适用于 Python 的 Cloud Endpoints Frameworks 使用入门


本页面介绍了如何使用 Python 版 Cloud Endpoints Frameworks 配置、部署示例 API 以及向其发送请求。Python 版 Endpoints Frameworks 与 App Engine 标准 Python 2.7 运行时环境集成。Endpoints Frameworks 具备各种工具、库和功能,可供您通过 App Engine 应用生成 API 和客户端库。

目标

学习本教程时,请使用以下概要任务列表。为确保请求成功发送到 API,您必须完成所有任务。

  1. 设置 Google Cloud 项目。请参阅准备工作
  2. 安装所需的软件并创建 App Engine 应用。请参阅安装和配置所需的软件
  3. 下载示例代码。请参阅获取示例代码
  4. 生成 OpenAPI 文档。请参阅配置 Endpoints
  5. 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置
  6. 在计算机上运行该示例。请参阅在本地运行示例
  7. 创建后端,以提供 API 并部署 API。请参阅部署 API 后端
  8. 向 API 发送请求。请参阅向 API 发送请求
  9. 跟踪 API 活动。请参阅跟踪 API 活动
  10. 避免系统向您的 Google Cloud 账号收费。请参阅清理

费用

在本文档中,您将使用 Google Cloud 的以下收费组件:

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用

完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. 确保您的 Google Cloud 项目已启用结算功能

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

    Go to project selector

  5. 确保您的 Google Cloud 项目已启用结算功能

  6. 记下 Google Cloud 项目 ID,稍后需要用到。

安装和配置所需的软件

  1. 按照安装 Python 版 Google Cloud CLI 中的说明获取 App Engine 标准开发环境设置。请务必安装 app-engine-pythonapp-engine-python-extras gcloud 组件。
  2. 运行以下命令:
    1. 更新 gcloud CLI。
      gcloud components update
    2. 确保 Google Cloud CLI (gcloud) 有权访问您在 Google Cloud 上的数据和服务:
      gcloud auth login
    3. 在浏览器打开的新标签页中选择账号。
    4. 将默认项目设置为您的项目 ID。
      gcloud config set project [YOUR_PROJECT_ID]

      [YOUR_PROJECT_ID] 替换为您的 Google Cloud 项目 ID。如果您有其他 Google Cloud 项目,并且想使用 gcloud 来管理这些项目,请参阅管理 gcloud CLI 配置

  3. 您需要一个应用来向示例 API 发送请求

    • Linux 和 macOS 用户:本教程提供了一个使用 curl 的示例,它通常已预装在您的操作系统中。如果您没有 curl,可以从 curl 版本和下载页面中下载。
    • Windows 用户:本教程提供了一个使用 Invoke-WebRequest 的示例,PowerShell 3.0 及更高版本支持该命令。
  4. 确保您的 python 开发环境包括 pip
  5. 确保您可以编译 Python 版 C 扩展程序。
    • Windows:需要 Microsoft Visual C++ 9.0 或更高版本。您可以从 Microsoft 下载中心下载 Microsoft Visual C++ 编译器(Python 2.7 版)
    • 其他操作系统:根据您使用的操作系统,您可能需要安装编译器工具(有时包含在软件包 build-essential 中)或 Python 开发头文件(有时包含在软件包 python-dev 中)。
  6. 对于 Linux,将 ENDPOINTS_GAE_SDK 环境变量设置为您的 App Engine SDK 文件夹路径:[Path-to-Google-Cloud-SDK]/platform/google_appengine

    [Path-to-Google-Cloud-SDK] 替换为以下命令的输出:

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

  7. 创建 App Engine 应用:
    1. 选择要在其中创建 App Engine 应用的区域。运行以下命令以获取区域列表:
      gcloud app regions list
    2. 使用以下命令创建 App Engine 应用。将 [YOUR_PROJECT_ID] 替换为您的 Google Cloud 项目 ID,并将 [YOUR_REGION] 替换为您要在其中创建 App Engine 应用的区域。
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      例如:

      gcloud app create --project=example-project-12345 --region=us-central

获取示例代码

要从 GitHub 克隆示例 API,请执行以下操作:

  1. 将示例代码库克隆到本地计算机:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. 切换到包含示例代码的目录:

    cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    

配置 Endpoints

要配置 Endpoints,首先必须安装 Endpoints Frameworks Python 库。然后,您可以使用 Endpoints Frameworks 库中的工具为示例 API 生成 OpenAPI 文档。您需要使用 Endpoints Frameworks 库和 OpenAPI 文档,以便 Endpoints 可以管理 API。如需了解详情,请参阅添加 API 管理

安装 Endpoints Frameworks 库

本部分逐步介绍如何使用 Python 的 pip 向示例 API 的项目目录添加 Endpoints Frameworks 库。

如需将 Endpoints Frameworks 库添加到示例,请执行以下操作:

  1. 请确保您位于示例 API 的主目录 python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo 中。

  2. 在项目中创建一个 /lib 子目录:

    mkdir lib
    
  3. 在示例主目录 python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo 中,运行安装命令:

    pip install --target lib --requirement requirements.txt --ignore-installed
    

    请注意以下事项:

    • pip 命令可使用 GNU 编译器集合 (GCC) 来编译扩展程序模块。如果您使用的是 macOS,并且是第一次在系统上运行 GCC,则可能必须接受 Apple 的 XCode 许可。为此,请运行 sudo xcodebuild -license

    • 如果您的计算机上安装了多个 Python 版本,请确保所用的 pip 版本与您将在本教程中使用的 Python 版本对应。版本不一致(例如,pip 的版本为 Python 3.4,而所用的 python 的版本为 Python 2.7)可能导致难以理解的错误。如果需要,您可以将 pip 作为 Python 模块运行:将上述命令中的 pip 替换为 python -m pip

    • 如果 pip 在运行命令时找不到合适的软件包,请尝试运行 pip install --upgrade pip 以将其升级。升级完成后,再次尝试安装命令。

    • 在一些 Debian 和 Ubuntu 版本上,pip 可能会失败,并显示 DistutilsOptionError。如果出现此错误,请添加 --system 标志。

成功完成后,系统会用构建 Endpoints Frameworks 应用所需的文件填充 lib 目录。

生成 OpenAPI 文档

您可以使用 Endpoints Frameworks 库中的工具生成文档来描述示例代码的 REST API。

要生成 OpenAPI 文档,请执行以下操作:

  1. 确保您位于示例主目录中:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. 生成 OpenAPI 文档:

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

    [YOUR_PROJECT_ID] 替换为您的 Google Cloud 项目 ID。忽略显示的警告。Endpoints 工具在当前目录中生成名为 echov1openapi.json 的 OpenAPI 文档。Endpoints 工具将根据 @endpoints.api 修饰器中指定的服务名称和版本为文件命名。如需了解详情,请参阅创建 API

    Endpoints 会将 hostname 参数中指定的文本用作服务名称。该 YOUR_PROJECT_ID.appspot.com 名称格式与您将 API 部署到 App Engine 后端时由系统自动创建的 DNS 条目匹配。因此,在这种情况下,Endpoints 服务名称和完全限定的域名 (FQDN) 相同。

成功完成后,系统会显示以下消息:OpenAPI spec written to ./echov1openapi.json

部署 Endpoints 配置

要部署 Endpoints 配置,请使用 Service Infrastructure,这是 Google 的基础服务平台,供 Endpoints 和其他服务用来创建和管理 API 及服务。

要部署配置文件,请执行以下操作:

  1. 确保您位于示例主目录中:
    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. 通过运行以下命令,部署在上一部分生成的 OpenAPI 文档:
    gcloud endpoints services deploy echov1openapi.json

    这会创建一个新的 Endpoints 服务,其名称由您运行 Endpoints 工具以生成 OpenAPI 文档时在 hostname 参数中指定。无论 Endpoints 服务名称是什么,当您在 App Engine 上部署 API 时,系统都会使用名称格式 YOUR_PROJECT_ID.appspot.com 创建一条 DNS 记录,这是您向 API 发送请求时使用的 FQDN。

    在创建和配置服务时,Service Management 会向终端输出大量信息。您尽可忽略有关 echov1openapi.json 中的路径未要求 API 密钥的警告。部署完成后,您将看到如下所示的消息:

    Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
    

    在上面的示例中,2017-02-13-r2 是服务配置 ID,example-project-12345.appspot.com 是服务名称。

    如需了解详情,请参阅 gcloud 参考文档中的 gcloud endpoints services deploy

检查所需服务

要提供 API 管理功能,Endpoints Frameworks 需要以下服务:
名称 标题
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

在大多数情况下,gcloud endpoints services deploy 命令会启用这些必需的服务。但在以下情况下,gcloud 命令会成功完成,但不启用必需的服务:

  • 您使用了 Terraform 之类的第三方应用,但未添加这些服务。

  • 您将 Endpoints 配置部署到已明确停用这些服务的现有 Google Cloud 项目。

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

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 ENDPOINTS_SERVICE_NAME

要确定 ENDPOINTS_SERVICE_NAME,您可以执行以下任一操作:

  • 部署 Endpoints 配置后,前往 Cloud 控制台中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。

  • 对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的 host 字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的 name 字段中指定的值。

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

在本地运行示例

部署 Endpoints 配置后,您可以使用本地开发服务器在本地运行示例。

  1. 确保您位于示例主目录中:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. 启动本地开发服务器:

    dev_appserver.py ./app.yaml
    

    默认情况下,开发服务器会监听 http://localhost:8080, 如 dev_appserver.py 输出的 Google Cloud 控制台日志所示:

    INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
    
  3. 向本地开发服务器发送请求:

Linux 或 Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

在上面的 curl 中:

  • --data 选项用于指定要发布到 API 的数据。
  • --header 选项用于指定数据采用 JSON 格式。

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 要了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest

API 会回显您向其发送的消息,并以如下内容作为响应:

{
 "message": "hello world"
}

部署 API 后端

到目前为止,您已将 OpenAPI 文档部署到 Service Management,但尚未部署用于为 API 后端提供服务的代码。本部分逐步介绍如何将示例 API 部署到 App Engine。

要部署 API 后端,请执行以下操作:

  1. 运行以下命令以显示服务配置 ID:

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

    [YOUR_PROJECT_ID] 替换为您的项目 ID。例如:

    gcloud endpoints configs list --service=example-project-12345.appspot.com
    

  2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2016-08-01r0
  • env_variables 部分进行以下更改:
    • ENDPOINTS_SERVICE_NAME 字段中,将 YOUR-PROJECT-ID 替换为您的 Google Cloud 项目 ID。
    • ENDPOINTS_SERVICE_VERSION 字段中,将文本替换为服务配置 ID。例如:
      ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
    
  • 运行以下命令:
    gcloud app deploy
  • 按照屏幕上的提示操作。等待部署成功完成,忽略警告消息。部署完成后,系统将显示如下所示的消息:
    File upload done.
    Updating service [default]...done.
    

    如果收到错误消息,请参阅 App Engine 文档的问题排查部分了解相关信息。

    我们建议您等待几分钟,然后在 App Engine 完全初始化时向 API 发送请求。

  • 向示例 API 发送请求

    Linux 或 Mac OS

    使用 curl 发送 HTTP 请求。将 [YOUR_PROJECT_ID] 替换为您的 Google Cloud 项目 ID:

    curl \
        --request POST \
        --header "Content-Type: application/json" \
        --data '{"message":"hello world"}' \
        https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
    

    在上面的 curl 中:

    • --data 选项用于指定要发布到 API 的数据。
    • --header 选项用于指定数据采用 JSON 格式。

    PowerShell

    使用 Invoke-WebRequest 发送 HTTP 请求。将 [YOUR_PROJECT_ID] 替换为您的 Google Cloud 项目 ID:

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
        -Headers @{"content-type"="application/json"} -URI `
         "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
    

    在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest

    第三方应用

    您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:

    • 选择 POST 作为 HTTP 谓词。
    • 对于标头,请选择键 content-type 和值 application/json
    • 对于正文,请输入以下内容:
      {"message":"hello world"}
    • 输入示例应用的网址。例如:
      https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

    API 会回显您向其发送的消息,并以如下内容作为响应:

    {
     "message": "hello world"
    }
    

    如果未成功收到响应,请参阅排查响应错误

    跟踪 API 活动

    1. 在 Google Cloud 控制台中查看您的 API 的活动图表,网址为: 端点 >服务页面。

      转到“Endpoints 服务”页面

      请求可能需要一些时间才能体现在图表中。

    2. 在“日志浏览器”页面中查看 API 的请求日志。

      转到“日志浏览器”页面

    为 API 创建开发者门户

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

    清除数据

    为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。

    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.

    后续步骤