通过 API 同步自定义文档

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

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

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

创建授权服务帐号

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

控制台

  1. 在 Cloud Console 中,打开服务帐号页面。

    转到“服务帐号”页面

  2. 点击选择项目

  3. 选择您的项目,然后点击打开

  4. 点击 add 创建服务帐号

  5. 服务帐号名称字段中,输入服务帐号的显示名称。

  6. 选中提供新的私钥复选框。

  7. 对于密钥类型,使用默认类型 JSON

  8. 点击保存

  9. 此时会出现显示密钥信息的对话框。关闭此对话框,继续操作。

  10. 在 Cloud Console 中,转到项目的 Endpoints > 服务页面。

    Endpoints 服务

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

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

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

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

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

gcloud

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

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

    gcloud config set project [YOUR_PROJECT_ID]
        
  3. 确保 Cloud SDK (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 计算机上安装了 Cloud SDK,请打开一个终端窗口。
  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