通过 API 同步自定义文档

OpenAPI | gRPC

您的门户提供了一个用于同步自定义内容的特殊 API。要调用此 API，您必须执行以下操作：

至少手动同步您的自定义内容一次。
创建一个具备适当授权和密钥的服务帐号。
发出同步内容的 HTTP 请求。

本文档提供了创建服务帐号的说明，并提供了通过 Python 或命令行发出请求的示例。

创建授权服务帐号

要使用 API 同步您的自定义内容，您需要一个具备适当授权和密钥的服务帐号。要创建服务帐号、向该帐号授予适当角色并获取所需的密钥文件，请按照以下说明操作：

控制台

创建服务帐号：
1. 在 Google Cloud 控制台中，转到服务帐号页面。
  
  转到“服务帐号”
2. 选择 API 所使用的项目。
3. 点击 创建服务帐号。
4. 在服务帐号名称字段中，输入一个名称。Google Cloud 控制台会根据此名称填充服务帐号 ID 字段。
5. 可选：在服务帐号说明字段中，输入服务帐号的说明。
6. 点击创建并继续。
7. 点击完成以完成服务帐号的创建。
  
  不要关闭浏览器窗口。您将在下一步骤中用到它。
下载刚刚创建的服务帐号的 JSON 密钥：
1. 在 Google Cloud 控制台中，点击您创建的服务帐号的电子邮件地址。
2. 点击密钥。
3. 依次点击添加密钥和创建新密钥。
4. 点击创建。JSON 密钥文件将下载到您的计算机上。
  
  务必要安全存储密钥文件，因为它能够以服务帐号的身份进行身份验证。您可以根据需要移动并重命名此文件。
5. 点击关闭。
在 Google Cloud Console 中，转到项目的 Endpoint > Services 页面。

Endpoints 服务
点击您需要用于同步自定义内容的 API 的名称，以更改其访问权限。
如果“权限”侧边面板未打开，请点击 +权限。
要向已创建的服务帐号授予对 API 的访问权限，请在添加成员字段中输入已创建服务帐号的电子邮件地址。
在选择角色下拉列表中，点击 Service Management，然后为服务帐号选择服务配置编辑者角色。

恭喜！您已创建了服务帐号，将其私钥下载到了 JSON 文件，并向服务帐号分配了适当的角色。

gcloud

输入以下命令，以显示 Google Cloud 项目的 ID：
```
gcloud projects list
```
替换以下命令中的 [YOUR_PROJECT_ID]，以将默认项目设置为您的 API 所属的项目：
```
gcloud config set project [YOUR_PROJECT_ID]
```
重要提示：您必须在 API 所属的项目中创建服务帐号。
确保 Google Cloud CLI (gcloud) 有权访问您在 Google Cloud 上的数据和服务：
```
gcloud auth login
```
如果您有多个帐号，请务必选择 API 所属的 Google Cloud 项目中的帐号。如果运行 gcloud auth list，则您选择的帐号将显示为项目的活跃帐号。
如需创建服务帐号，请运行以下命令，并将 [SERVICE_ACCOUNT_NAME] 和 [Service Account to Sync Custom Content] 分别替换为您要使用的名称和显示名：
```
gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
  --display-name "[Service Account to Sync Custom Content]"
```
该命令将采用以下格式指定服务帐号的电子邮件地址：
```
[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
```
后续命令会用到此电子邮件地址。

创建服务帐号密钥文件，将 [KEY_FILE] 替换为您的密钥的文件名：

gcloud iam service-accounts keys create ~/[KEY_FILE] \
  --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com

要向服务帐号授予对包含自定义内容的 API 的访问权限，请调用以下命令，并将 [YOUR_SERVICE_NAME] 替换为包含自定义内容的 API 的名称：

gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
      --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
      --role roles/servicemanagement.configEditor

发出同步自定义内容的请求

以下示例演示了如何发出同步自定义内容的请求。请求应如下所示：

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

将 [YOUR_PROJECT_ID] 和 [YOUR_SERVICE_NAME] 替换为适当的值。请求成功完成后，响应的 HTTP 状态代码为 200。

接下来的示例演示了如何使用 Python 或命令行从 Google 的授权服务器获取访问令牌，并使用此令牌向门户的端点发出请求：

Python

安装所需的 Python 库：
```
    pip install --upgrade google-auth
```

如需根据服务帐号的凭据和端点所需的范围创建 Credentials 对象并发出同步内容的请求，请将 [YOUR_PROJECT_ID]、/path/to/service.json 和 [YOUR_SERVICE_NAME] 替换为以下脚本中的相应值：

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
SERVICE_ACCOUNT_FILE = "/path/to/service.json"
PROJECT_ID = "[YOUR_PROJECT_ID]"
SERVICE_NAME = "[YOUR_SERVICE_NAME]"

credentials = service_account.Credentials.from_service_account_file(
   SERVICE_ACCOUNT_FILE, scopes=SCOPES)
authed_session = AuthorizedSession(credentials)
endpoint =
"https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
result = authed_session.post(endpoint)
print result

命令行

打开 Cloud Shell；如果 Linux 计算机上安装了 gcloud CLI，则打开终端窗口。
如需向您的服务帐号进行身份验证，请将下面的 [KEY_FILE] 替换为指向服务帐号密钥文件的路径，然后运行以下命令：
```
gcloud auth activate-service-account --key-file [KEY_FILE]
```

使用您的服务帐号获取授权令牌：

ACCESS_TOKEN=$(gcloud auth print-access-token)

调用 API 时，将该令牌值作为 authorization 标头中的不记名令牌传递。将 [YOUR_PROJECT_ID] 和 [YOUR_SERVICE_NAME] 替换为相应的值：
```
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content
```