添加 API 管理

Cloud Endpoints Frameworks 提供的 API 管理功能与 Extensible Service Proxy (ESP) 为 Cloud Endpoints 提供的功能相近。Endpoints Frameworks 内置了一个 API 网关,该网关会拦截所有请求并执行所有必要的检查(例如身份验证),然后将请求转发到 API 后端。当后端响应时,Endpoints Frameworks 会收集遥测数据并进行报告。您可以在 Google Cloud Console 中的 Endpoints > 服务页面上查看 API 的指标。

Endpoints Frameworks 中提供了以下 API 管理功能:

要将您的 API 交给 Endpoints 来管理,您必须根据 2.0 版 OpenAPI 规范部署一个用于描述您的 API 的 OpenAPI 文档。 本页面介绍如何生成和部署 OpenAPI 文档,以借助 Endpoints 来管理您的 API。

如果您未添加 API 管理功能,您的 API 仍会处理请求,但它不会显示在 Cloud Console 的 Endpoints > 服务页面上,并且 Endpoints 提供的功能(例如日志记录、监控和设置配额)也不可用。

安装和配置所需的软件

如果尚未进行此操作,请安装和配置适用于 Python 的 Cloud SDK,并将 Endpoints Frameworks Python 库添加到您的 API 项目目录,以便在部署时随 API 代码一起上传

安装和配置适用于 Python 的 Cloud SDK

  1. 安装并初始化 Cloud SDK:

    下载并安装 Cloud SDK

  2. 安装包含 App Engine Python 扩展程序的 gcloud 组件:

    gcloud components install app-engine-python
    
  3. 更新 Cloud SDK:

    gcloud components update
    
  4. 确保 Cloud SDK 有权访问您在 Google Cloud 上的数据和服务:

    gcloud auth login
    

    您的浏览器会打开一个新标签页,并提示您选择一个帐号。

  5. 将默认项目设置为您的项目 ID。将 YOUR_PROJECT_ID 替换为您的 Cloud 项目 ID。

    gcloud config set project YOUR_PROJECT_ID
    
  6. 对于 Linux,将 ENDPOINTS_GAE_SDK 环境变量设置为您的 App Engine SDK 文件夹路径:

    PATH_TO_CLOUD_SDK/platform/google_appengine
    

    PATH_TO_CLOUD_SDK 替换为以下命令的输出:

    gcloud info --format="value(installation.sdk_root)"
    

添加 Endpoints Frameworks Python 库

  1. 确保您可以编译 Python 版 C 扩展程序。

    • Windows:需要 Microsoft Visual C++ 9.0 或更高版本。您可以从 Microsoft 下载中心下载适用于 Python 的 Microsoft Visual C++ 编译器 2.7 版

    • 其他操作系统:根据您使用的操作系统,您可能需要安装编译器工具(有时包含在软件包 build-essential 中)和/或 Python 开发头文件(有时包含在软件包 python-dev 中)。

  2. 将目录更改为 API 的主目录。

  3. 在 API 的主目录中创建一个 /lib 子目录:

    mkdir lib
    
  4. 安装库:

    pip install -t lib google-endpoints --ignore-installed
    

生成 OpenAPI 文档

在 API 的主目录中,使用框架工具生成 OpenAPI 文档。例如:

单个类

在以下命令中,将 YOUR_PROJECT_ID 替换为您的 Cloud 项目 ID。

python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \
    --hostname YOUR_PROJECT_ID.appspot.com

忽略显示的警告。

多个类

您可以使用命令行列出多个类。Endpoints 会为每个 API 名称/版本组合生成一个 OpenAPI 文档。

如果您想要将 API 名称不同的多个 API 类作为同一项服务的多个部分进行部署,则还必须添加 --x-google-api-name 标志。启用此标志会给您的 API 名称带来额外的限制。具体来说,名称必须与正则表达式 [a-z][a-z0-9]{0,39} 相匹配;也就是说,名称必须包含 1 至 40 个字符,这些字符可以全部为小写字母字符或数字,但第一个字符不能是数字。例如:

在以下命令中,将 YOUR_PROJECT_ID 替换为您的 Cloud 项目 ID。

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname YOUR_PROJECT_ID.appspot.com \
   --x-google-api-name

忽略显示的警告。

Endpoints 会使用您在 hostname 参数中指定的文本作为服务名称。将 API 部署到 App Engine 时,系统会自动创建名称格式为 YOUR_PROJECT_ID.appspot.com 的 DNS 条目。

部署 OpenAPI 文档

单个类

gcloud endpoints services deploy echov1openapi.json

多个类

如果您有多个 OpenAPI 文档,可使用命令行列出所有文档。 例如:

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

第一次部署一或多个 OpenAPI 文档时,系统将使用名称 YOUR_PROJECT_ID.appspot.com 创建一项新的 Endpoints 服务。

成功完成后,您会看到如下所示的行,其中显示了服务配置 ID 和服务名称:

Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com

在上面的示例中,2017-02-13r0 是服务配置 ID。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您再次部署 OpenAPI 文档,则服务配置 ID 中的修订号会递增。

如果您需要再次显示服务配置 ID,请运行以下命令,但需将 YOUR_PROJECT_ID 替换为 Cloud 项目的项目 ID:

gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com

您可以创建自己的 OpenAPI 文档并进行部署,而不使用生成的文档。只需将上述 echov1openapi.json 替换为 OpenAPI 文档的路径即可。如需详细了解如何编写 OpenAPI 文档,请参阅 OpenAPI 概览

重新部署您的 API 并进行测试

  1. 按如下方式修改项目的文件 app.yaml 并添加 env_variables 部分:

    env_variables:
      ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
    

    YOUR_PROJECT_ID 替换为您的 Cloud 项目 ID,并将 YOUR_SERVICE_VERSION 替换为上一部分中的服务配置 ID。将这些信息添加到 app.yaml 文件后,Endpoints 便会在您重新部署应用后对 API 实施管理。

  2. 重新部署应用:

    gcloud app deploy
    
  3. 等待部署成功完成,忽略警告消息。部署完成后,系统将显示如下所示的消息:

    File upload done.
    Updating service [default]...done.
    
  4. 使用 curl 等命令测试重新部署操作是否成功:

    curl --request POST \
        --header "Content-Type: application/json" \
        --data '{"content":"echo"}' \
        https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2
    

    echo 替换为您的 API 名称。

    结果应如下所示:

    {
     "content": "echo echo"
    }
    
  5. 向您的 API 发出一些其他请求。

  6. 查看 API 指标,请在 Cloud Console 中打开项目的 Endpoints > 服务页面:

    转到“Endpoints 服务”页面