GSP842

概览

Google Cloud 的 Apigee API Platform 可为现有 API 添加新功能，对现有应用进行现代化改造。

在本实验中，您将在 Cloud Run 上部署一个后端服务。该后端服务实现了一个 REST API，用于在 Firestore 数据库中存储和检索银行数据（客户、账号、ATM 和交易）。您需要创建一个 Apigee API 代理，用于代理后端服务。您还将创建一个可从外部服务检索并缓存内容的共享流。然后，您从 API 代理调用该共享流，并使用 JavaScript 代码修改 API 响应。

目标

在本实验中，您将学习如何执行以下任务：

• 在 Cloud Run 上部署后端服务
• 使用 Apigee X 代理来代理该后端服务
• 创建可供多个代理使用的共享流
• 将配置数据存储在属性集中
• 使用服务调用政策从某个服务中检索内容
• 使用缓存政策缓存可重复使用的信息
• 使用 JavaScript 代码修改响应载荷

设置

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

此实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud。

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

如何开始实验并登录 Google Cloud 控制台

1. 点击开始实验按钮。如果该实验需要付费，系统会打开一个对话框供您选择支付方式。左侧是“实验详细信息”窗格，其中包含以下各项：

   • “打开 Google Cloud 控制台”按钮
   • 剩余时间
   • 进行该实验时必须使用的临时凭据
   • 帮助您逐步完成本实验所需的其他信息（如果需要）

2. 点击打开 Google Cloud 控制台（如果您使用的是 Chrome 浏览器，请右键点击并选择在无痕式窗口中打开链接）。

   该实验会启动资源并打开另一个标签页，显示“登录”页面。

   提示：将这些标签页安排在不同的窗口中，并排显示。

   注意：如果您看见选择账号对话框，请点击使用其他账号。

3. 如有必要，请复制下方的用户名，然后将其粘贴到登录对话框中。

   {{{user_0.username | "<用户名>"}}}

   您也可以在“实验详细信息”窗格中找到“用户名”。

4. 点击下一步。

5. 复制下面的密码，然后将其粘贴到欢迎对话框中。

   {{{user_0.password | "<密码>"}}}

   您也可以在“实验详细信息”窗格中找到“密码”。

6. 点击下一步。

   重要提示：您必须使用实验提供的凭据。请勿使用您的 Google Cloud 账号凭据。 注意：在本实验中使用您自己的 Google Cloud 账号可能会产生额外费用。

7. 继续在后续页面中点击以完成相应操作：

   • 接受条款及条件。
   • 由于这是临时账号，请勿添加账号恢复选项或双重验证。
   • 请勿注册免费试用。

片刻之后，系统会在此标签页中打开 Google Cloud 控制台。

注意：如需访问 Google Cloud 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

激活 Cloud Shell

Cloud Shell 是一种装有开发者工具的虚拟机。它提供了一个永久性的 5GB 主目录，并且在 Google Cloud 上运行。Cloud Shell 提供可用于访问您的 Google Cloud 资源的命令行工具。

1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

2. 在弹出的窗口中执行以下操作：

   • 继续完成 Cloud Shell 信息窗口中的设置。
   • 授权 Cloud Shell 使用您的凭据进行 Google Cloud API 调用。

如果您连接成功，即表示您已通过身份验证，且项目 ID 会被设为您的 Project_ID 。输出内容中有一行说明了此会话的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的命令行工具。它已预先安装在 Cloud Shell 上，且支持 Tab 自动补全功能。

3. （可选）您可以通过此命令列出活跃账号名称：

gcloud auth list

4. 点击授权。

输出：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. （可选）您可以通过此命令列出项目 ID：

gcloud config list project

输出：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需查看在 Google Cloud 中使用 gcloud 的完整文档，请参阅 gcloud CLI 概览指南。

任务 1. 在 Cloud Run 上部署后端服务

在此任务中，您将在 Cloud Run 上部署一个后端服务。

该服务将为 SimpleBank 实施一个 API。此 API 是一个简单的银行系统演示，其中包含客户、账号、交易和 ATM。SimpleBank 服务使用 Node.js 构建，数据存储在 Firestore 中。代码会打包到 Docker 容器中，此容器会被部署到 Cloud Run。

克隆代码库

1. 如需克隆包含 SimpleBank 服务代码的代码库，请在 Cloud Shell 中运行以下命令：

   git clone --depth 1 https://github.com/GoogleCloudPlatform/training-data-analyst

2. 创建指向工作目录的软链接：

   ln -s ~/training-data-analyst/quests/develop-apis-apigee ~/develop-apis-apigee

3. 如需切换到包含 REST 后端的目录，请运行以下命令：

   cd ~/develop-apis-apigee/rest-backend

4. 如需更新配置文件中的区域设置，请运行以下命令：

   sed -i "s/us-west1/{{{ project_0.default_region | "REGION" }}}/g" config.sh

初始化项目

项目初始化脚本 init-project.sh 会在项目内启用 API。部署 Cloud Run 服务需要用到这些 API。

该服务的数据库将使用原生模式 Firestore。一个项目可以托管一个以原生模式或 Datastore 模式运行的 Firestore 数据库。此脚本将创建原生模式 Firestore 数据库。

1. 如需查看 init-project.sh 脚本运行的命令，请输入以下命令：

   cat init-project.sh

   该脚本可启用 API 并创建原生模式 Firestore 数据库。

2. 如需运行该脚本，请输入以下命令：

   ./init-project.sh

点击检查我的进度，验证已完成以下目标： 启用 Cloud Run API 并创建 Firestore 数据库

初始化服务

服务初始化脚本 init-service.sh 会创建一个名为 simplebank-rest 的服务账号。此服务账号用作 Cloud Run 服务的身份。系统为服务账号授予角色 roles/datastore.user，该角色允许服务读取和更新 Firestore 中的数据。

最佳做法是，为所创建的服务各创建一个服务账号，并根据最小权限原则向该账号授予权限。根据此原则，账号应仅拥有执行其特定功能所需的权限。

1. 如需查看 init-service.sh 脚本运行的命令，请输入以下命令：

   cat init-service.sh

   该脚本会创建服务所用的服务账号，并向该服务账号添加角色。

2. 如需运行该脚本，请输入以下命令：

   ./init-service.sh

部署后端服务

部署脚本 deploy.sh 使用当前目录中的代码构建 simplebank 服务应用，并使用 simplebank-rest 服务账号将该服务部署到 Cloud Run。每次更新应用代码时，都会运行部署脚本。

该服务部署为需要经过身份验证才能访问，因此，如果没有有效的 OpenID Connect 身份令牌，您将无法调用该服务。

1. 在 Cloud Shell 中，如需查看 deploy.sh 脚本运行的命令，请输入以下命令：

   cat deploy.sh

   该脚本会构建 simplebank-grpc 服务并将其部署到 Cloud Run。

注意：部署脚本会使用 max-instances 参数将 Cloud Run 集群中的实例数限制为 1。对于实际的生产服务，不应指定如此低的限制。

2. 如需将脚本部署到 Cloud Run，请输入以下命令：

   ./deploy.sh

点击检查我的进度，验证已完成以下目标： 部署后端服务

测试服务

1. 如需验证服务是否可运行，请发出调用该服务的 curl 请求：

   export RESTHOST=$(gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)') echo "export RESTHOST=${RESTHOST}" >> ~/.bashrc curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/_status"

   用于设置 RESTHOST 变量的命令将使用 gcloud 检索 simplebank-rest Cloud Run 服务的主机名。然后，该变量会添加到 .bashrc 文件中，这样一来，如果 Cloud Shell 重启，系统就会重新加载 RESTHOST 变量。

   GET /_status 命令只会返回一个 JSON 响应，表明 API 已上线且运行正常。在此调用中，您使用 gcloud auth print-identity-token 为登录到 Cloud Shell 的用户获取了 Open ID Connect 身份令牌。您已登录并拥有 Project Owner 角色，该角色拥有的权限非常广泛。

2. 如需验证服务可以写入 Firestore，可发出一个创建客户的 curl 请求：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -H "Content-Type: application/json" -X POST "${RESTHOST}/customers" -d '{"lastName": "Diallo", "firstName": "Temeka", "email": "temeka@example.com"}'

   POST /customers 命令用于创建客户。lastName、firstName 和 email 均为必需的参数。邮箱必须是唯一的，用作客户的标识符。客户记录会存储在 Firestore 中。

   注意：如果您收到“AlreadyExist”错误，可能表示您未能成功创建 Firestore 数据库。数据库是通过运行 init-project.sh 脚本创建的。

3. 如需验证该服务可以从 Firestore 读取数据，可发出 curl 请求来检索您刚刚创建的客户：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/customers/temeka@example.com"

   GET /customers/ 命令可从 Firestore 中检索客户记录。

4. 如需将一些额外的示例数据加载到 Firestore 中，请输入以下命令：

   gcloud firestore import gs://spls/shared/firestore-simplebank-data/firestore/example-data

   此 gcloud 命令将使用 Firestore 导入/导出功能，将客户、账号和 ATM 的数据导入到数据库中。

5. 如需检索 ATM 列表，请运行以下 curl 命令：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms"

6. 如需检索单个 ATM，请运行以下 curl 命令：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms/spruce-goose"

   该请求将按名称检索 ATM，响应结果将包含 ATM 的纬度和经度，但不包含地址：

   {"name":"spruce-goose","longitude":-118.408207,"description":"","latitude":33.977601}

   在后续任务中，您将使用 Apigee 和 Geocoding API 将地址添加至检索特定 ATM 时返回的响应中。

任务 2. 使用 Apigee API 代理来代理后端服务

在此任务中，您将创建一个Apigee API 代理，此代理将作为后端服务的表层。API 代理将使用一个服务账号，以便向 Cloud Run 服务提供 OpenID Connect 身份令牌。

为 Apigee API 代理创建服务账号

1. 如需创建可供 Apigee API 代理使用的服务账号，请输入以下命令：

   gcloud iam service-accounts create apigee-internal-access \ --display-name="Service account for internal access by Apigee proxies" \ --project=${GOOGLE_CLOUD_PROJECT}

   gcloud 命令会创建一个名为 apigee-internal-access 的服务账号，您的 Apigee 代理在调用后端服务时将使用该账号。

2. 如需授予允许访问该服务的角色，请输入以下命令：

   gcloud run services add-iam-policy-binding simplebank-rest \ --member="serviceAccount:apigee-internal-access@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --role=roles/run.invoker --region={{{project_0.default_region |REGION}}} \ --project=${GOOGLE_CLOUD_PROJECT}

   此 gcloud 命令会向服务账号授予 simplebank-rest Cloud Run 服务的 roles/run.invoker 角色，从而允许该服务账号调用该服务。

3. 如需检索后端服务的网址，请使用以下命令：

   gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)'

   请保存此网址，它将在创建 API 代理时用到。

点击检查我的进度，验证已完成以下目标（系统可能要延迟一小段时间才能检测到所授予的角色）： 为 Apigee API 代理创建服务账号

打开 Apigee 控制台

如需打开 Apigee 控制台，请执行以下操作：

• 在 Google Cloud 控制台中，在搜索字段中输入 Apigee，然后点击搜索结果中的 Apigee API Management。

Apigee 控制台会随即打开，着陆页会显示指向常用位置的快捷链接。

• 在导航菜单 () 中，点击 Apigee 旁边的固定 ()。

Apigee 现在已固定到导航菜单中。

创建 Apigee 代理

1. 在导航菜单中，依次选择代理开发 > API 代理。

2. 如需使用代理向导创建新代理，请点击 +创建。

   您将为后端服务创建反向代理。

3. 对于 Proxy template（代理模板），依次选择 General template > Reverse proxy (Most common)（常规模板 > 反向代理 [最常见]）。

   注意：请勿使用 OpenAPI 规范模板部分中的 OpenAPI spec template（反向代理 [最常见]）选项。

4. 指定以下有关代理详情的内容：

   属性	值
   代理名称	bank-v1
   基本路径	/bank/v1
   目标（现有 API）	后端网址

   注意：请确认基本路径使用的是“/bank/v1”，而不是“/bank-v1”。

   目标应为任务中之前检索到的后端网址，该网址应如下所示：

   https://simplebank-rest-mtdtzt7yzq-ue.a.run.app

5. 点击下一步。

6. 将 Deploy (optional)（部署 [可选]）设置保留默认值，然后点击创建。

确认运行时实例可用

1. 在 Cloud Shell 中，粘贴并运行以下一组命令：

   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***";

   此系列命令使用 Apigee API 来判断 Apigee 运行时实例何时完成创建，以及 eval 环境何时完成附加。

2. 等待实例准备就绪。

   当屏幕上显示文本 ***ORG IS READY TO USE*** 时，表示实例已准备就绪。Apigee 组织 (org) 可能在您开始实验前就已经创建好了，因此您不一定需要等待实例创建完成。

   如果您正在等待组织准备就绪，可以了解有关 Apigee 的详细信息、探索 Apigee X 架构，或了解 API 和 API 代理。

部署 API 代理

1. 在导航菜单中，依次选择代理开发 > API 代理，然后点击 bank-v1。

2. 点击部署。

3. 对于环境，选择 eval。

4. 对于服务账号，指定服务账号的邮箱：

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

5. 点击部署，然后点击确认。

6. 等待 eval 部署状态显示代理已部署。

测试 API 代理

Apigee 组织中的 eval 环境可以使用主机名 eval.example.com 进行调用。此主机名的 DNS 条目已在您的项目中创建，并且会解析为 Apigee 运行时实例的 IP 地址。此 DNS 条目是在专用区域中创建的，这意味着它仅在内部网络中可见。

Cloud Shell 不在内部网络中，因此 Cloud Shell 命令无法解析此 DNS 条目。项目中的虚拟机 (VM) 可以访问专用区域 DNS。系统自动创建了名为 apigeex-test-vm 的虚拟机。您可以使用此机器调用 API 代理。

1. 在 Cloud Shell 中，打开与测试虚拟机的 SSH 连接：

   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

   第一个 gcloud 命令用于检索测试虚拟机的可用区，第二个命令用于打开与虚拟机的 SSH 连接。

2. 如果系统提示您进行授权，请点击授权。

   对于 Cloud Shell 中提出的每个问题，点击 Enter 键或 Return 键来指定默认输入。

   您的登录身份为项目所有者，因此允许通过 SSH 连接到此机器。

   您的 Cloud Shell 会话现在正在虚拟机内运行。

3. 在 eval 环境中调用已部署的 bank-v1 API 代理：

   curl -i -k "https://eval.example.com/bank/v1/_status"

   -k 选项会告知 curl 跳过 TLS 证书的验证。在此实验中，Apigee 运行时使用的是自签名证书，而不是由受信任的证书授权机构 (CA) 创建的证书。

   注意：在生产使用场景中，不应使用 -k 选项来绕过证书验证。

   系统会返回“403 Forbidden”状态代码，并显示一条错误消息，指出您的客户端无获取相应网址的权限。发送至后端服务的请求已被拒绝，因为客户端未在请求中提供必需的令牌。API 代理正在以正确的身份运行，但您仍需要强制将 OpenId Connect 身份令牌随请求一起发送。

4. 返回 bank-v1 代理，然后点击开发标签页。

5. 在代理的左侧菜单中，点击目标端点 > 默认部分中的 PreFlow。

6. 找到以下代码（您的网址将有所不同）：

   <HTTPTargetConnection> <Properties/> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection> 注意：如果您未看到“HTTPTargetConnection”部分，请确保您点击的是目标端点部分中的“PreFlow”，而不是 Proxy endpoints（代理端点）部分中的“PreFlow”。

7. 前往 HTTPTargetConnection 部分，在网址下方添加如下所示的“身份验证”部分：

   <Authentication> <GoogleIDToken> <Audience>AUDIENCE</Audience> </GoogleIDToken> </Authentication>

8. 将 AUDIENCE 替换为“HTTPTargetConnection”部分中的已有网址值。现在，您的代码应如下所示，不同的是网址部分和 Audience 元素中将填入您自己的具体网址：

   <TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <Properties/> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> <Authentication> <GoogleIDToken> <Audience>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>

9. 点击保存，然后点击另存为新修订版本。

10. 点击部署。

11. 对于环境，使用 eval。

12. 对于服务账号，指定服务账号的邮箱：

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

13. 点击部署，然后点击确认。

14. 点击概览标签页，然后等待 eval 部署状态显示为新修订版本已部署。

点击检查我的进度，验证已完成以下目标： 创建 Apigee 代理

14. 如果您的 SSH 登录已超时，请在 Cloud Shell 中运行以下命令以重新建立连接：

    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

15. 在虚拟机内重新运行状态命令：

    curl -i -k "https://eval.example.com/bank/v1/_status"

    您现在应该会看到一个成功的 (200) 响应，类似于以下示例：

    HTTP/2 200 x-powered-by: Express content-type: application/json; charset=utf-8 etag: W/"41-x4uozCo6q/yN+kzizriXxryNZvc" x-cloud-trace-context: 5c810a7faa3353bcc085473fd58805b7 date: Thu, 11 Nov 2021 22:54:35 GMT server: Google Frontend content-length: 65 x-request-id: cf109193-6d6f-49a1-b323-7f66f63c5e28 via: 1.1 google {"serviceName":"simplebank-rest","status":"API up","ver":"1.0.0"}

    此响应表示 API 代理正在成功调用后端服务。

16. 输入命令 exit 以退出 SSH 会话并返回到 Cloud Shell。

任务 3. 启用 Google Cloud Geocoding API 的使用权限

在此任务中，您将启用 Geocoding API，该 API 将在您的 API 代理中使用，从而实现在 SimpleBank 服务检索 ATM 时向响应添加地址信息。

1. 在 Cloud Shell 中，运行以下命令来启用 Geocoding API：

   gcloud services enable geocoding-backend.googleapis.com

   接下来，您将创建一个可以访问 Geocoding API 的 API 密钥。

2. 如需创建 API 密钥，请运行以下命令：

   API_KEY=$(gcloud alpha services api-keys create --project=${GOOGLE_CLOUD_PROJECT} --display-name="Geocoding API key for Apigee" --api-target=service=geocoding_backend --format "value(response.keyString)") echo "export API_KEY=${API_KEY}" >> ~/.bashrc echo "API_KEY=${API_KEY}" 注意：如果您收到错误消息，指出项目属性设置为空字符串，请确保您已退出虚拟机 SSH 会话并返回到 Cloud Shell。

   gcloud 命令会创建能够向 Geocoding API 发送请求的 API 密钥。通过提供 --format 参数，您可以选择响应中的 keyString 字段，并将其存储在 API_KEY shell 变量中。然后，API_KEY 变量会存储在 Cloud Shell 的 .bashrc 文件中。

点击检查我的进度，验证已完成以下目标： 启用 Google Cloud Geocoding API 的使用权限

3. 如需检索特定纬度和经度的地理编码信息，请运行以下 curl 命令：

   curl "https://maps.googleapis.com/maps/api/geocode/json?key=${API_KEY}&latlng=37.404934,-122.021411"

   此命令会调用 Geocoding API，并提供 API 密钥和所需的纬度和经度。响应将包含一个结果数组，每个结果都包含一个格式化的地址。在您的 API 代理中，您将使用第一个结果的格式化地址，以便在检索单个 ATM 的详细信息时向 API 响应添加地址。

任务 4. 创建可调用 Geocoding API 的共享流

在此任务中，您将创建可调用 Google Geocoding API 的共享流。借助共享流，您可以将政策和资源组合成一个流，供多个 API 代理或其他共享流使用。

共享流将使用以下模式：

我们数据库中的 ATM 数量有限，且 ATM 的纬度和经度不会发生变化。为避免过度调用 Geocoding API，系统会缓存检索到的地址，并使用纬度和经度作为缓存键。如果缓存中未含有指定纬度和经度的地址，系统将调用 Geocoding API，并将返回的地址存储在缓存中。

创建共享流

1. 在导航菜单中，依次选择 Apigee > 代理开发 > 共享流。
2. 点击 +创建。
3. 将名称设置为 get-address-for-location，然后点击创建。
4. 点击开发标签页。

添加 LookupCache 政策

如果地址之前已缓存，LookupCache 政策将检索该地址。

1. 在共享流的左侧菜单中，点击共享流部分中的默认。

2. 在 sharedflows/default.xml 窗格中，点击 Add policy step（添加政策步骤）()。

3. 选择创建新政策。

4. 对于 Select policy（选择政策），依次选择流量管理 > Lookup Cache（查询缓存）。

5. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	LC-LookupAddress
   显示名称	LC-LookupAddress

6. 点击添加，然后点击 LC-LookupAddress。

   政策已添加到流中，并且政策的配置 XML 会显示在流下方的窗格中。

7. 验证窗格中是否包含 LookupCache 配置，然后将 LookupCache 配置替换为：

   <LookupCache continueOnError="false" enabled="true" name="LC-LookupAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <AssignTo>geocoding.address</AssignTo> </LookupCache>

   该政策会在 AddressesCache 中查找与指定纬度和经度匹配的条目，如果找到，则将该值分配给变量 address（地址）。

添加 Service Callout 政策

Service Callout 政策将调用 Google Geocoding API。

1. 在共享流的左侧菜单中，点击共享流部分中的默认。

2. 在 sharedflows/default.xml 窗格中，点击 Add policy step（添加政策步骤）()。

3. 选择创建新政策。

4. 对于 Select policy（选择政策），依次选择扩展程序 > Service Callout（服务调用）。

5. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	SC-GoogleGeocode
   显示名称	SC-GoogleGeocode

6. 保持 HTTP 目标字段不变，点击添加，然后点击 SC-GoogleGeocode。

7. 验证窗格中是否包含 ServiceCallout 配置，然后将 ServiceCallout 配置替换为：

   <ServiceCallout continueOnError="false" enabled="true" name="SC-GoogleGeocode"> <Request> <Set> <QueryParams> <QueryParam name="latlng">{geocoding.latitude},{geocoding.longitude}</QueryParam> <QueryParam name="key">{geocoding.apikey}</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> </Request> <Response>calloutResponse</Response> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>

   此政策使用 geocoding.latitude、geocoding.longitude 和 geocoding.apikey 变量调用 Geocoding API。API 调用响应存储在 calloutResponse 变量中。

添加 ExtractVariables 政策

ExtractVariables 政策将从 Google Geocoding API 响应中提取格式化地址。

1. 在共享流的左侧菜单中，点击共享流部分中的默认。

2. 在 sharedflows/default.xml 窗格中，点击 Add policy step（添加政策步骤）()。

3. 选择创建新政策。

4. 对于 Select policy（选择政策），依次选择中介 > Extract Variables（提取变量）。

5. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	EV-ExtractAddress
   显示名称	EV-ExtractAddress

6. 点击添加，然后点击 EV-ExtractAddress。

7. 验证窗格中是否包含 ExtractVariables 配置，然后将 ExtractVariables 配置替换为：

   <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> <VariablePrefix>geocoding</VariablePrefix> </ExtractVariables>

   此政策使用 JSONPath 从 calloutResponse 消息 JSON 载荷的第一个结果中提取 formatted_address。该地址存储在 geocoding.address 变量中。

添加 PopulateCache 政策

PopulateCache 政策会将地址存储到缓存中。

1. 在共享流的左侧菜单中，点击共享流部分中的默认。

2. 在 sharedflows/default.xml 窗格中，点击 Add policy step（添加政策步骤）()。

3. 选择创建新政策。

4. 对于 Select policy（选择政策），依次选择流量管理 > PopulateCache。

5. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	PC-StoreAddress
   显示名称	PC-StoreAddress

6. 点击添加，然后点击 PC-StoreAddress。

7. 验证窗格中是否包含 PopulateCache 配置，然后将 PopulateCache 配置替换为：

   <PopulateCache continueOnError="false" enabled="true" name="PC-StoreAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <Source>geocoding.address</Source> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <ExpirySettings> <TimeoutInSec>3600</TimeoutInSec> </ExpirySettings> </PopulateCache>

   该政策使用与 LookupCache 政策相同的纬度和经度键片段，以相同的顺序将 address 变量中的值存储到 AddressesCache 中。ExpirySettings/TimeoutInSec 设置规定了存储的数据将缓存 3600 秒（即 1 小时）。

有条件地跳过政策

如果在缓存中找到了特定纬度和经度的地址（缓存命中），则无需使用并应跳过 ServiceCallout、ExtractVariables 和 PopulateCache 政策。

1. 在共享流的左侧菜单中，点击共享流部分中的默认。

   “代码”窗格包含默认流，其中列出了已附加的四项政策：

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Name>EV-ExtractAddress</Name> </Step> <Step> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

   每个“步骤”都会指定已附加的政策。“名称”用于指定所附加政策的名称。您还可以添加“条件”元素，以指定一个布尔值条件，用于确定是否应执行相应政策。

   回顾一下任务开始时的共享流模式。当地址查找成功时，无需调用服务或将数据存储回缓存中。在这种情况下，应跳过第二步到第四步政策。

   LookupCache 政策会设置一个变量，用于表明是否在缓存中找到了相应项。如果变量 lookupcache.{policyName}.cachehit 为 false，则表示未找到相应项。第二步到第四步的政策应仅在未实现缓存命中时执行。

2. 对于第二步到第四步中的每一步，请在“步骤”元素中添加以下条件：

   <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition>

   添加所有条件后，共享流应如下所示：

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>EV-ExtractAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

3. 点击保存。

4. 点击部署。

5. 对于环境，使用 eval。

6. 将“服务账号”留空，然后依次点击部署和确认。

   共享流使用 API 密钥调用 Geocoding API，因此不需要服务账号。

   如需测试共享流，只能通过从 API 代理调用该共享流。

点击检查我的进度，验证已完成以下目标： 创建可调用 Geocoding API 的共享流

任务 5. 在检索单个 ATM 时添加该 ATM 的地址

在此任务中，您需要向 API 代理添加 FlowCallout 政策，以调用刚刚创建的共享流。在您检索特定 ATM 时，API 代理必须从 Cloud Run 服务响应中提取纬度和经度，并调用共享流来检索相应地址。然后，JavaScript 政策会将地址添加到 API 响应中。

为 API 密钥添加属性集

属性集可用于存储不过期的数据，这些数据可从 API 代理中轻松访问。属性集值将包含 API 密钥。

1. 在左侧导航菜单中，依次选择代理开发 > API 代理。

2. 点击 bank-v1，然后选择开发标签页。

3. 在代理的左侧菜单中，点击资源部分中的添加资源 ()。

4. 在资源类型下拉菜单中，选择Property Set（属性集）。

5. 对于资源名称，指定 geocoding.properties，然后点击添加。

6. 在 geocoding.properties 窗格中，添加以下属性：

   apikey=<APIKEY>

7. 将 <APIKEY> 替换为您在任务 3 中创建的 API_KEY。

8. 您可以在 Cloud Shell 中使用以下命令检索 API_KEY：

   echo ${API_KEY}

   您的 geocoding.properties 文件应如下所示：

   apikey=AIzaSyC8-B6nt7M240wwZtsxR2O5sb0xznuhQWc

创建条件流

1. 在代理的左侧菜单中，点击 Proxy endpoints（代理端点）部分中的默认。

2. 在 proxy-endpoints/default.xml 窗格中，点击 Proxy endpoint: default（代理端点：默认）旁边的 Add conditional flow（添加条件流）()。

3. 在“Add conditional flow”（添加条件流）对话框中，指定以下值：

   属性	值
   流名称	GetATM
   描述	检索单个 ATM
   条件类型	选择“路径”和“动词”
   路径	/atms/{name}
   动词	选择 GET（获取）

   将“目标网址”留空。

4. 点击添加。

   API 代理由多个流组成。每个流都提供了一个位置，用于以步骤的形式附加政策。下方显示了 API 代理的图表：

   

   只有在条件为 true 时，系统才会运行条件流配置。对于此条件流，proxy.pathsuffix 变量必须匹配 /atms/{name} 格式，并且 request.verb 变量必须为 GET（获取）。

   您要将一些政策附加到 GetATM 条件流，以便这些政策仅执行 GET /atms/{name} 请求。政策必须在调用后端服务后执行，因此必须附加到“Proxy Endpoint Response”（代理端点响应）条件流中。

提取纬度和经度

1. 在 Proxy endpoint: default（代理端点：默认）流的响应部分中，点击 GetATM 右侧的 Add Policy Step（添加政策步骤）()。

   注意：请务必将该步骤添加到响应端，而不是请求端。

2. 选择创建新政策。

3. 对于 Select policy（选择政策），依次选择中介 > Extract Variables（提取变量）。

4. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	EV-ExtractLatLng
   显示名称	EV-ExtractLatLng

5. 点击添加，然后点击 EV-ExtractLatLng。

6. 验证窗格中是否包含 ExtractVariables 配置，然后将 ExtractVariables 配置替换为：

   <ExtractVariables name="EV-ExtractLatLng"> <Source>response</Source> <JSONPayload> <Variable name="latitude"> <JSONPath>$.latitude</JSONPath> </Variable> <Variable name="longitude"> <JSONPath>$.longitude</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

   此政策将从后端服务的 GET /atms/{name} JSON 响应中提取纬度和经度。IgnoreUnresolvedVariables 元素被设为 true，这意味着即使响应中找不到经纬度，处理过程也会继续。

调用共享流

1. 在 Proxy endpoint: default（代理端点：默认）流的响应部分中，点击 GetATM 右侧的 Add Policy Step（添加政策步骤）()。

2. 选择创建新政策。

3. 对于 Select policy（选择政策），依次选择扩展 > FlowCallout。

4. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	FC-GetAddress
   显示名称	FC-GetAddress
   共享流	选择 get-address-for-location
   条件	latitude != null AND longitude != null

   如果未检索到 ATM 的纬度或经度，则无法确定地址，因此相应政策步骤会被跳过。

5. 点击添加，然后点击 FC-GetAddress。

6. 验证窗格中是否包含 FlowCallout 配置，然后将 FlowCallout 配置替换为：

   <FlowCallout continueOnError="false" enabled="true" name="FC-GetAddress"> <Parameters> <Parameter name="geocoding.latitude">{latitude}</Parameter> <Parameter name="geocoding.longitude">{longitude}</Parameter> <Parameter name="geocoding.apikey">{propertyset.geocoding.apikey}</Parameter> </Parameters> <SharedFlowBundle>get-address-for-location</SharedFlowBundle> </FlowCallout>

   此政策可将纬度、经度和 apikey 变量设置为共享流参数，并调用该共享流。共享流可设置 geocoding.address 变量。

添加地址

1. 在 Proxy endpoint: default（代理端点：默认）流的响应部分中，点击 GetATM 右侧的 Add Policy Step（添加政策步骤）()。

2. 选择创建新政策。

3. 对于 Select policy（选择政策），依次选择扩展程序 > JavaScript。

4. 在“详细信息”部分，指定以下内容：

   属性	值
   名称	JS-AddAddress
   显示名称	JS-AddAddress
   JavaScript 文件	选择“创建新资源”

5. 在“添加资源”部分，指定以下内容：

   属性	值
   来源	选择“创建新文件”
   资源名称	addAddress.js

6. 点击添加，然后选择 addAddress.js。

7. 对于条件，指定 latitude != null AND longitude != null。

8. 点击添加，然后点击 JS-AddAddress。

9. 在代理的左侧菜单中，点击资源 > jsc 部分中的 addAddress.js。

   addAddress.js 代码的代码窗格为空。

10. 添加以下 JavaScript 代码以将地址添加到响应中：

    // get the flow variable 'geocoding.address' var address = context.getVariable('geocoding.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)); } catch(e) { // catch any exception print('Error occurred when trying to add the address to the response.'); }

    此代码会将 JSON 响应载荷解析为对象，向该对象添加地址字段，将该对象转换回 JSON 字符串，然后将其存储在响应中。

    使用 try/catch 代码块是为了防止从 JavaScript 政策中抛出异常。如果未能捕获到异常，则系统会引发故障，导致 API 代理处理中止。

验证是否已经有条件地跳过政策

1. 在代理的左侧菜单中，点击 Proxy endpoints > default（代理端点 > 默认）部分中的 GetATM。

   “代码”窗格包含“Get ATM”流，其中列出了已附加的三项政策，第二项和第三项政策附带条件：

   <Flow name="GetATM"> <Description>retrieve a single ATM</Description> <Request/> <Response> <Step> <Name>EV-ExtractLatLng</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>FC-GetAddress</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>JS-AddAddress</Name> </Step> </Response> <Condition>(proxy.pathsuffix MatchesPath "/atms/{name}") and (request.verb = "GET")</Condition> </Flow>

2. 点击保存，然后点击另存为新修订版本。

3. 点击部署。

4. 对于环境，使用 eval。

5. 对于服务账号，指定服务账号的邮箱：

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

6. 点击部署，然后点击确认。

7. 点击概览标签页，然后等待 eval 部署状态显示为新修订版本已部署。

点击检查我的进度，验证已完成以下目标： 在检索单个 ATM 时添加该 ATM 的地址

测试更新后的 API 代理

1. 在 Cloud Shell 中，打开与测试虚拟机的 SSH 连接：

   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

2. 使用以下命令调用 bank-v1 代理并检索所有 ATM：

   curl -i -k "https://eval.example.com/bank/v1/atms"

   由于请求未使用 GET /atms/{name} 流，因此响应不包含地址。

3. 检索单个 ATM：

   curl -i -k "https://eval.example.com/bank/v1/atms/spruce-goose"

   此响应现在包含已在 API 代理中添加的地址：

   {"longitude":-118.408207,"latitude":33.977601,"description":"","name":"spruce-goose","address":"5865 S Campus Center Dr, Los Angeles, CA 90094, USA"}

恭喜！

在本实验中，您在 Cloud Run 上部署了后端服务。您创建了一个可代理后端服务的 Apigee API 代理。您创建了一个共享流，用于从外部服务检索内容并将其缓存。您从 API 代理调用了该共享流，并使用 JavaScript 代码修改了 API 响应。

后续步骤/了解详情

• Apigee 是什么？
• Apigee X 架构
• API 和 API 代理

本手册的最后更新时间：2024 年 7 月 16 日

本实验的最后测试时间：2024 年 7 月 16 日

版权所有 2025 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。