GSP845

Overview

Apigee is a platform for developing and managing APIs. Apigee can help you leverage Google Cloud services like Pub/Sub, Cloud Logging, or any other cloud service providing a REST API. In this lab, your Apigee API proxy leverages several Google Cloud services.

In this lab, you use multiple Google Cloud services from an Apigee API proxy to handle user comments.

Objectives

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

• Enable required Google Cloud APIs
• Create a service account and apply the correct roles
• Call a Google Cloud service using the Google Cloud REST API
• Perform sentiment analysis by calling the Cloud Natural Language API
• Publish a Pub/Sub message using the PublishMessage policy
• Log error messages to Cloud Logging

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources are made available to you.

This hands-on lab lets you do the lab activities in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

• Time to complete the lab—remember, once you start, you cannot pause a lab.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the left is the Lab Details pane with the following:

   • The Open Google Cloud console button
   • Time remaining
   • The temporary credentials that you must use for this lab
   • Other information, if needed, to step through this lab

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab Details pane.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab Details pane.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To access Google Cloud products and services, click the Navigation menu or type the service or product name in the Search field.

Activate Cloud Shell

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. Cloud Shell provides command-line access to your Google Cloud resources.

1. Click Activate Cloud Shell at the top of the Google Cloud console.

2. Click through the following windows:

   • Continue through the Cloud Shell information window.
   • Authorize Cloud Shell to use your credentials to make Google Cloud API calls.

When you are connected, you are already authenticated, and the project is set to your Project_ID, . The output contains a line that declares the Project_ID for this session:

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

3. (Optional) You can list the active account name with this command:

4. Click Authorize.

Output:

5. (Optional) You can list the project ID with this command:

Output:

Task 1. Enable Google Cloud APIs

In this task, you enable the APIs that will be used by the Apigee API proxy.

1. In the Cloud Console, on the Navigation menu (), navigate to APIs & Services > Library.

   This page allows you to enable the APIs that will be used by the Apigee API proxy.

2. In the Search for APIs & Services box, enter Cloud Natural Language and click Enter.

   The Cloud Natural Language API provides natural language insights such as sentiment analysis and entity recognition. This API will be used to determine when a comment indicates a user is unhappy.

3. Click Cloud Natural Language API.

   The API is already enabled.

   The gcloud command can also be used to enable APIs.

4. In Cloud Shell, to enable the required APIs, use the following command:

   gcloud services enable language.googleapis.com pubsub.googleapis.com logging.googleapis.com

   In addition to the Cloud Natural Language API, you are also enabling the Pub/Sub API and the Cloud Logging API.

   Pub/Sub will be used to publish a message to a topic when the Natural Language API indicates that a user is unhappy. You might choose to create a Cloud Function that runs for each message, contacting the user in an attempt to solve the problem and improve customer satisfaction.

   Cloud Logging will be used to capture a log entry for each comment that is received. These logs could include internal API details that might help detect issues with services or applications.

Task 2. Create a service account

In this task, you create a service account to be used by the Apigee proxy.

Create the IAM service account

1. From the Navigation menu (), navigate to IAM & Admin > Service Accounts.

2. Click + Create Service Account.

3. For Service account name, specify the following:

   apigee-gc-service-access

   This service account will allow your Apigee API proxy to access the Google Cloud services you specify.

4. Click Create and Continue.

5. For Select a role, select Pub/Sub > Pub/Sub Publisher.

   The Apigee API proxy will publish to a Pub/Sub topic.

6. Click + Add Another Role.

7. For Select a role, select Logging > Logs Writer.

   The Apigee API proxy will write log messages to Cloud Logging.

8. Click Done.

   The service account has been created.

Click Check my progress to verify the objective. Create the service account and assign roles

Task 3. Create an API proxy

In this task, you create the Apigee API proxy. The API proxy will use policies to call services, so no target will be required.

Open the Apigee console

To open the Apigee console:

• In the Google Cloud console, in the Search field, enter Apigee, and then click Apigee API Management in the search results.

The Apigee console opens, and the landing page shows quick links to commonly used locations.

• In the Navigation menu (), next to Apigee, click Pin ().

Apigee is now pinned to the Navigation menu.

Create the Apigee API proxy

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

2. To create a new proxy using the proxy wizard, click Create.

3. For Proxy template, select General template > No target.

   The proxy will not use a backend service. All communication with external services will be done using policies.

4. Specify the following for the Proxy details:

   Property	Value
   Proxy name	services-v1
   Base path	/services/v1

   Note: Confirm that you are using /services/v1 for the base path, not /services-v1.

5. Click Next.

6. Leave the Deploy (optional) settings at their defaults, and click Create.

Create a new conditional flow

1. Click the Develop tab in the Proxy Editor.

2. Select Proxy endpoints > default in the left-hand pane.

3. Click the + button above the Response pane.

4. In the Add conditional flow dialog, specify the following values:

   Property	Value
   Flow Name	postComment
   Description	post a comment for a particular category
   Condition Type	select Path and Verb
   Path	/comments
   Verb	select POST

   Leave Target URL blank.

5. Click Add, and then click Save.

Click Check my progress to verify the objective. Create the API proxy

Task 4. Call the Natural Language API

In this task, you add a ServiceCallout policy to call the Natural Language API to determine the sentiment of an incoming comment.

Extract input parameters

The POST /comments resource will use a JSON payload with two parameters: comment, the free text entered by a user, and category, which specifies the type of comment. An ExtractVariables policy will extract the inputs.

1. In the Flow pane, click the + next to postComment flow in the Request pane.

2. In the Add policy step dialog, click Create new policy.

3. In the Select Policy dropdown, select Extract Variables policy type from the Mediation section.

4. Specify the following:

   Property	Value
   Display Name	EV-ExtractRequest
   Name	EV-ExtractRequest

5. Click Add.

6. Click EV-ExtractRequest policy and replace the ExtractVariables XML configuration with:

This policy extracts the comment and category from the POST /comments JSON request. The IgnoreUnresolvedVariables element is set to false, which causes a fault to be raised if those two inputs are not specified.

Call the Natural Language API

A ServiceCallout policy will be used to call the Natural Language API to return the sentiment for the comment.

1. Click the postComment flow if it is not highlighted and then click the + next to postComment flow in the Response pane.

   The response from the Natural Language API call will be returned to the caller.

2. In the Add policy step dialog, click Create new policy.

3. In the Select Policy dropdown, select Service Callout policy type from the Extension section.

4. Specify the following:

   Property	Value
   Display Name	SC-NaturalLanguage
   Name	SC-NaturalLanguage

5. Click Add.

   The flow should look similar to this:

   

6. Click the SC-NaturalLanguage policy.

7. Replace the ServiceCallout XML configuration with:

   <ServiceCallout name="SC-NaturalLanguage"> <Request clearPayload="true"> <Set> <Verb>POST</Verb> <Payload contentType="application/json">{ "document": { "content": "{comment}", "type": "PLAIN_TEXT" } } </Payload> </Set> </Request> <Response>response</Response> <HTTPTargetConnection> <Properties/> <URL>https://language.googleapis.com/v1/documents:analyzeSentiment</URL> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-language</Scope> </Scopes> </GoogleAccessToken> </Authentication> </HTTPTargetConnection> </ServiceCallout>

   The Request section of the ServiceCallout policy specifies the request POSTed to the service. The format of this payload is specific to the Natural Language API.

   The Response element indicates that the Natural Language API response will be stored in the response message.

   The HTTPTargetConnection section specifies the service URL that is being called. The URL and the request and response formats can be found in Natural Language API reference.

   The Authentication section specifies the authentication for the Google Cloud API. A Google OAuth access token will be automatically added to the callout request. The Scope specifies that the access token will be used to provide access to the Natural Language API.

8. Click Save.

Confirm that the runtime instance is available

• In Cloud Shell, paste and run the following set of commands:

  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/${GOOGLE_CLOUD_PROJECT}/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/${GOOGLE_CLOUD_PROJECT}/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***";

  This series of commands uses the Apigee API to determine when the Apigee runtime instance has been created and the eval environment has been attached.

Wait until the instance is ready.

When the text ***ORG IS READY TO USE*** is displayed, the instance is ready. The Apigee organization (org) may have been created before you started the lab, so you might not have to wait for the instance to be created.

If you are waiting for the org to be ready, you can explore the AI products and services on Google Cloud.

Deploy the API

1. Return to the services-v1 API proxy, and click the Develop tab.

2. Click Deploy.

3. For Environment select eval.

4. For Service Account, specify the service account's email address:

   apigee-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Click Deploy and Confirm.

6. Click the Overview tab, and wait for the eval deployment status to show that the proxy has been deployed.

Click Check my progress to verify the objective. Call the Natural Language API

Test the API

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. You can use this machine to call the API proxy.

1. In Cloud Shell, 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

   If asked Do you want to continue (Y/n)?, enter Y.

2. 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.

3. Call the deployed services-v1 API proxy in the eval environment:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"Jane was nice enough to return to her car to get me extra hot sauce. Thanks Jane!", "category":"delivery-reviews"}'

   The response from the Natural Language API looks like this:

The documentSentiment score ranges from 1 to -1, with 1 being extremely positive, and -1 being extremely negative. In this case, the sentiment is very positive.

4. Make another call to the API proxy:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"delivery-reviews"}'

   For this comment, the sentiment is quite negative.

5. Enter the command exit to leave the SSH session and return to Cloud Shell.

Task 5. Publish a message to Pub/Sub for negative comments

In this task, you add a PublishMessage policy to publish a Pub/Sub message to a Pub/Sub topic whenever a negative comment is received. A subscriber to the topic could run a workflow that attempts to solve the problem for the commenter.

Create a Pub/Sub topic for delivery reviews

A Pub/Sub topic will be created to correspond with each category. A topic must be created before a message may be published to the topic.

1. In the Navigation menu (), navigate to Pub/Sub > Topics.

2. Click + Create Topic.

3. For the topic ID, enter apigee-services-v1-delivery-reviews, and then click Create.

   A new topic and subscription is created.

Extract the score from the Natural Language API response

1. Return to the Apigee in the cloud console.

2. On the left navigation menu, select Proxy development > API Proxies and then click services-v1.

3. Open Develop tab. Click the postComment flow.

4. In the Flow pane, click the + next to postComment flow in the Response pane.

5. In the Add policy step dialog, click Create new policy.

6. In the Select Policy dropdown, select Extract Variables policy type from the Mediation section.

7. Specify the following:

   Property	Value
   Display Name	EV-ExtractSentiment
   Name	EV-ExtractSentiment

8. Click Add, and then click the EV-ExtractSentiment policy.

9. Replace the ExtractVariables XML configuration with:

   <ExtractVariables name="EV-ExtractSentiment"> <Source>response</Source> <JSONPayload> <Variable name="sentimentScore"> <JSONPath>$.documentSentiment.score</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

Add a PublishMessage policy

1. Click the postComment flow, and then click the + button below the Response flow.

2. In the Extension section, select the Publish Message policy type.

3. Specify the following:

   Property	Value
   Display Name	PM-PublishScore
   Name	PM-PublishScore

4. Click Add, and then click the PM-PublishScore policy.

5. Replace the PublishMessage XML configuration with:

   <PublishMessage continueOnError="true" name="PM-PublishScore"> <Source>{response.content}</Source> <CloudPubSub> <Topic>projects/{organization.name}/topics/apigee-services-v1-{category}</Topic> </CloudPubSub> </PublishMessage>

6. Click Save. If you are notified that the proxy was saved as a new revision, click Save as new revision.

   The response.content is the payload that was returned by the Natural Language API, and will be the Pub/Sub message. The category from the request is used to build the Pub/Sub topic name.

   Any categories that are incorrect will result in a topic name that does not exist. In a production API, you would want to verify categories that are specified before trying to publish a Pub/Sub message. In this case, continueOnError is set to true on the policy, so, when the topic does not exist, a fault will not be raised.

Add conditional check for the PublishMessage policy

Conditions can be used to optionally skip policies in a flow.

1. In the proxy Navigator menu, under Proxy Endpoints, click default.

   The ProxyEndpoint configuration is shown.

2. To add a condition to the PM-PublishScore step, replace this:

with this:

The PublishMessage policy will only execute when the sentiment score is less than 0.

Deploy the API

1. Click Save. If you are notified that the proxy was saved as a new revision, click Save as new revision.

2. Click Deploy.

3. For Environment select eval.

4. For Service Account, specify the service account's email address:

   apigee-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Click Deploy and Confirm.

Click Check my progress to verify the objective. Publish a message to Pub/Sub for negative comments

Test the API

1. In Cloud Shell, 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

   If asked to authorize, click Authorize.

2. Call the deployed services-v1 API proxy in the eval environment:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"delivery-reviews"}'

3. From the Navigation menu (), navigate to Pub/Sub > Topics.

4. Click the apigee-services-v1-delivery-reviews topic.

5. Scroll down to the bottom, and then click on the apigee-services-v1-delivery-reviews-sub subscription.

6. Click the Messages tab, and then click Pull.

7. In the message, click the View all row content dropdown button.

   You can see the JSON payload that was sent for any comments with negative sentiment.

Task 6. Add a MessageLogging policy

In this task, you add a MessageLogging policy to log a message to Cloud Logging.

Create a PostClientFlow

A ProxyEndpoint has an optional flow called the PostClientFlow. Policies attached to this flow run after the response has already been returned to the caller. This can be an ideal location to perform message logging, because the logging would add no additional latency to the request.

1. Return to the Apigee tab and, if necessary, return to the services-v1 Develop page.

2. In the proxy Navigator menu, under Proxy Endpoints, click default.

   The ProxyEndpoint configuration is shown.

3. Immediately above the HTTPProxyConnection section, add the following line:

   <PostClientFlow/>

   After adding this line, the bottom of your ProxyEndpoint code should resemble this:

This adds an empty PostClientFlow to the ProxyEndpoint.

Add a MessageLogging policy

1. In the proxy Navigator menu, under Proxy Endpoints, click PostClientFlow, and then click the + button below the Response flow.

2. In the Add policy step dialog, click Create new policy.

3. In the Select Policy dropdown, select Message Logging policy type from the Extension section.

4. Specify the following:

   Property	Value
   Display Name	ML-LogToCloudLogging
   Name	ML-LogToCloudLogging

5. Click Add, and then click the ML-LogToCloudLogging policy.

6. Replace the PublishMessage XML configuration with:

   <MessageLogging name="ML-LogToCloudLogging"> <CloudLogging> <LogName>projects/{organization.name}/logs/apiproxy-{apiproxy.name}</LogName> <Message contentType="application/json">{ "messageid": "{messageid}", "environment": "{environment.name}", "apiProxy": "{apiproxy.name}", "proxyRevision": "{apiproxy.revision}", "uri": "{request.uri}", "statusCode": "{response.status.code}", "category": "{category}", "score": "{sentimentScore}", "publishFailed": "{publishmessage.failed}" }</Message> <Labels> <Label> <Key>proxyName</Key> <Value>services-v1</Value> </Label> </Labels> </CloudLogging> </MessageLogging>

   The CloudLogging section specifies the information to be logged to Cloud Logging. The policy uses the name of the proxy as part of the LogName, which makes it easy to find in Cloud Logging.

   The message in this policy is a JSON message, but any type of text message can be used in your logs. The contents of your logs should typically include proxy flow variables that would help you debug any issues. For example, the variable publishmessage.failed will be true if the Pub/Sub message was not sent.

   Labels can also be added to the logged message to categorize the message contents.

Deploy the API

1. Click Save. If you are notified that the proxy was saved as a new revision, click Save as new revision.

2. Click Deploy.

3. For Environment select eval.

4. For Service Account, specify the service account's email address:

   apigee-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Click Deploy and Confirm.

   Wait for the deployment to complete.

Click Check my progress to verify the objective. Add the MessageLogging policy

Test the API

1. In Cloud Shell, if your SSH connection has closed, open the 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

   If asked to authorize, click Authorize.

2. Call the deployed services-v1 API proxy in the eval environment:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"invalid-category"}'

   The category supplied (invalid-category) does not have a corresponding Pub/Sub topic.

3. From the Navigation menu (), navigate to Logging > Logs Explorer.

4. In the Query box, enter the following query:

   "invalid-category"

5. Click Run query.

6. Expand the log entry in the Query Results pane, and then expand the jsonPayload.

Expanding the log entry shows the logged JSON message and other metadata. The jsonPayload should resemble this:

publishFailed is true because there wasn't a topic created for this category. Well-designed logs can help find issues in your API proxies and backend services.

Congratulations!

In this lab, you enabled Google Cloud APIs, and created a service account. You called the Cloud Natural Language API by using a ServiceCallout policy, leveraging the service account authentication provided by Apigee. You used the PublishMessage policy to publish a message to a Pub/Sub topic. Finally, you used the MessageLogging policy to log a message to Cloud Logging.

Next steps / Learn more

• Pub/Sub
• Cloud Logging
• AI and Machine Learning products, including the Cloud Natural Language API

Manual last updated January 27, 2025

Manual last tested January 27, 2025

Copyright 2025 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.