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

获取示例代码

要从 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。

检查所需服务

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

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

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

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

gcloud services list

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

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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. 向本地开发服务器发送请求：

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

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

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