Cloud Endpoints 快速入门

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

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

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

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

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册一个新帐号

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Google Cloud 项目已启用结算功能。 了解如何确认您的项目已启用结算功能

启动 Cloud Shell

  1. 在 Cloud Console 中,确保系统当前显示的是您要用于示例 API 的项目。

  2. 打开 Cloud Shell。

    打开 Cloud Shell

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

    Cloud Shell 会话

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

    gcloud components update
    

获取示例代码

  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 会向 Cloud Console 输出信息。您尽可忽略有关 openapi.yaml 中的路径未要求 API 密钥的警告。成功完成后,您会看到如下所示的行,其中会显示服务配置 ID 和服务名称:

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

启用必需服务

要使用 Endpoints,需要至少启用以下 Google 服务:

姓名 说明
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

在大多数情况下,部署 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,该参数设置为 SEAJFK 等有效 IATA 机场代码。例如:

./query_api.sh JFK

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

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

跟踪 API 活动

通过 Endpoints 部署 API,您可以在 Cloud Console 中监控关键运维指标,并通过 Cloud Logging 深入了解您的用户和使用情况。

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

    ./generate_traffic.sh
    
  2. 在 Cloud Console 中,查看 API 的活动图表。

    转到“Endpoints 服务”页面

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

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

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

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

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

  4. 打开 Cloud Shell。

    打开 Cloud Shell

  5. 如需停止脚本运行,请按 Ctrl+C

向 API 添加配额

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

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

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    

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

  2. 在 Cloud Console 中,转到凭据页面。

    转到“凭据”页面

  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 秒后,按 Ctrl-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 帐号收取费用,请按照以下步骤操作。

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

  1. 在 Cloud Console 中,转到管理资源页面。

    转到“管理资源”页面

  2. 在项目列表中,选择要删除的项目,然后点击删除
  3. 在对话框中输入项目 ID,然后点击关闭以删除项目。

后续步骤