GSP843

概览

API 旨在供应用开发者使用，开发者可借助 API 为其用户提供独特体验。Google Cloud 的 Apigee API 平台可用于发布 API，供应用开发者调用。

在本实验中，您将创建一个 Apigee API 代理，该代理需要进行 API 密钥验证，以限制对 API 的访问。

您会创建 API 产品，以便为内部和外部应用开发者提供不同级别的服务，并利用配额政策来限制各特定应用调用 API 的次数。您将创建 CORS 政策，来为 API 添加跨域资源共享功能，使其可被 Web 应用调用。然后，您将创建开发者门户，并发布 API 产品供应用开发者使用。

学习内容

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

• 验证 API 密钥，以限制对 API 的访问并跟踪应用使用情况
• 创建 API 产品，以便为不同类型的应用开发者提供不同级别的访问权限
• 使用配额政策，根据关联的 API 产品限制特定应用调用 API 的次数
• 为 API 添加跨域资源共享 (CORS) 功能，允许 Web 应用发起跨域 API 调用
• 创建开发者门户并发布 API 产品

设置和要求

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

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 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 概览指南。

打开 Apigee 控制台

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

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

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

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

Apigee 现在已作为收藏项添加到导航菜单中。

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

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

名为 simplebank-rest 的后端服务已创建完成并部署到 Cloud Run。

创建 Apigee 代理

1. 在 Cloud Shell 中，如需检索后端服务的网址，请使用以下命令：

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

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

1. 在 Apigee 导航菜单中，依次选择 Proxy development > API proxies（“代理开发”>“API 代理”）。

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

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

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

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

4. 在 Proxy details（代理详情）部分，指定以下内容：

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

   注意：请确认使用“/bank/v1”而非“/bank-v1”作为基本路径。

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

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

5. 点击 Next（下一步）。

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

任务 2. 添加 VerifyAPIKey 政策

在此任务中，您将向 API 代理添加 VerifyAPIKey 政策。任何未提供有效 API 密钥的请求都会被拒绝。

VerifyAPIKey 政策会在运行时强制执行 API 密钥验证，仅允许拥有已获批 API 密钥的应用访问 API。此政策可确保 API 密钥有效、未被撤销，并且已获准使用所请求的特定资源。

添加 VerifyAPIKey 政策

1. 点击 Develop（开发）标签页。

2. 在代理的导航菜单中，点击 Proxy Endpoints（代理端点）部分中的 PreFlow。

   VerifyAPIKey 政策应置于 API 代理中非常靠前的位置。“default proxy endpoint”（默认代理端点）中的“request PreFlow”（请求 PreFlow）是请求进入 API 代理时执行的第一个流。

3. 在 Flow（流）窗格中，点击请求流右上方的 + Add Policy Step（+ 添加政策步骤）按钮。

4. 选择 Create new policy（创建新政策），然后在 Security（安全）部分的 select policy（选择政策）下，选择 Verify API Key（验证 API 密钥），并将 Display Name（显示名称）和 Name（名称）设置为 VAK-VerifyKey。

5. 点击 Add（添加）。

6. 点击名称 VAK-VerifyKey。

   VerifyAPIKey 配置即会显示在 Policies（政策）下的 Code（代码）窗格中。

   APIKey 元素用于指明请求中提供 API 密钥的位置。

7. 在 APIKey 元素中，将 request.queryparam.apikey 替换为 request.header.apikey。

   如果 API 密钥是在标头中指定的，其被记录或保存在浏览器历史记录中的可能性会降低。

修改目标以发送 OpenID Connect 身份令牌

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

HTTPTargetConnection 指定服务的后端目标。

1. 在代理的导航菜单中，点击 Target Endpoints（目标端点）部分中的 PreFlow。

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

   <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection>

注意：如果您没有看到 HTTPTargetConnection 部分，请确保您点击的是 Target Endpoints（目标端点）部分中的 PreFlow，而不是 Proxy Endpoints（代理端点）部分中的 PreFlow。

3. 在网址下方添加如下所示的 Authentication 部分：

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

4. 将 AUDIENCE 替换为 HTTPTargetConnection 部分中已有的网址值。现在，您的代码应如下所示，不过 URL 和 Audience 元素中的网址需替换为您的实际网址：

<TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <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>

5. 点击 Save（保存）。

确认运行时实例可用

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

   export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; if [ -z "${GOOGLE_CLOUD_PROJECT}" ]; then echo "Error: GOOGLE_CLOUD_PROJECT environment variable is not set. Please set it to your project ID."; else 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}\" or (.environment | endswith(\"/${ENV_NAME}\"))) | .environment" --raw-output); [[ -n "${ATTACHMENT_DONE}" ]] && break; echo -n "."; sleep 5; done; echo; echo "${ENV_NAME} environment attached"; echo "***ORG IS READY TO USE***"; fi

   这组命令使用 Apigee API 来判断 Apigee 运行时实例是否已创建，以及 eval 环境是否已关联至该实例。

2. 等待实例准备就绪。

   当屏幕上显示文本 ***ORG IS READY TO USE*** 时，表示实例已准备就绪。Apigee 组织可能在您开始本实验前就已创建，因此您或许无需等待实例创建。

   如果您正在等待组织准备就绪，可以先了解 API 产品、CORS（跨域资源共享）和开发者门户。

部署 API 代理

1. 在 Apigee 导航菜单中，依次选择 Proxy development > API proxies（“代理开发”>“API 代理”），然后点击 bank-v1。

2. 点击 Deploy（部署）。

3. 在 Environment（环境）部分，选择 eval。

4. 对于 Service account（服务账号），指定服务账号的邮箱：

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

5. 点击 Deploy（部署），然后点击 Confirm（确认）。

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

点击检查我的进度以验证是否完成了以下目标：创建 Apigee 代理并添加 VerifyAPIKey 政策

测试 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

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

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

   您的登录身份是项目的所有者，因此可以通过 SSH 连接到此机器。

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

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

   curl -i -k -X GET "https://eval.example.com/bank/v1/customers"

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

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

   此 API 会尝试检索客户列表。您现在应该会看到类似于以下内容的“401 未经授权”响应：

   HTTP/2 401 content-type: application/json x-request-id: 01e8da87-dc8c-4428-9cdf-8bea84e98860 content-length: 146 date: Tue, 07 Dec 2021 22:54:37 GMT via: 1.1 google {"fault":{"faultstring":"Failed to resolve API Key variable request.header.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

   此响应表明，由于未提供 API 密钥，API 代理已阻止对后端服务的访问。

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

任务 3. 添加 API 产品和应用

在此任务中，您将添加 API 产品，这些产品将为您的 API 提供不同的访问权限级别。然后，您将创建两个应用并为其关联不同的 API 产品，从而为它们提供不同的访问权限。

创建第一个 API 产品

第一个 API 产品提供对服务的完整访问权限。

1. 在 Apigee 导航菜单中，依次选择 Distribution > API Products（“分发”>“API 产品”）。

2. 如需创建新的 API 产品，请点击 +CREATE（+创建）。

3. 在 Product details（产品详情）窗格中，指定以下内容：

   属性	值
   名称	bank-fullaccess
   显示名称	bank（完整访问权限）
   说明	授予对 bank API 的完整访问权限
   环境	选择 eval
   访问权限	选择 Public（公开）

   保持 Automatically approve access requests（自动批准访问请求）处于选中状态。

4. 在 Operations（操作）部分中，点击 +Add an Operation（+添加操作）。

   操作用于指定与 API 产品关联的应用允许在哪些 API 代理中发出哪些请求。

   注意：请确认该按钮位于“Operations”（操作）部分，而不是“GraphQL Operations”（GraphQL 操作）部分。

5. 指定下列内容：

   名称	值
   来源	选择 bank-v1 API 代理
   路径	/**
   方法	选择 GET、PATCH、POST、PUT 和 DELETE

   路径表达式“/**”指示任意深度的任何路径后缀都与该操作匹配。

   在生产环境中，您可能会选择单独添加允许的每项操作，而不是使用此通配符路径表达式。

6. 点击 Save（保存）以保存该操作。

7. 在 API 产品的 Custom Attributes（自定义属性）部分中，点击 +Add Custom Attribute（+添加自定义属性）。

   自定义属性可用于附加您希望在代理中提供的任何数据，以控制访问权限。

   在这种情况下，由于这是 Retail API 的完整访问权限 API 产品，因此您将创建一个自定义属性，用于指示调用该 API 的应用应被授予完全访问权限。

8. 指定下列内容：

   属性	值
   名称	full-access
   值	yes

9. 点击 OK（确定）以保存自定义属性。

10. 如需保存 API 产品，请点击页面顶部的 Save（保存）。

11. 返回到 Distribution > API Products（“分发”>“API 产品”）页面。系统会列出相应 API 产品。

点击检查我的进度以验证是否完成了以下目标：添加 API 产品和应用

创建提供有限访问权限的 API 产品

第二种 API 产品将提供对服务的只读权限。

1. 如需创建新的 API 产品，请点击 +CREATE（+创建）。

2. 在 Product details（产品详情）窗格中，指定以下内容：

   属性	值
   名称	bank-readonly
   显示名称	bank（只读）
   说明	允许对 bank API 进行只读访问
   环境	选择 eval
   访问权限	选择 Public（公开）

   保持 Automatically approve access requests（自动批准访问请求）处于选中状态。

3. 在 Operations（操作）部分中，点击 +Add an Operation（+添加操作）。

   注意：请确认该按钮位于“Operations”（操作）部分，而不是“GraphQL Operations”（GraphQL 操作）部分。

4. 指定下列内容：

   属性	值
   来源	选择 bank-v1 API 代理
   路径	/**
   方法	选择 GET

5. 点击 Save（保存）以保存该操作。

6. 如需保存 API 产品，请点击页面顶部的 Save（保存）。

7. 返回到 Distribution > API Products（“分发”>“API 产品”）页面。系统会列出相应 API 产品。

创建应用开发者

在创建应用之前，您必须先创建应用开发者。

注意：应用开发者通常是使用开发者门户创建的，您将在本实验的后面部分创建开发者门户。目前，请使用 Apigee 控制台创建开发者。

1. 在 Apigee 导航菜单中，依次点击 Distribution > Developers（“分发”>“开发者”）。

2. 如需创建新的应用开发者，请点击 +CREATE（+创建）。

3. 指定下列内容：

   属性	值
   名字	Joe
   姓氏	Developer
   邮箱	joe@example.com
   用户名	joe

4. 点 击ADD（添加）以创建应用开发者。

创建具有只读权限的应用

1. 在 Apigee 导航菜单中，依次点击 Distribution > Apps（“分发”>“应用”）。

2. 如需创建新应用，请点击 +CREATE（+创建）。

3. 在 App details（应用详情）窗格中，指定以下内容：

   属性	值
   名称	readonly-app
   开发者	选择 Joe Developer

4. 在 Credentials（凭证）窗格中，点击 + ADD CREDENTIAL（+ 添加凭证），然后点击 + ADD PRODUCTS（+ 添加产品），选择 bank（只读），然后点击 Add（添加）以进行添加。

   在“Product”（产品）下，点击 bank（只读）旁边的复选框，然后点击 APPROVE（批准）

5. 点击 Create（创建）以创建应用。

   现在，系统已为该应用配置“密钥”和“密文”。

6. 在 Apigee 导航菜单中，依次点击 Distribution > Apps > readonly-app（“分发”>“应用”>“readonly-app”）。

7. 在“Credentials”（凭证）下，点击 Key（密钥）旁边的 Show（显示）。

   这是将用于调用 API 的 API 密钥。您可以复制该密钥，但后续步骤将使用对 Apigee API 的 curl 调用来检索 API 密钥。

创建具有完整访问权限的应用

1. 在左侧导航菜单中，依次点击 Distribution > Apps（“分发”>“应用”）。

2. 如需创建新应用，请点击 +CREATE（+创建）。

3. 在 App details（应用详情）窗格中，指定以下内容：

   属性	值
   名称	fullaccess-app
   开发者	选择 Joe Developer

4. 在 Credentials（凭证）窗格中，点击 + ADD CREDENTIAL（+ 添加凭证），然后点击 + ADD PRODUCTS（+ 添加产品），选择 bank（完整访问权限），然后点击 Add（添加）以进行添加。

   在“Product”（产品）下，点击 bank（完整访问权限）旁边的复选框，然后点击 APPROVE（批准）

5. 点击 Create（创建）以创建应用。

6. 在 Apigee 导航菜单中，依次点击 Distribution > Apps > fullaccess-app（“分发”>“应用”>“fullaccess-app”）。

7. 在“Credentials”（凭证）下，点击 Key（密钥）旁边的 Show（显示）。

点击检查我的进度以验证是否完成了以下目标：创建提供有限访问权限的 API 产品

使用 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. 如果系统提示您进行授权，请点击授权。

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

3. 如需获取只读应用的 API 密钥，请运行以下命令：

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

   第一条命令会读取 gcloud 配置以获取当前项目。第二条命令会使用 Apigee API 检索 API 密钥。由于您发送的访问令牌具有已登录用户的权限，因此请求已获得授权。

4. 使用虚构 API 密钥，在 eval 环境中调用已部署的 bank-v1 API 代理：

   curl -i -k -X GET -H "apikey: ABC123" "https://eval.example.com/bank/v1/customers"

   响应为“401 未经授权”，并显示表明 API 密钥无效的故障。

5. 使用真实的 API 密钥，在 eval 环境中调用已部署的 bank-v1 API 代理：

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

   请求被允许，并且响应包含客户列表。

6. 同样使用真实的 API 密钥，在 eval 环境中再次调用已部署的 bank-v1 API 代理：

   curl -i -k -X POST -H "apikey: ${API_KEY}" -H "Content-Type: application/json" "https://eval.example.com/bank/v1/customers" -d '{"firstName": "Julia", "lastName": "Dancey", "email": "julia@example.org"}'

   这次的响应是“401 未经授权”，并包含一个故障，表明 API 密钥对给定资源无效。请求被拒绝，因为所提供的 API 密钥与只读 API 产品相关联，而只读 API 产品不允许 POST 请求。

7. 输入 exit 以退出虚拟机 SSH 会话。

任务 4. 强制执行配额

在此任务中，您将添加一个配额政策，该政策将限制每个应用在特定时间段内允许的请求数量。配额政策将使用 API 产品中指定的配额配置。

添加配额政策

2. 在 Apigee 导航菜单中，依次选择 Proxy development > API Proxies（“代理开发”>“API 代理”），然后点击 bank-v1。

3. 点击 Develop（开发）标签页。

4. 在代理的导航菜单中，点击 Proxy Endpoints（代理端点）部分中的 PreFlow。

   配额政策将验证特定应用的配额是否未超出。如果已达到上限，配额政策会引发故障，并且请求会被中止。如果未达到上限，则允许的请求数会递减。

   配额政策会根据 VerifyAPIKey 政策填充的变量来确定调用应用。因此，配额政策必须放在 VerifyAPIKey 政策之后。

5. 在 Flow（流）窗格中，点击请求流右上方的 + Add Policy Step（+ 添加政策步骤）按钮。

6. 选择 Create new policy（创建新政策），然后在“Traffic Management”（流量管理）部分的 select policy（选择政策）下，选择 Quota（配额），并将 Display Name（显示名称）和 Name（名称）设置为 Q-EnforceQuota。

7. 点击 Add（添加）。

8. 点击名称 Q-EnforceQuota。

   Quota（配额）配置显示在 Code（代码）窗格中。

9. 将配额配置更改为：

   <Quota continueOnError="false" enabled="true" name="Q-EnforceQuota" type="calendar"> <Identifier ref="client_id"/> <UseQuotaConfigInAPIProduct stepName="VAK-VerifyKey"> <DefaultConfig> <Allow>2</Allow> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> </DefaultConfig> </UseQuotaConfigInAPIProduct> <Distributed>true</Distributed> <Synchronous>true</Synchronous> <StartTime>2021-01-01 00:00:00</StartTime> </Quota>

   您将使用 API 产品来指定允许的速率。UseQuotaConfigInAPIProduct 元素中的 stepName 指定哪个步骤将确定 API 产品。

   API 密钥或 OAuth 令牌经过验证后，即可与已关联 API 产品的应用相关联。使用这些政策设置，名为 VAK-VerifyKey 的 VerifyAPIKey 步骤会确定 API 产品。VerifyAPIKey 政策必须在 Q-EnforceQuota 政策之前运行。

   配额政策中指定的默认配置值表示每 1 (Interval) 个月 (TimeUnit) 最多 2 (Allow) 个请求。只有在没有相应值时才会使用默认值，而只有在未为与 API 密钥关联的 API 产品设置配额设置时才会出现这种情况。

10. 点击 Save（保存）。如果您收到代理已另存为新修订版本的通知，请点击 SAVE AS NEW REVISION（另存为新修订版本）。

11. 点击 Deploy（部署）

12. 对于 Service account（服务账号），指定服务账号的邮箱：

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

13. 点击 Deploy（部署），然后点击 Confirm（确认）。

14. 点击 Overview（概览）标签页，然后等待 eval 部署状态显示代理已部署。

为完整访问权限 API 产品添加配额配置

1. 在 Apigee 导航菜单中，依次选择 Distribution > API Products（“分发”>“API 产品”），然后点击 bank（完整访问权限）。
2. 点击 Edit（修改）。
3. 在“Operations”（操作）部分的 bank-v1 行中，点击操作菜单图标 ()，然后选择 Edit（修改）。
4. 将操作的配额设置为每 1 分钟 5 个请求，然后点击 Save（保存）以保存该操作。

注意：请确保您正在修改操作中配置的配额。

5. 点击 Save（保存）以保存该 API 产品。

点击检查我的进度以验证是否完成了以下目标：强制执行配额

启动调试会话

Debug 是一种用于对 Apigee 上运行的 API 代理进行问题排查和监控的工具。借助 Debug 工具，您可以在 API 调用期间检查每个步骤的详细信息。

1. 在 Apigee 导航菜单中，依次选择 Proxy development > API Proxies（“代理开发”>“API 代理”），然后点击 bank-v1。

2. 点击 Debug（调试）标签页。

3. 点击 Start a debug session（启动调试会话）。

4. 在 Start a debug session（启动调试会话）窗格中，从环境下拉菜单中选择 eval。

5. 点击 Start（启动）。

   调试会话可能需要过一段时间才能开始捕获请求。

注意：如果您在屏幕顶部附近的红色框中看到错误消息，且提示内容类似“提取调试事务时出错”或“列出调试会话事务时出错”等说明，则您的调试会话可能仍能正常运行。

您将发出 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. 如果系统提示您进行授权，请点击授权。

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

3. 如需获取这两个 API 密钥，请运行以下命令：

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

4. 反复发送此请求，直到您收到配额失败消息：

   curl -i -k -X GET -H "apikey: ${API_KEY_READONLY}" "https://eval.example.com/bank/v1/customers" 注意：如需在 Cloud Shell 或 SSH 会话中快速重复执行某个命令，请点击向上键，然后按 RETURN 或 ENTER 键。

   您的配额违规将如下所示：

   {"fault":{"faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : bKSV3nOz2JS5Z58sWMh2RBnnwWeEeNK2N2G6HMCESgLGDLFI","detail":{"errorcode":"policies.ratelimit.QuotaViolation"}}}

5. 返回到 Apigee 界面标签页。

   您应该会看到一些 200 请求和一个 429 请求。

   点击某个 200 请求。事务地图右侧会显示一个工厂图标，表示已调用后端。

6. 在“Debug session”（调试会话）窗格中，点击左上角的向左箭头 (<)。

7. 在 Apigee 导航菜单中，依次选择 Proxy development > API Proxies（“代理开发”>“API 代理”），然后点击 bank-v1。

8. 点击 Debug（调试）标签页。

9. 点击 Start Debug Sessio（启动调试会话）以启动新的调试会话。

10. 返回到 SSH 会话，然后使用完整访问权限 API 密钥反复发送此请求，直到出现配额失败：

    date; curl -i -k -X GET -H "apikey: ${API_KEY_FULL}" "https://eval.example.com/bank/v1/customers"

    这次，您应该能够发送至少 5 个请求，然后才会因收到 429 响应而被拒绝。完整访问权限 API 产品的配额为每分钟 5 个请求。当时间的秒数部分重置为零时，配额会重置。上述命令会输出调用 API 之前的时间，因此您应该能够看到配额重置的大致时间。

11. 输入 exit 以退出虚拟机 SSH 会话。

12. 返回到 Apigee 界面标签页。

    如果您选择一个请求并点击配额图标，则会看到 VAK-VerifyKey 配额变量现在指示每 1 分钟 5 个请求。

任务 5. 向 API 代理添加 CORS

在此任务中，您将向 bank-v1 代理添加 CORS（跨域资源共享）。

CORS 是一种协议，它使用 HTTP 标头向浏览器指示是否可以安全地从单独的网域访问受限资源。默认情况下，同源安全政策会禁止跨网域请求。同源政策可保护浏览器用户免遭作恶方窃取会话信息。

同源政策意味着，默认情况下，从 www.example.com 提供的网页无法调用 api.example.com 中的 API，因为主机名不同。CORS 可用于允许此类跨源访问。

您需要在 bank API 中为开发者门户添加 CORS。Apigee 开发者门户的域名为 *.apigee.io，而 API 是通过其他网域进行访问。为了从文档中调用 API，您需要向所有 API 响应（包括错误响应）添加 CORS 标头。

CORS 也使用预检请求。浏览器会使用 OPTIONS 动词发送预检请求，以确定是否允许进行下一次调用。

CORS 政策可以处理所有 CORS 功能。

如需详细了解 CORS，请参阅 Apigee CORS 文档。

添加 CORS 政策

1. 在 Apigee 导航菜单中，依次选择 Proxy development > API Proxies（“代理开发”>“API 代理”），然后点击 bank-v1。

2. 点击 Develop（开发）标签页。

3. 在代理的导航菜单中，点击 Proxy Endpoints（代理端点）部分中的 PreFlow。

4. 在 Flow（流）窗格中，点击请求流右上方的 + Add Policy Step（+ 添加政策步骤）按钮。

5. 选择 Create new policy（创建新政策），然后在“Security”（安全）部分的 select policy（选择政策）下，选择 CORS，并将 Display Name（显示名称）和 Name（名称）设置为 CORS。

6. 点击 Add（添加）。

   CORS 政策配置显示在“Flow”（流）窗格下方。

   AllowOrigins 列出了允许的源。默认配置允许任何源，因为它会将允许的源设置为请求中传递的源。在典型的生产应用场景中，您可能只允许来自特定主机名的请求。

   AllowMethods 用于指定 API 允许的请求方法。

   AllowHeaders 列出了可在请求中传递的标头。

   ExposeHeaders 用于指定当接收到来自某个源的调用时，响应中应允许暴露的标头。如果默认值为 *，则不会从响应中删除任何响应标头。

   MaxAge 用于指定预检响应可被浏览器缓存的时长（以秒为单位）。

   AllowCredentials 用于指示是否可以在请求中发送授权标头、TLS 客户端证书或 Cookie。

   GeneratePreflightResponse 用于指定是否将处理使用 OPTIONS 方法的预检请求。

7. 点击名称 CORS。

8. 将 AllowHeaders 配置替换为：

   <AllowHeaders>origin, x-requested-with, accept, content-type, apikey</AllowHeaders>

   您的 API 使用 apikey 标头来指定 API 密钥，因此必须添加该标头，以便可以从浏览器调用该 API。

9. 将 MaxAge 值替换为 -1。

   这样会停用浏览器对预检响应的缓存，以便您始终看到预检请求。在生产应用场景中，您通常会允许缓存响应，以避免每个请求进行两次调用。

10. 在代理的导航菜单中，点击 Proxy Endpoints（代理端点）部分中的 PreFlow。

    添加 CORS 政策时，系统会自动将其添加到流程末尾。不过，对于预检请求，不应要求提供 API 密钥。

11. 通过修改 PreFlow 配置，将 CORS 政策移到 VAK-VerifyKey 政策之前。将

    <PreFlow name="PreFlow"> <Request> <Step> <Name>VAK-VerifyKey</Name> </Step> <Step> <Name>Q-EnforceQuota</Name> </Step> <Step> <Name>CORS</Name> </Step> </Request> <Response/> </PreFlow>

    替换为：

    <PreFlow name="PreFlow"> <Request> <Step> <Name>CORS</Name> </Step> <Step> <Name>VAK-VerifyKey</Name> </Step> <Step> <Name>Q-EnforceQuota</Name> </Step> </Request> <Response/> </PreFlow>

12. 点击 Save（保存）。如果您收到代理已另存为新修订版本的通知，请点击 SAVE AS NEW REVISION（另存为新修订版本）。

13. 点击 Deploy（部署）。

14. 对于 Service account（服务账号），指定服务账号的邮箱：

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

15. 点击 Deploy（部署），然后点击 Confirm（确认）。

16. 点击 Overview（概览）标签页，然后等待 eval 部署状态显示代理已部署。

点击检查我的进度以验证是否完成了以下目标：向 API 代理添加 CORS

启动调试会话

1. 点击 Debug（调试）标签页。

2. 点击 Start a debug session（启动调试会话）。

3. 在 Start a debug session（启动调试会话）窗格中，从环境下拉菜单中选择 eval。

4. 点击 Start（启动）。

   调试会话可能需要过一段时间才能开始捕获请求。

测试 CORS 功能

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. 如果系统提示您进行授权，请点击授权。

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

3. 如需获取 API 密钥，请运行以下命令：

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

4. 发出请求以检索客户名单：

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

   由于没有源，因此系统会跳过 CORS 功能。确认未返回 Access-Control-Allow-Origin 标头。

5. 再发出一个请求，但这次要包含 Origin 标头。此测试用于测试正常的 CORS 请求：

   curl -i -k -X GET -H "Origin: https://www.example.com" -H "apikey: ${API_KEY}" "https://eval.example.com/bank/v1/customers"

   由于提供了 Origin，因此返回了 access-control-* 标头。

6. 发出预检请求：

   curl -i -k -X OPTIONS -H "Origin: https://www.example.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type,apikey" "https://eval.example.com/bank/v1/customers"

   CORS 政策会在响应中设置预检标头，并阻止请求继续传递到后端。

   如果您返回到 Apigee 界面，并在 Debug 工具中查看 OPTIONS 调用，则可以确认 CORS 政策未允许该调用传递到后端服务。

7. 输入 exit 以退出虚拟机 SSH 会话。

任务 6. 下载和修改 OpenAPI 规范

在此任务中，您将下载并修改用于定义 API 代理接口的 OpenAPI 规范。

将 API 代理发布到开发者门户时，将用到 OpenAPI 规范。

下载并修改 OpenAPI 规范

1. 在 Cloud Shell 中，运行以下命令，下载 API 代理的 OpenAPI 规范：

   curl https://storage.googleapis.com/spls/shared/firestore-simplebank-data/dev-portal/simplebank-spec.yaml?$(date +%s) --output ~/simplebank-spec.yaml

   此 curl 命令会下载名为 simplebank-spec.yaml 的文件，并将其存储在主目录中同名的文件中。

注意：“?$(date +%s)”会向网址添加一个查询参数，该参数是当前日期/时间的字符串表示形式。此动态变化的变量会更改网址，并强制 curl 检索文件的最新版本，即使之前版本已缓存也是如此。

2. 在 Cloud Shell 中，点击打开编辑器，然后根据需要点击在新窗口中打开。

   

3. 在编辑器中，选择 simplebank-spec.yaml 文件。

   此 OpenAPI 规范指定了您在本实验期间已创建的 API 代理的接口。该规范将用于在开发者门户中提供实时文档。

   开发者门户从外部网络访问 Apigee 代理。您一直使用的主机名 eval.example.com 仅在内部网络中可用。

   已预配负载均衡器，以提供对 API 代理的外部访问权限。外部访问使用 nip.io（通配符 DNS 提供商）提供的主机名。

   外部主机名将类似于以下内容：

   eval.60.70.80.90.nip.io

   此主机名已指定为 eval-group 环境组的匹配主机名。

4. 在 Cloud Shell 中，如需检索 eval-group 设置，请使用以下命令：

   curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/envgroups/eval-group"

   hostnames 数组包含两个主机名：一个不含 IP 地址 (eval.example.com)，另一个包含 IP 地址（类似于 eval.60.70.80.90.nip.io）。您将在 OpenAPI 规范中使用包含 IP 地址的主机名。

5. 在编辑器中，替换第 10 行的主机名：

   eval.<IPADDR>.nip.io

   替换服务器网址中的主机名后，第 10 行应如下所示：

   - url: "https://eval.60.70.80.90.nip.io/bank/v1"

6. 依次点击文件 -> 保存。

7. 右键点击 simplebank-spec.yaml > 下载。

   这会将该文件下载到您的本地机器。您将使用更新后的规范与开发者门户交互。

任务 7. 创建开发者门户并向其中发布 API

在此任务中，您将创建一个集成式开发者门户，然后将 API 发布到该门户。

创建集成式开发者门户

1. 在 Apigee 导航菜单中，依次选择 Distribution > Portals（“分发”>“门户”），然后点击 + CREATE（+ 创建）。

2. 输入 bank 作为名称，然后点击 Create（创建）。

   创建过程可能需要一分钟时间，然后门户概览页面应该会打开。

3. 如果系统显示“Enroll in beta for team and audience management features”（注册团队和受众群体管理功能 Beta 版）消息，请点击 Enroll（注册）。

将 API 发布到门户

1. 在 Apigee 导航菜单中，依次选择 Distribution > Portals（“分发”>“门户”），然后点击 bank。

2. 点击 + API（添加 API）。

3. 选择 bank（完整访问权限）作为 API 产品。

4. 自定义 API 详细信息：

   属性	值
   已发布（在目录中列出）	已选择
   显示标题	SimpleBank
   显示说明	SimpleBank API v1
   API 公开范围	选择“公开（所有人都可以看到）”

   “已发布”可让 API 在门户中显示，而将公开范围设为“公开”可让用户即使未登录门户也能看到 API。

5. 在 Display Image 中点击 Select（选择），然后点击 URL（网址）。

6. 将图片网址设置为：

   https://storage.googleapis.com/spls/shared/firestore-simplebank-data/dev-portal/piggy-bank.png

   点击 PREVIEW（预览）后，您应该会看到存钱罐的图片。

7. 点击 Select（选择）。

8. 在 API documentation（API 文档）部分，选择 OpenAPI document（OpenAPI 文档）。

9. 在 Select File 中，点击 Select（选择）。

10. 点击 Browse（浏览），然后选择您从 Cloud Shell 下载的 OpenAPI 规范文件 (simplebank-spec.yaml)。

11. 点击 Select（选择）。

12. 点击 Save（保存）。

13. 如需在新标签页中打开开发者门户，请点击右上角的 VIEW LIVE PORTAL（查看实时门户）。

点击检查我的进度以验证是否完成了以下目标：创建开发者门户并向其中发布 API

启动调试会话

1. 返回到 Apigee 导航菜单，依次选择 Proxy development > API Proxies（“代理开发”>“API 代理”），然后点击 bank-v1。
2. 点击 Debug（调试）标签页。
3. 在 Start a debug session（启动调试会话）窗格中，从环境下拉菜单中选择 eval。
4. 点击 Start（启动）。

使用开发者门户测试 API

1. 在 Cloud Shell 中，运行以下命令以获取完整访问权限 API 密钥：

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

   将 API 密钥复制到剪贴板。

2. 返回到“实时门户”标签页，然后点击 API。

3. 点击存钱罐。

   系统会显示 SimpleBank API。

4. 点击授权。

5. 将 API 密钥粘贴到密钥中。

6. 点击授权，然后点击确定。

   现在，系统会随任何请求一起发送 API 密钥。

7. 在左侧菜单中，点击 /customers POST。

8. 指定以下请求正文：

   { "email": "mina@example.com", "lastName": "Yu", "firstName": "Mina" }

9. 点击执行。

   200 OK 响应表示已创建客户。

10. 在左侧菜单中，点击 /customers GET。

11. 点击执行。

    您刚刚创建的客户会与数据库中的其他客户一起返回。

    如果您返回到 Apigee 界面和调试会话，则会看到浏览器在发送这两个命令之前自动发送了一个 OPTIONS（预检）请求。在 GET 命令之前需要发送预检请求，因为浏览器不知道是否应允许 apikey 标头。

任务 8. 在门户中创建应用开发者（可选）

在此任务中，您将使用开发者门户创建应用开发者。

注意：此任务需要您输入邮箱，以便接收注册邮件。该邮件包含一个链接，您必须点击该链接，注册的账号才能登录开发者门户。该邮箱将不会用于任何其他用途，并且会在 Google Cloud 项目自动删除时一并删除。

在开发者门户中注册应用开发者

1. 返回到“实时门户”，然后点击登录。

2. 点击创建账号。

3. 输入名字、姓氏、邮箱和密码。

   您需要使用此密码登录开发者门户，因此请确保密码便于记忆。

4. 点击表示您同意相关条款的复选框。

   “条款及条件”页面将由向应用开发者提供 API 的组织指定。

5. 点击创建账号

   系统会向您的邮箱发送一封邮件。其中包含一个链接，必须点击该链接才能允许账号用户登录。

6. 点击邮件中的链接。

   系统会打开一个浏览器标签页，其中显示开发者门户。

7. 点击登录。

8. 输入邮箱和密码，然后点击登录。

为应用开发者创建应用

1. 点击右上角的邮箱，然后点击应用。

2. 点击 + 新建应用。

3. 将 MyApp 指定为应用名称。

4. 在“API”部分中，针对 SimpleBank 点击启用。

5. 点击保存。

   应用已注册，并且系统会显示 API 密钥。此 API 密钥可在开发者门户中使用。返回 Apigee 界面，然后分别前往 Publish > Developers（“发布”>“开发者”）和 Publish > Apps（“发布”>“应用”），即可查看应用开发者和应用。

恭喜！

在本实验中，您使用了 API 密钥验证来限制对 API 的访问。您创建了 API 产品，以便为内部和外部应用开发者提供不同级别的服务。您使用了配额政策来限制每个应用的调用次数，并添加了 CORS 政策以支持 API 中的跨域资源共享。您创建了开发者门户，并发布了 API 产品，供应用开发者使用。

后续步骤/了解详情

• API 产品
• CORS（跨域资源共享）
• 开发者门户

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

本手册的最后更新时间：2025 年 8 月 5 日

本实验的最后测试时间：2025 年 8 月 5 日

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