
Before you begin
- Labs create a Google Cloud project and resources for a fixed time
- Labs have a time limit and no pause feature. If you end the lab, you'll have to restart from the beginning.
- On the top left of your screen, click Start lab to begin
In this lab, you will create two target endpoints and conditionally route to them using route rules. You also learn how to troubleshoot your proxies using the Apigee Debug tool.
In this lab, you will learn how to perform the following tasks:
For each lab, you get a new Google Cloud project and set of resources for a fixed time at no cost.
Sign in to Qwiklabs using an incognito window.
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.
When ready, click Start lab.
Note your lab credentials (Username and Password). You will use them to sign in to the Google Cloud Console.
Click Open Google Console.
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.
Accept the terms and skip the recovery resource page.
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.
In Cloud console, on the top right toolbar, click the Open Cloud Shell button.
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.
Output:
Example output:
Output:
Example output:
In this task, you create a new API proxy that calls the retail backend.
In the Google Cloud console, on the Navigation menu (), look for Apigee in the Pinned Products section.
The Apigee console page will open.
If Apigee is not pinned, search for Apigee in the top search bar and navigate to the Apigee service.
Hover over the name, then click the pin icon ().
The Apigee console page will now be pinned to the Navigation menu.
On the left navigation menu, select Proxy development > API proxies.
To start the proxy wizard, click +Create.
For Proxy template, select Reverse proxy (Most common).
Specify the following settings:
Property | Value |
---|---|
Proxy Name | lab2a-v1 |
Base path | /lab2a/v1 |
Target (Existing API) | https://gcp-cs-training-01-test.apigee.net/training/db |
/lab2a/v1
for the base path, and not /lab2a-v1
.
Click Create.
Click the Develop tab.
In this task, you create a new target endpoint and route rule to call a new backend service.
In the Navigator pane, click the Add target endpoint (+) button for Target endpoints.
In the Add target endpoint pane, specify the following values:
Property | Value |
---|---|
Target endpoint name | uuid_service |
HTTP target | https://httpbin.org/uuid |
This service returns a UUID.
Click Add.
The uuid_service
target endpoint appears in the code pane. Functionality that is specific to the target should be placed in the target endpoint flows.
In the Navigator pane, click Proxy endpoints > default.
The default ProxyEndpoint configuration is displayed in the code box. Examine the RouteRule
section in the proxy endpoint.
When we created the proxy, it had only a single target endpoint. The single route rule routes all traffic to the default target endpoint because there is no condition for the route rule. We need to add a route rule to conditionally route to the uuid_service
target endpoint.
Replace the following:
with:
This new route rule routes to the uuid_service
target endpoint if the proxy's path suffix is /uuid.
Click Save. If you are notified that the proxy was saved as a new revision.
Click Deploy.
To specify that you want the new revision deployed to the eval environment, select eval as the Environment, and then click Deploy.
Click Confirm.
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.
In Cloud Shell, to confirm that the runtime instance has been installed and the eval environment has been attached, run the following commands:
When the script returns ORG IS READY TO USE
, you can proceed to the next steps.
Take note of the following:
In this task, you call each service.
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).
In Cloud Shell, open a new tab, and then open an SSH connection to your test VM:
The first gcloud command retrieves the zone of the test VM, and the second opens the SSH connection to the VM.
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.
To make a call to proxy hosted in the eval environment, in the Cloud Shell SSH session, send a request to your API proxy by using this command:
The curl command responds with a JSON array of category objects.
Now, send the following curl command:
When you changed the proxy suffix to /uuid, you probably expected the uuid_service target to be called. Instead, you see an HTML error.
To directly call the backend service you were intending to call, open another tab in your browser, and navigate to the URL you used in the uuid_service
target endpoint:
Opening a web page uses a GET verb, and this URL successfully returns a JSON payload with a UUID.
Something must be going wrong. How do you determine what is happening?
In this task, you explore how to use the debug tool to debug API proxy issues.
In the proxy wizard, select the Debug tab.
Click Start Debug Session.
In the Start debug session pane, on the Environment dropdown, select eval.
The deployed revision number will also show in the dropdown.
Click Start.
A debug session will last a maximum of 10 minutes or until 15 transactions are received, whichever comes first.
Back in the Cloud Shell SSH session, send the following curl command:
A transaction for this request should appear in the Transactions pane on the left. When a transaction is selected, you'll see a trace of the request and response through Apigee.
You should see a 404 Status if your backend URL was correctly set and you correctly sent the curl command.
Click View Options, and then select Show skipped policies and Show all flow conditions.
Click OK.
S
When you select a step on the Transaction pane, the details of that step show up in the details pane. For example, if you click on a policy, you would see details like variables read and updated by the policy, as well as properties set in the policy configuration.
Click the GET 404
transaction.
In the Transaction pane, in the request, click on the Condition for the first route rule.
This shows the details of the condition you added in the first route rule.
The condition Expression is proxy.pathsuffix equals "/uuid"
, and the ExpressionResult is true
.
The true result indicates that your request was handled by the uuid_service
target endpoint.
Click Response Start, and then select the Response Content tab.
The response content shows that the backend server returned 404 Not Found. You need to determine what URL was called on the backend server.
Click AnalyticsPublisher, select the Variables tab, and then scroll down to the request.uri variable.
Apigee captures analytics for the API calls that travel through your proxies. The AnalyticsPublisher step in the transaction details shows the variables that were captured.
The variable request.uri contains the path that was called by the Apigee proxy, /uuid/uuid
.
You can probably see the issue now. The request to the backend service was a GET on https://httpbin.org/uuid/uuid, and the backend service returned the HTML error. The backend service URL only requires a single uuid. Why did this happen?
By default, the path suffix is automatically added to the target endpoint URL. This is why a request to /lab2a/v1/categories
went to the categories endpoint in the retail backend service. /categories
was the path suffix, which was automatically added to the target endpoint URL.
In this request, /uuid
follows the base path, and is therefore the path suffix. It was being added to the target endpoint URL, which already ends with /uuid
.
You could remove /uuid
from the target endpoint URL. Instead, you will change the proxy to not automatically append the path suffix to the target endpoint URL.
In this task, you add a policy to stop the path suffix from being added to the target service URL.
Click the Develop tab.
In the Navigator pane, click Target endpoints > uuid_service > PreFlow.
A visual representation of the target endpoint preflow is displayed.
On the Request PreFlow, click Add Policy Step (+).
This policy must run before we call the backend, so the step must be in the request path.
In the Add policy step pane, select Create new policy, and then select Extension > Javascript.
Specify the following values:
Property | Value |
---|---|
Name | JS-DisablePathSuffixCopy |
Display name | JS-DisablePathSuffixCopy |
For Javascript file, select Create New Resource.
For Resource name, specify DisablePathSuffixCopy.js
.
Click Add.
For Javascript file, select DisablePathSuffixCopy.js.
Click Add.
In another browser tab, open the Flow variables reference page.
This page lists the available built-in variables and is very useful when building API proxies. In the target section, there is a variable named target.copy.pathsuffix. Setting the variable to false will block the pathsuffix from being automatically copied to the target request URL. You can also specify the backend URL directly using the target.url variable.
In the Navigator pane, click Policies > JS-DisablePathSuffixCopy.
The policy XML configuration is shown in the Code pane.
You typically add JavaScript code to the .js file, but in this case the code is only a single line, so we add it directly in the JavaScript configuration.
Replace the current JavaScript configuration:
with:
The single line of JavaScript sets the target.copy.pathsuffix variable to false.
The .js file is no longer needed, so click Resources > jsc > DisablePathSuffixCopy.js, and then click Delete Resource ().
Confirm the deletion of the script by clicking Delete.
To save the updates, click Save, and then click Save as New Revision.
Click Deploy.
To specify that you want the new revision deployed to the eval environment, click Deploy, and then click Confirm.
Click the Overview tab, and then wait for the revision to deploy.
In this task, you verify that the proxy correctly calls the UUID service.
Click the Debug tab, and then click Start Debug Session.
In the Start debug session pane, on the Environment dropdown, select eval.
For Filter, select Custom.
For this debug session, you will specify a custom filter. Requests that do not match the filter will not be captured. This feature is very important when trying to debug the proxy in production, because the vast majority of the API traffic may not be what you are trying to capture.
For Value, specify this filter:
This filter will only capture calls that are going to the UUID service.
Click Start.
In the Cloud Shell SSH session, send the following curl command a few times:
You should see a UUID in the curl response.
Send the following curl command a few times too:
You should see the categories in the curl response.
Return to the debug tool.
You should only see UUID calls, because the categories calls were filtered out.
Click one of the transactions.
Click on the JS-DisablePathSuffixCopy step, and then click Variables.
You can see in the policy details that target.copy.pathsuffix was set to false.
In this lab, you learned about route rules and using multiple targets. You also learned all about the debug tool. Now you should be able to debug issues with your proxies!
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:
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.
This content is not currently available
We will notify you via email when it becomes available
Great!
We will contact you via email if it becomes available
One lab at a time
Confirm to end all existing labs and start this one