通过 API 同步自定义文档

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

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

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

创建授权服务帐号

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

控制台

  1. 创建服务帐号:

    1. 在 Google Cloud 控制台中,转到服务帐号页面。

      转到“服务帐号”

    2. 选择 API 所使用的项目。

    3. 点击 创建服务帐号

    4. 服务帐号名称字段中,输入一个名称。Google Cloud 控制台会根据此名称填充服务帐号 ID 字段。

    5. 可选:在服务帐号说明字段中,输入服务帐号的说明。

    6. 点击创建并继续

    7. 点击完成以完成服务帐号的创建。

      不要关闭浏览器窗口。您将在下一步骤中用到它。

  2. 下载刚刚创建的服务帐号的 JSON 密钥:

    1. 在 Google Cloud 控制台中,点击您创建的服务帐号的电子邮件地址。
    2. 点击密钥
    3. 依次点击添加密钥创建新密钥
    4. 点击创建。JSON 密钥文件将下载到您的计算机上。

      务必要安全存储密钥文件,因为它能够以服务帐号的身份进行身份验证。您可以根据需要移动并重命名此文件。

    5. 点击关闭

  3. 在 Google Cloud Console 中,转到项目的 Endpoint > Services 页面。

    Endpoints 服务

  4. 点击您需要用于同步自定义内容的 API 的名称,以更改其访问权限。

  5. 如果“权限”侧边面板未打开,请点击 +权限

  6. 要向已创建的服务帐号授予对 API 的访问权限,请在添加成员字段中输入已创建服务帐号的电子邮件地址。

  7. 选择角色下拉列表中,点击 Service Management,然后为服务帐号选择服务配置编辑者角色。

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

gcloud

  1. 输入以下命令,以显示 Google Cloud 项目的 ID:

    gcloud projects list
    
  2. 替换以下命令中的 [YOUR_PROJECT_ID],以将默认项目设置为您的 API 所属的项目:

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. 确保 Google Cloud CLI (gcloud) 有权访问您在 Google Cloud 上的数据和服务:

    gcloud auth login
    

    如果您有多个帐号,请务必选择 API 所属的 Google Cloud 项目中的帐号。如果运行 gcloud auth list,则您选择的帐号将显示为项目的活跃帐号。

  4. 如需创建服务帐号,请运行以下命令,并将 [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
    

    后续命令会用到此电子邮件地址。

  5. 创建服务帐号密钥文件,将 [KEY_FILE] 替换为您的密钥的文件名:

    gcloud iam service-accounts keys create ~/[KEY_FILE] \
      --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
    
  6. 要向服务帐号授予对包含自定义内容的 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

  1. 安装所需的 Python 库:
        pip install --upgrade google-auth
  2. 如需根据服务帐号的凭据和端点所需的范围创建 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

命令行

  1. 打开 Cloud Shell;如果 Linux 计算机上安装了 gcloud CLI,则打开终端窗口。
  2. 如需向您的服务帐号进行身份验证,请将下面的 [KEY_FILE] 替换为指向服务帐号密钥文件的路径,然后运行以下命令:
    gcloud auth activate-service-account --key-file [KEY_FILE]
  3. 使用您的服务帐号获取授权令牌:
    ACCESS_TOKEN=$(gcloud auth print-access-token)
  4. 调用 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