检查点
Create the service account and assign roles
/ 20
Create the API proxy
/ 20
Call the Natural Language API
/ 20
Publish a message to Pub/Sub for negative comments
/ 20
Add the MessageLogging policy
/ 20
Using Google Cloud Services with Apigee X
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 will be made available to you.
This hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that 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
-
Click the Start Lab button. If you need to pay for the lab, a pop-up opens for you to select your payment method. On the left is the Lab Details panel 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
-
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. -
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 panel.
-
Click Next.
-
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 panel.
-
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. -
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.
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.
- Click Activate Cloud Shell at the top of the Google Cloud console.
When you are connected, you are already authenticated, and the project is set to your Project_ID,
gcloud
is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.
- (Optional) You can list the active account name with this command:
- Click Authorize.
Output:
- (Optional) You can list the project ID with this command:
Output:
gcloud
, in Google Cloud, refer to the gcloud CLI overview guide.
Open the Apigee UI
The Apigee UI is accessed on a page separate from the Google Cloud Console. This lab has automatically created an Apigee organization that has the same name as the Google Cloud project.
-
Click to open the Apigee UI.
You may also open the Apigee UI from the Google Cloud Console by opening the Navigation menu () click View All Products under Integration Services select Apigee.
If you see an error indicating that the project does not have an organization provisioned, the tab might be trying to load the organization for a previous lab.
If you get this error:
-
Click on the organization dropdown.
The organization dropdown should show an organization that has the same name as the Google Cloud project.
The organizations listed are those that are accessible by the logged-in user. For this lab, you should be logged in with the lab credentials provided in the Lab Details panel when you started the lab.
You can navigate the Apigee UI using its left navigation menu. The landing page also shows quick links for navigating to commonly used locations.
Task 1. Enable Google Cloud APIs
In this task, you enable the APIs that will be used by the Apigee API proxy.
-
In the Cloud Console tab, 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.
-
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.
-
Click Cloud Natural Language API.
The API is already enabled.
The
gcloud
command can also be used to enable APIs. -
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
-
In the Cloud Console tab, on the Navigation menu (), navigate to IAM & Admin > Service Accounts.
-
Click + Create Service Account.
-
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.
-
Click Create and Continue.
-
For Select a role, select Pub/Sub > Pub/Sub Publisher.
The Apigee API proxy will publish to a Pub/Sub topic.
-
Click + Add Another Role.
-
For Select a role, select Logging > Logs Writer.
The Apigee API proxy will write log messages to Cloud Logging.
-
Click Done.
The service account has been created.
Click Check my progress to verify the objective.
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.
Create the Apigee API proxy
-
Select the Apigee UI tab in your browser window.
-
On the left navigation menu, select Develop > API Proxies.
-
To create a new proxy using the proxy wizard, click Create New.
-
Click the No target box.
The proxy will not use a backend service. All communication with external services will be done using policies.
-
Specify the following for the Proxy details:
Property Value Name services-v1 Base path /services/v1 Note: Confirm that you are using /services/v1
for the base path, not/services-v1
. -
Click Next.
-
Leave the Common Policies settings at their defaults, and click Next.
-
On the summary page, leave the settings at their defaults, and click Create.
-
Click Edit proxy.
-
If a Switch to Classic link is in the upper right corner, click that link.
Create a new conditional flow
-
Click the Develop tab.
-
In the Navigator menu for the API proxy, inside the Proxy Endpoints section, on the line with default, click +.
-
In the New 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 Optional Target URL blank.
-
Click Add, and then click Save.
Click Check my progress to verify the objective.
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.
-
Click the postComment flow if it is not highlighted, and then click the + Step button in the upper right above the Request flow.
-
In the Mediation section, select the Extract Variables policy type.
-
Specify the following:
Property Value Display Name EV-ExtractRequest Name EV-ExtractRequest -
Click Add.
-
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.
-
Click the postComment flow if it is not highlighted, and then click the + Step button in the lower left below the Response flow.
The response from the Natural Language API call will be returned to the caller.
-
In the Extension section, select the Service Callout policy type.
-
Specify the following:
Property Value Display Name SC-NaturalLanguage Name SC-NaturalLanguage -
Click Add.
The flow should look similar to this:
-
Click the SC-NaturalLanguage policy.
-
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.
-
Click Save. If you are notified that the proxy was saved as a new revision, click OK.
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
-
Return to the services-v1 API proxy, and click the Develop tab.
-
Click Deploy to eval.
A dialog asks you to confirm the deployment.
-
For Service Account, specify the service account's email address:
apigee-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com -
Click Deploy.
-
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.
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
In the Cloud Console tab, on the Navigation menu (), navigate to Pub/Sub > Topics.
-
Click + Create Topic.
-
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
-
Return to the Apigee UI tab and, if necessary, return to the services-v1 Develop page.
-
Click the postComment flow, and then click the + Step button in the lower left below the Response flow.
-
In the Mediation section, select the Extract Variables policy type.
-
Specify the following:
Property Value Display Name EV-ExtractSentiment Name EV-ExtractSentiment -
Click Add, and then click the EV-ExtractSentiment policy.
-
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
-
Click the postComment flow, and then click the + Step button in the lower left below the Response flow.
-
In the Extension section, select the Publish Message policy type.
-
Specify the following:
Property Value Display Name PM-PublishScore Name PM-PublishScore -
Click Add, and then click the PM-PublishScore policy.
-
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> 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.
-
In the proxy Navigator menu, under Proxy Endpoints, click default.
The ProxyEndpoint configuration is shown.
-
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
-
Click Save. If you are notified that the proxy was saved as a new revision, click OK.
-
Click Deploy to eval.
A dialog asks you to confirm the deployment.
-
Click Deploy, and then wait for the deployment to complete.
Click Check my progress to verify the objective.
Test the API
-
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.
-
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"}' -
In the Cloud Console tab, on the Navigation menu (), navigate to Pub/Sub > Topics.
-
Click the apigee-services-v1-delivery-reviews topic.
-
Scroll down to the bottom, and then click on the apigee-services-v1-delivery-reviews-sub subscription.
-
Click the Messages tab, and then click Pull.
-
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.
-
Return to the Apigee UI tab and, if necessary, return to the services-v1 Develop page.
-
In the proxy Navigator menu, under Proxy Endpoints, click default.
The ProxyEndpoint configuration is shown.
-
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
-
In the proxy Navigator menu, under Proxy Endpoints, click PostClientFlow, and then click the + Step button in the lower left below the Response flow.
-
In the Extension section, select the Message Logging policy type.
-
Specify the following:
Property Value Display Name ML-LogToCloudLogging Name ML-LogToCloudLogging -
Click Add, and then click the ML-LogToCloudLogging policy.
-
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
-
Click Save. If you are notified that the proxy was saved as a new revision, click OK.
-
Click Deploy to eval.
A dialog asks you to confirm the deployment.
-
Click Deploy, and then wait for the deployment to complete.
Click Check my progress to verify the objective.
Test the API
-
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.
-
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.
-
In the Cloud Console tab, on the Navigation menu (), navigate to Logging > Logs Explorer.
-
In the Query box, enter the following query:
"invalid-category" -
Click Run query.
-
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
Manual last updated July 10, 2024
Manual last tested July 10, 2024
Copyright 2024 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.