Overview

Some API resource flows require calling more than one service and combining the responses into a single response. This is often called "mashing up" service calls.

In this lab, you call a third-party service, extract data, and add the data to the target's API response.

Objectives

In this lab, you learn how to perform the following tasks:

• Use a ServiceCallout policy to call a service.
• Use custom JavaScript code to combine API responses.

Setup

For each lab, you get a new Google Cloud project and set of resources for a fixed time at no cost.

1. Sign in to Qwiklabs using an incognito window.

2. Note the lab's access time (for example, 1:15:00), and make sure you can finish within that time.
   There is no pause feature. You can restart if needed, but you have to start at the beginning.

3. When ready, click Start lab.

4. Note your lab credentials (Username and Password). You will use them to sign in to the Google Cloud Console.

5. Click Open Google Console.

6. Click Use another account and copy/paste credentials for this lab into the prompts.
   If you use other credentials, you'll receive errors or incur charges.

7. Accept the terms and skip the recovery resource page.

Activate Google Cloud Shell

Google Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud.

Google Cloud Shell provides command-line access to your Google Cloud resources.

1. In Cloud console, on the top right toolbar, click the Open Cloud Shell button.

   

2. Click Continue.

It takes a few moments to provision and connect to the environment. When you are connected, you are already authenticated, and the project is set to your PROJECT_ID. For example:

gcloud is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.

• You can list the active account name with this command:

gcloud auth list

Output:

Credentialed accounts: - @.com (active)

Example output:

Credentialed accounts: - google1623327_student@qwiklabs.net

• You can list the project ID with this command:

gcloud config list project

Output:

[core] project =

Example output:

[core] project = qwiklabs-gcp-44776a13dea667a6 Note: Full documentation of gcloud is available in the gcloud CLI overview guide .

Preloaded assets

These assets have already been added to the Apigee organization:

• The retail-v1 API proxy
• The oauth-v1 API proxy (for generating OAuth tokens)
• The TS-Retail target server in the eval environment (used by retail-v1)

These assets will be added to the Apigee organization as soon as the runtime is available:

• The API products, developer, and developer app (used by retail-v1)
• The ProductsKVM key value map in the eval environment (used by retail-v1)
• The ProductsKVM key value map entries backendId and backendSecret

The highlighted items are used during this lab.

Note: Revision 1 of the retail-v1 proxy is marked as deployed, and is immutable. If you ever make a mistake in your proxy code that you can't recover from, you can select revision 1 and restart editing from there.

Task 1. Call a Google geocoding API

In this task, you use a ServiceCallout policy to call a Google Maps geocoding API to get a street address by latitude and longitude.

Understanding the stores resource

A list of stores may be retrieved by using GET /stores.

The beginning of the GET /stores response is:

{ "benbrook": { "affiliate": "Walsample", "location": { "latitude": 32.677649, "longitude": -97.465539 }, "name": "Bensample", "phone": "682-233-6820", "site_type": "store" }, "central-warehouse-1": { "affiliate": "Walsample", "location": { "latitude": 36.315127, "longitude": -94.12623 }, "name": "Central Warehouse-1", "phone": "479-633-0769", "site_type": "warehouse" }, "mall": {

The first store has the ID benbrook. GET /stores/benbrook returns:

{ "affiliate": "Walsample", "location": { "latitude": 32.677649, "longitude": -97.465539 }, "name": "Bensample", "phone": "682-233-6820", "site_type": "store" }

This request is handled by the getStoreById conditional flow. The latitude and longitude must be extracted from the location object.

You will modify the GET /stores/{storeId} API call to add the street address corresponding to the store's latitude and longitude.

Pin the Apigee console page

1. In the Google Cloud console, on the Navigation menu (), look for Apigee in the Pinned Products section.

   The Apigee console page will open.

2. If Apigee is not pinned, search for Apigee in the top search bar and navigate to the Apigee service.

3. Hover over the name, then click the pin icon ().

   The Apigee console page will now be pinned to the Navigation menu.

Extract the latitude and longitude from backend response

1. On the left navigation menu, select Proxy development > API proxies.

2. Select the retail-v1 proxy.

3. Click the Develop tab.

   You are modifying the version of the retail-v1 proxy that was created during Labs 1 through 7.

4. In the Navigator menu, click Proxy endpoints > default > getStoreById.

5. On the Response getStoreById flow, click Add Policy Step (+).

   

6. In the Add policy step pane, select Create new policy, and then select Mediation > Extract Variables.

7. Specify the following values:

   Property	Value
   Name	EV-ExtractLatLng
   Display name	EV-ExtractLatLng

8. Click Add.

9. Click Policies > EV-ExtractLatLng.

10. Set the policy configuration to extract the latitude and longitude into variables:

    <ExtractVariables continueOnError="false" enabled="true" name="EV-ExtractLatLng"> <JSONPayload> <Variable name="lat"> <JSONPath>$.location.latitude</JSONPath> </Variable> <Variable name="lng"> <JSONPath>$.location.longitude</JSONPath> </Variable> </JSONPayload> <Source clearPayload="false">response</Source> </ExtractVariables>

    This uses JSONPath to extract the latitude and longitude from the location object and store them in the variables lat and lng.

Call the geocoding service

The service callout calls the Google Geocoding API, passing the latitude and longitude variables to the API.

Property	Value
Geocoding API Key	API-ENG-TRAINING-GEOCODING-KEY
Geocoding API URL	https://gcp-cs-training-01-prod.apigee.net/googleapis/maps/api/geocode/json

Note: This lab will call a proxied version of the Google Maps Geocoding API that only supports the latitudes and longitudes for the stores. It uses an API key that cannot be used directly with the Geocoding API.

If you want to create a Google Maps API key of your own (which requires a billing account) follow the directions on the Get Started documentation. You could then replace the key and the URL to call the Google Maps API directly.

1. Open a new browser tab and make a call directly to the API, using this URL for the benbrook location:

   https://gcp-cs-training-01-prod.apigee.net/googleapis/maps/api/geocode/json?latlng=32.677649,-97.465539&key=API-ENG-TRAINING-GEOCODING-KEY

   The latlng query parameter contains the latitude and longitude, separated by a comma. The API key is passed in the key query parameter.

   The response field formatted_address will be accessed using JSONPath. The first entry of the results array will be used. The JSONPath location is:

   $.results[0].formatted_address

2. Click Proxy endpoints > default > getStoreById.

3. On the Response getStoreById flow, click Add Policy Step (+).

4. In the Add policy step pane, select Create new policy, and then select Extension > Service Callout.

5. Specify the following values:

   Property	Value
   Name	SC-GoogleGeocode
   Display name	SC-GoogleGeocode

   Leave the HTTP Target unchanged.

6. Click Add.

7. Click Policies > SC-GoogleGeocode.

   The new policy should follow the EV-ExtractLatLng policy, which means that it will be executed after the ExtractVariables policy.

8. Change the configuration for the SC-GoogleGeocode policy to call the same location you called in the browser:

   <ServiceCallout continueOnError="false" enabled="true" name="SC-GoogleGeocode"> <Request> <Set> <QueryParams> <QueryParam name="latlng">{lat},{lng}</QueryParam> <QueryParam name="key">API-ENG-TRAINING-GEOCODING-KEY</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> </Request> <Response>calloutResponse</Response> <HTTPTargetConnection> <URL>https://gcp-cs-training-01-prod.apigee.net/googleapis/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>

   The response from the API call is stored in an object named calloutResponse.

Extract the formatted address

1. Click Proxy endpoints > default > getStoreById.

2. On the Response getStoreById flow, click Add Policy Step (+).

3. In the Add policy step pane, select Create new policy, and then select Mediation > Extract Variables.

4. Specify the following values:

   Property	Value
   Name	EV-ExtractAddress
   Display name	EV-ExtractAddress

5. Click Add.

6. Click Policies > EV-ExtractAddress.

7. Change the configuration for EV-ExtractAddress:

   <ExtractVariables continueOnError="false" enabled="true" name="EV-ExtractAddress"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <JSONPayload> <Variable name="address"> <JSONPath>$.results[0].formatted_address</JSONPath> </Variable> </JSONPayload> <Source clearPayload="false">calloutResponse.content</Source> </ExtractVariables>

   The response payload from the geocoding API call is the source, and the address from the response is stored in a variable named address.

8. Click Save, and then click Save as New Revision.

9. Click Deploy.

10. To specify that you want the new revision deployed to the eval environment, select eval as the Environment, and then click Deploy.

11. Click Confirm.

Check deployment status

A proxy that is deployed and ready to take traffic will show a green status on the Overview tab.

When a proxy is marked as deployed but the runtime is not yet available and the environment is not yet attached, you may see a red warning sign. Hold the pointer over the Status icon to see the current status.

If the proxy is deployed and shows as green, your proxy is ready for API traffic. If your proxy is not deployed because there are no runtime pods, you can check the provisioning status.

Check provisioning status

• In Cloud Shell, to confirm that the runtime instance has been installed and the eval environment has been attached, run the following commands:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***";

  When the script returns ORG IS READY TO USE, you can proceed to the next steps.

While you are waiting

While you wait, explore the following:

• ServiceCallout policy
• JavaScript policy
• Google Geocoding Service
• JSONPath syntax
• JSONPath Online Evaluator

Task 2. Verify that the address variable is populated

In this task, you use the debug tool to verify that the formatted address is retrieved from the geocoding API and extracted into the address variable.

1. On the left navigation menu, select Proxy development > API proxies, and then select the retail-v1 proxy.
2. Click the Debug tab, and then click Start Debug Session.
3. In the Start debug session pane, on the Environment dropdown, select eval.
4. Click Start.

Test the API proxy using private DNS

The eval environment in the Apigee organization can be called using the hostname eval.example.com. The DNS entry for this hostname has been created within your project, and it resolves to the IP address of the Apigee runtime instance. This DNS entry has been created in a private zone, which means it is only visible on the internal network.

Cloud Shell does not reside on the internal network, so Cloud Shell commands cannot resolve this DNS entry. A virtual machine (VM) within your project can access the private zone DNS. A virtual machine named apigeex-test-vm was automatically created for this purpose. You can make API proxy calls from this machine.

The curl command will be used to send API requests to an API proxy. The -k option for curl tells it to skip verification of the TLS certificate. For this lab, the Apigee runtime uses a self-signed certificate. For a production environment, you should use certificates that have been created by a trusted certificate authority (CA).

1. In Cloud Shell, open a new tab, and then open an SSH connection to your test VM:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   The first gcloud command retrieves the zone of the test VM, and the second opens the SSH connection to the VM.

2. If asked to authorize, click Authorize.

   For each question asked in the Cloud Shell, click Enter or Return to specify the default input.

   Your logged in identity is the owner of the project, so SSH to this machine is allowed.

   Your Cloud Shell session is now running inside the VM.

Store the app's key in a shell variable

The API key may be retrieved directly from the app accessible on the Publish > Apps page. It can also be retrieved via Apigee API call.

• In the Cloud Shell SSH session, run the following command:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}" export API_KEY=$(curl -q -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/retail-app" | jq --raw-output '.credentials[0].consumerKey'); echo "export API_KEY=${API_KEY}" >> ~/.bashrc; echo "API_KEY=${API_KEY}"

  This command retrieves a Google Cloud access token for the logged-in user, sending it as a Bearer token to the Apigee API call. It retrieves the retail-app app details as a JSON response, which is parsed by jq to retrieve the app's key. That key is then put into the API_KEY environment variable, and the export command is concatenated onto the .bashrc file which runs automatically when starting a the SSH session.

  Note: If you run the command and it shows API_KEY=null, the runtime instance is probably not yet available.

Debug the API

1. To get the store by ID, run this curl command in Cloud Shell:

   curl -i -k -X GET -H "apikey:${API_KEY}" "https://eval.example.com/retail/v1/stores/benbrook"

2. In Debug, click on the GET request, and then click EV-ExtractAddress.

   If you have successfully extracted the latitude and longitude, called the geocoding API, and extracted the formatted address, the address variable will be populated.

   

Task 3. Add the address to the target response

In this task, you use a JavaScript policy to insert the address into the target response.

Begin by adding a JavaScript policy that is executed after EV-ExtractAddress in the getStoreById flow.

1. Click Proxy endpoints > default > getStoreById.

2. On the Response getStoreById flow, click Add Policy Step (+).

3. In the Add policy step pane, select Create new policy, and then select Extension > Javascript.

4. Specify the following values:

   Property	Value
   Name	JS-AddAddress
   Display name	JS-AddAddress

5. For Javascript file, select Create New Resource.

6. For Resource name, specify addAddress.js.

7. Click Add.

8. For Javascript file, select addAddress.js.

9. Click Add.

   The four policies in the getStoreById response flow should look like this:

   

   The JavaScript policy configuration does not need to be changed.

10. In the Navigator pane, click Resources > jsc > addAddress.js.

    The code pane contains the addAddress.js Javascript code. It is currently empty.

11. To combine the responses, use this Javascript code:

    // get the flow variable 'address' var address = context.getVariable('address'); // parse the response payload into the responsePayload object var responsePayload = JSON.parse(context.getVariable('response.content')); try { // add address to the response responsePayload.address = address; // convert the response object back into JSON context.setVariable('response.content', JSON.stringify(responsePayload)); context.setVariable('mashupAddressSuccess', true); } catch(e) { // catch any exception print('Error occurred when trying to add the address to the response.'); context.setVariable('mashupAddressSuccess', false); }

    This code parses the JSON response payload into an object, adds an address field to the object, and converts the object back into a JSON string, storing it in the response.

    try/catch is used so that an exception isn't thrown out of the JavaScript policy. A fault is raised if an exception isn't caught.

12. Click Save, and then click Save as New Revision.

13. Click Deploy.

14. To specify that you want the new revision deployed to the eval environment, click Deploy, and then click Confirm.

Task 4. Verify that the address is returned in the response

In this task, you verify that the API call returns the address in the response payload.

• In the Cloud Shell SSH session, to get the store by ID, run the following command:

  curl -i -k -X GET -H "apikey:${API_KEY}" "https://eval.example.com/retail/v1/stores/benbrook"

  The response now should include the address:

  { "address" : "6008 Benbrook Blvd, Benbrook, TX 76126, USA", "affiliate" : "Walsample", "location" : { "latitude" : 32.677649, "longitude" : -97.465539 }, "name" : "Bensample", "phone" : "682-233-6820", "site_type" : "store" }

  If the address field is not in the response, use the debug tool to determine what is not working.

Congratulations!

In this lab, you mashed up the responses from two calls into a single response, adding a feature to your API proxy without modifying the backend service.

End your lab

When you have completed your lab, click End Lab. Google Cloud Skills Boost removes the resources you’ve used and cleans the account for you.

You will be given an opportunity to rate the lab experience. Select the applicable number of stars, type a comment, and then click Submit.

The number of stars indicates the following:

• 1 star = Very dissatisfied
• 2 stars = Dissatisfied
• 3 stars = Neutral
• 4 stars = Satisfied
• 5 stars = Very satisfied

You can close the dialog box if you don't want to provide feedback.

For feedback, suggestions, or corrections, please use the Support tab.

Copyright 2022 Google LLC All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.