部署由 Cloud Endpoints 管理的 API

部署由 Cloud Endpoints 管理的 API

本快速入门将引导您部署一个由 Endpoints 管理的示例 API。示例代码包括以下内容：

• 用于根据机场的三字母 IATA 代码查找机场名称的 REST API。
• 用于将 API 配置上传到 Endpoints 的脚本。
• 用于部署 App Engine 柔性环境后端来托管示例 API 的脚本。

向示例 API 发送请求后，您可以在 Google Cloud 控制台中查看 Endpoints 活动图表和 Google Cloud Observability 日志。您可以通过这些工具来监控 API 并详细了解其使用情况。

本快速入门使用脚本简化配置步骤，让您快速了解活动图表和日志的实际运用。如需了解如何配置和部署示例 API，请选择与以下任一 API 框架相关的教程：

• 适用于 OpenAPI 的 Cloud Endpoints：教程
• 适用于 gRPC 的 Cloud Endpoints：教程
• Cloud Endpoints Frameworks：教程

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

启动 Cloud Shell

1. 在 Google Cloud 控制台中，确保您正在使用 用于示例 API。

2. 打开 Cloud Shell。

   打开 Cloud Shell

   一个 Cloud Shell 会话随即会在 Google Cloud 控制台底部的新框内打开，并显示命令行提示符。该会话可能需要几秒钟来完成初始化。

   

3. 如果您使用的是现有项目，请确保所有已安装的 gcloud 组件均为最新版本：

   gcloud components update
   

注意：如果您使用的是 Linux 或 MacOS 机器，并且希望使用本地 shell 按照本快速入门进行操作，请下载 Google Cloud CLI，然后使用本地命令行界面（而不是 Cloud Shell）执行快速入门的操作说明。

获取示例代码

1. 在 Cloud Shell 中，输入以下命令来获取示例 API 和脚本：

   git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
   

2. 切换到包含示例代码的目录：

   cd endpoints-quickstart
   

部署 Endpoints 配置

如需将 REST API 发布到 Endpoints，需要一个用于描述该 API 的 OpenAPI 配置文件。示例 API 附有一个名为 openapi.yaml 的预配置 OpenAPI 文件。

Endpoints 使用 Google Cloud 基础架构服务 Service Management 创建并管理 API 和服务。如需使用 Endpoints 管理 API，请将 API 的 OpenAPI 配置文件部署到 Service Management。

如需部署 Endpoints 配置，请执行以下操作：

1. 在 Cloud Shell 中，进入 endpoints-quickstart 目录，然后输入以下命令：

   cd scripts
   

2. 运行示例中包含的以下脚本：

   ./deploy_api.sh
   

Endpoints 使用 OpenAPI 配置文件中的 host 字段标识服务。deploy_api.sh 脚本将 Google Cloud 项目 ID 设置为 host 字段中所配置的名称的一部分。 在为您自己的服务准备 OpenAPI 配置文件时，需要手动执行此操作。

随后，该脚本将使用以下命令将 OpenAPI 配置部署到 Service Management：gcloud endpoints services deploy openapi.yaml

在创建和配置服务时，Service Management 会向 Google Cloud 控制台输出信息。您尽可忽略有关 openapi.yaml 中的路径未要求 API 密钥的警告。成功完成后，您会看到如下所示的行，其中会显示服务配置 ID 和服务名称：

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

启用必需服务

要使用 Endpoints，需要至少启用以下 Google 服务：

姓名	标题
endpoints.googleapis.com	Google Cloud Endpoints
servicecontrol.googleapis.com	Service Control API
servicemanagement.googleapis.com	Service Management API

在大多数情况下，部署 Endpoints 配置可启用这些必需服务。

使用以下命令确认必需服务是否已启用：

gcloud services list

如果您没有看到列出的必需服务，请启用它们：

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

同时启用 Endpoints 服务：

gcloud services enable YOUR-PROJECT-ID.appspot.com

如需详细了解 gcloud 命令，请参阅 gcloud 服务。

部署 API 后端

到目前为止，您已将 OpenAPI 配置部署到 Service Management，但尚未部署将服务 API 后端的代码。示例中包含的 deploy_app.sh 脚本会创建一个 App Engine 柔性环境来托管 API 后端，然后将 API 部署到 App Engine。

要部署 API 后端，请执行以下操作：

• 在 Cloud Shell 中，进入 endpoints-quickstart/scripts 目录，然后运行以下脚本：

  ./deploy_app.sh
  

该脚本将运行以下命令，以便在 us-central 区域中创建 App Engine 柔性环境：gcloud app create --region="$REGION"

创建 App Engine 柔性环境后端需要几分钟的时间。创建该应用后，输出为：

Success! The app is now created.

接下来，该脚本会运行 gcloud app deploy 命令来将示例 API 部署到 App Engine。

输出为：

Deploying ../app/app_template.yaml...You are about to deploy the following services:

将 API 部署到 App Engine 需要几分钟的时间。在将 API 成功部署到 App Engine 后，输出为：

Deployed service [default] to [https://example-project.appspot.com]

向 API 发送请求

• 在 Cloud Shell 中，可以在部署示例 API 后运行以下脚本来向其发送请求：

  ./query_api.sh
  

该脚本会回显其用于向 API 发送请求的 curl 命令，然后显示结果。输出为：

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

API 需要一个查询参数 iataCode，该参数设置为 SEA 或 JFK 等有效 IATA 机场代码。例如：

./query_api.sh JFK

注意：App Engine 可能需要几分钟时间才能成功响应请求。如果您在发送请求后收到 HTTP 502、503 或其他一些服务器错误，请稍等一下再重新发送请求。

您刚刚在 Endpoints 中部署并测试了一个 API！

注意：如果您想告诉我们您对本教程的看法，请在本页底部提供反馈。您的反馈有助于我们改进这些教程。
如果您遇到错误，请加入 google-cloud-endpoints Google 群组，告诉我们您遇到的问题。在该论坛中，您会收到来自其他 Endpoints 用户和负责监控该论坛的 Google 工程师的回复。

跟踪 API 活动

通过使用 Endpoints 部署的 API，您可以监控 Google Cloud 控制台中的运维指标，并深入了解您的 了解用户数量和使用情况

1. 在 Cloud Shell 中，运行流量生成脚本来填充图表和日志：

   ./generate_traffic.sh
   

   注意 ：此脚本会在循环中生成请求，并自动超时 5 分钟后开始。如需更快地结束脚本，请在 Cloud Shell 中按 Control+C。

2. 在 Google Cloud 控制台中，查看 API 的活动图表。

   转到“Endpoints 服务”页面

   这些请求可能需要一些时间才能体现在图表中。 在等待显示数据期间：

   • 如果“权限”侧边面板未打开，请点击 +权限。 您可以使用“权限”面板控制哪些用户有权访问您的 API 以及控制访问权限级别。

   • 点击部署记录。此标签页将显示您的 API 部署记录，包括部署时间和部署更改的人员。

   • 点击概览。您会看到传入流量。在流量生成脚本运行一分钟后，您会在总延迟时间图表上看到三行数据（第 50 百分位、第 95 百分位和第 98 百分位）。这些数据用于估算响应时间。

3. 向下滚动到图表下方的表格，在链接下，针对 GET/airportName 点击查看日志。日志浏览器页面将显示该 API 的请求日志。

4. 打开 Cloud Shell。

   打开 Cloud Shell

5. 如需停止脚本运行，请按 Control+C。

向 API 添加配额

Beta 版

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

Endpoints 允许您通过设置配额来控制应用调用 API 的速率。您可以使用配额防止某个客户端过度使用您的 API。

1. 在 Cloud Shell 中，部署具有配额的 Endpoints 配置。

   ./deploy_api.sh ../openapi_with_ratelimit.yaml
   

   部署更新的 Endpoints 配置后，该配置将在一分钟内生效。

2. 在 Google Cloud 控制台中，转到凭据页面。

   转到“凭据”页面

3. 点击创建凭据，然后点击 API 密钥。屏幕上会显示新的 API 密钥。

4. 点击复制。

5. 在 Cloud Shell 中，输入以下命令。将 YOUR_API_KEY 替换为刚创建的 API 密钥。

   export API_KEY=YOUR_API_KEY
   

6. 使用刚刚生成的 API 密钥向您的 API 发送请求。

   ./query_api_with_key.sh $API_KEY
   

   输出类似于以下内容：

   curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
   San Francisco International Airport
   

7. 现在，API 每分钟最多接受 5 个请求。运行以下命令，将流量发送到 API 并触发配额限制。

   ./generate_traffic_with_key.sh $API_KEY
   

8. 脚本运行 5-10 秒后，按 Control+C 以停止脚本。

9. 向 API 发送另一个已通过身份验证的请求。

   ./query_api_with_key.sh $API_KEY
   

   输出类似于以下内容：

   {
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
     {
      "@type": "type.googleapis.com/google.rpc.DebugInfo",
      "stackEntries": [],
      "detail": "internal"
     }
    ]
   }
   

如果您收到其他响应，请再次尝试运行 generate_traffic_with_key.sh 脚本，然后重试操作。

恭喜！您已成功限制了 API 的速率。您还可以对不同的 API 方法设置不同的限制，创建多种配额，以及跟踪哪些使用方使用哪些 API。

如需了解详情，请参阅配额简介。

为 API 创建开发者门户

您可以使用 Cloud Endpoints 门户来创建开发者门户，一个供您与示例 API 进行交互的网站。如需了解详情，请参阅 Cloud Endpoints 门户概览。

清理

为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用，请按照以下步骤操作。

为避免产生费用，您可以删除 Google Cloud 项目，以停止对该项目中使用的所有资源计费。

注意：删除项目会产生以下影响：
• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

后续步骤

• 如需概括了解 Endpoints，请参阅以下内容：

  • 关于 Endpoints
  • Endpoints：架构概览

• 如需了解 Endpoints 支持的各种 API 框架，请参阅以下内容：

  • OpenAPI 规范
  • 适用于 gRPC API 的 Endpoints
  • Endpoints Frameworks 简介

• 如需了解如何配置和部署示例 API，请选择与以下任一 API 框架相关的教程：

  • 适用于 OpenAPI 的 Endpoints：教程
  • 适用于 gRPC 的 Endpoints：教程
  • Endpoints Frameworks：教程