Admin API 使用入门

区域 ID

REGION_ID 是 Google 根据您在创建应用时选择的区域分配的缩写代码。此代码不对应于国家/地区或省，尽管某些区域 ID 可能类似于常用国家/地区代码和省代码。对于 2020 年 2 月以后创建的应用，REGION_ID.r 包含在 App Engine 网址中。对于在此日期之前创建的现有应用，网址中的区域 ID 是可选的。

详细了解区域 ID。

本指南旨在帮助您了解如何使用 App Engine Admin API 将示例 Python 应用部署到 App Engine。您可以使用整个过程深入了解如何创建以编程方式管理和部署应用的代码。

在本指南中，使用的示例是一个会显示文本“Hello, World!”的简单 Hello World 应用，并且可以在 GitHub 中找到。使用 Google Cloud 控制台进行授权时，会用到 OAuth 客户端 ID 和网络浏览器。为了演示该过程的各个步骤，系统提供了 cURL 命令，以便您可以从终端发送 HTTP 请求。

目标

在 Google Cloud 控制台项目中启用 API 并创建 OAuth 客户端 ID 凭据。
获取用于通过 App Engine 进行身份验证的访问令牌。
使用 Admin API 将示例应用部署到 App Engine。
可选：配置您在其中部署了示例应用的版本的流量。

准备工作

您必须拥有或创建 Google 账号。
下载并安装 Google Cloud CLI，然后初始化 gcloud CLI：
下载 SDK

配置 Google Cloud 项目

在 Google Cloud 项目中启用 App Engine Admin API 和 Cloud Storage API，然后配置凭据：

在 Google Cloud 控制台中启用 API：

启用 API
在向导中，从列表中选择现有项目，或点击继续以创建新项目。
点击继续以创建 OAuth 客户端 ID 凭据：
1. 在 OAuth 同意屏幕中，至少指定您的电子邮件地址和向用户显示的产品名称。
2. 点击保存以保存同意屏幕设置，然后切换到凭据标签页。
3. 点击创建凭据，然后点击 OAuth 客户端 ID 以创建客户端 ID。
4. 点击 Web 应用，指定名称，然后使用 https://www.google.com 作为重定向 URI。
  
  注意：重定向 URI 定义 HTTP 响应的发送位置。本指南使用 https://www.google.com URI 作为示例，但对于生产环境，您必须指定应用的身份验证端点，该端点处理来自 OAuth 2.0 服务器的响应。
5. 点击创建以保存凭据。
6. 记下显示的客户端 ID，因为该 ID 将在后面的步骤中用于请求访问令牌。

如需详细了解如何为 Admin API 创建凭据，请参阅访问 API。

创建配置文件

创建用于定义 Hello World 应用部署的配置文件。在名为 app.json 的文件中，在 sourceUrl 字段中定义 Hello World 应用的 Cloud Storage 存储分区，并定义该版本的配置信息，包括 id 字段中的版本 ID。

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

例如 root/python-docs-samples/appengine/standard/hello_world/app.json。

向 HTTP 请求授权

您可以通过 App Engine 进行身份验证，以便使用 Admin API 发送 HTTP 请求。

使用以下任一方式来帮助您快速开始。HTTPS 和 gcloud 方式都提供手动但简单的步骤来获取试用 Admin API 所需的访问令牌。

HTTPS

要模拟客户端 OAuth 2.0 流，请将您的 OAuth 客户端 ID 凭据添加到 URI，然后通过网络浏览器发送 HTTPS 请求：

在您的网络浏览器中，使用 API 凭据的客户端 ID 来请求访问令牌。以下示例使用 client_id=[MY_CLIENT_ID] 和 redirect_uri=https://www.google.com，其中 [MY_CLIENT_ID] 是您之前创建的凭据的客户端 ID：
```
https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
```
从请求响应中检索访问令牌。

网络浏览器中的地址字段应该包含您在凭据中指定的重定向 URI 以及附加到 URI 的访问令牌，例如：
```
https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
```
现在，您可以使用 access_token 字段中提供的访问令牌 [MY_ACCESS_TOKEN] 将 HTTP 请求发送到您的 Google Cloud 项目。

gcloud

如需仅检索访问令牌，请运行以下 gcloud 命令：

设置要用于请求访问令牌的应用默认凭据 (ADC)：
```
gcloud auth application-default login
```

请求访问令牌：

gcloud auth application-default print-access-token

如需详细了解这些命令，请参阅 gcloud auth application-default。

请注意：您的访问令牌大约在颁发 60 分钟后到期。

上述方式不适合在以编程方式实现时使用。如需了解如何实现 OAuth 2.0 授权流程，请参阅访问 Admin API。

部署 Hello World 应用

您可以使用 HTTP 请求以通过 Admin API 部署 Hello World 应用：

使用 Admin API 发送 HTTP POST 请求，将某个版本的 Hello World 应用部署到您的 App Engine 应用，例如：

POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json

示例 cURL 命令：

从您创建 app.json 配置文件的目录运行以下命令，例如：

cd root/python-docs-samples/appengine/standard/hello_world/

curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions

其中：

[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

示例响应：

{
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  }
}

其中 [MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。

验证该版本的 Hello World 应用是否成功部署到 App Engine 应用：

在 HTTP GET 方法中，将上一步中返回的 name 字段用作操作名称，以查看实际部署操作的状态，例如：

GET https://appengine.googleapis.com/v1/[OPERATION_NAME]

示例 cURL 命令：

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]

其中：

[OPERATION_NAME] 是上一步中部署应用时返回的 name 字段的值，例如 apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85。
[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

示例响应：

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "endTime": "2016-07-29T17:13:20.424Z",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  },
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "response": {
    "@type": "type.googleapis.com/google.appengine.v1.Version",
    "creationTime": "2016-07-29T17:12:46.000Z",
    "deployer": "me@example.com",
    "id": "appengine-helloworld",
    "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "runtime": "python27",
    "servingStatus": "SERVING",
    "threadsafe": true,
  }
}

其中 [MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。

使用 HTTP GET 请求查看版本详细信息，以验证已在 App Engine 应用中创建了该版本的 Hello World 应用，例如：

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

示例 cURL 命令：

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

其中：

[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

示例响应：

{
  "creationTime": "2016-07-29T17:12:46.000Z",
  "deployer": "me@example.com",
  "deployment": {
    "files": {
      "main.py": {
        "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      }
    }
  },
  "handlers": [
    {
      "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
      "login": "LOGIN_OPTIONAL",
      "script": {
        "scriptPath": "main.app",
      },
      "securityLevel": "SECURE_OPTIONAL",
      "urlRegex": "/.*"
    }
  ]
  "id": "appengine-helloworld",
  "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
  "runtime": "python27",
  "servingStatus": "SERVING",
  "threadsafe": true,
  "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
}

其中 [MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。

访问上一步的 HTTP 响应的 versionUrl 字段中指定的网址，以在网络浏览器中查看 Hello World 应用，例如：
```
https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
```
其中，[MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。
REGION_ID 是 Google 根据您在创建应用时选择的区域分配的缩写代码。此代码不对应于国家/地区或省，尽管某些区域 ID 可能类似于常用国家/地区代码和省代码。对于 2020 年 2 月以后创建的应用，REGION_ID.r 包含在 App Engine 网址中。对于在此日期之前创建的现有应用，网址中的区域 ID 是可选的。

配置 Hello World 应用的流量。

默认情况下，您部署到新 App Engine 应用的初始版本会自动接收 100% 的流量，而任何后续版本将不会接收任何流量。

如需查看您的版本是否配置为接收流量，请发送 HTTP GET 请求，例如：

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

示例 cURL 命令：

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

其中：

[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

示例响应：

{
  "name": "apps/[MY_PROJECT_ID]/services/default/",
  "id": "default",
  "split": {
    "allocations": {
      "appengine-helloworld": 1
    }
  }
}

其中 [MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。

如需将所有流量都迁移到某个版本，请发送 HTTP PATCH 请求，例如：

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }

示例 cURL 命令：

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

其中：

[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

示例响应：

{
  "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

其中 [MY_PROJECT_ID] 是您的 Google Cloud 项目 ID。

扩展学习

如果您具有某个应用的多个版本，则可以执行下列步骤，以在这些版本之间拆分流量：

要将第二版 Hello World 应用部署到同一 App Engine 应用，请执行以下操作：
1. 在您之前创建的 Hello World 应用的现有 app.json 配置文件中，更新 id 字段以指定另一个版本。例如，附加 -2：
```
"id": "appengine-helloworld-2"
```
2. 再次执行所有相同步骤以部署 appengine-helloworld-2 版本，例如：
  1. 通过您的项目进行身份验证。
  2. 部署新的 appengine-helloworld-2 版本。
  3. 验证 appengine-helloworld-2 版本已成功部署。
  4. 在网络浏览器中查看正在运行的应用。

按照迁移和拆分流量中的说明拆分流量，例如发送 HTTP PATCH 请求：

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }

示例 cURL 命令：

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

其中：

[MY_ACCESS_TOKEN] 是您为了向 HTTP 请求授权而获取的访问令牌。
[MY_PROJECT_ID] 是要在其中部署版本的项目的 ID。

后续步骤

为应用创建、配置和设置凭据：访问 API