Cloud Support API 用户指南

本页面介绍如何开始使用 cloudsupport.googleapis.com API 版本 1。此 API 的版本 2 目前作为正式发布前的版本提供。如需了解详情,请参阅发布阶段说明

过程概览

本部分详细介绍开始使用 API 的简要过程。

  1. 客户服务团队会为客户创建一个支持帐号。这是其他所有操作的前提条件。
  2. 客户向客户服务团队指明要用于访问此 API 的项目 ID。此项目将成为 API 的指定使用方项目

    此项目将是启用 API 的资源,但您可以从任何 Google Cloud 项目中使用调用 API 的凭据。

  3. 客户为使用方项目生成 API 密钥。客户将使用此 API 密钥调用 API。如需生成 API 密钥,请参阅使用 API 密钥

  4. 客户服务团队允许通过应用正确的公开范围标签将客户团队 API 访问权限列入许可名单。

  5. 客户服务团队会将客户服务帐号列入许可名单,便于访问服务帐号。

  6. 客户通过访问 Google Cloud Console 中的 Cloud Support API 页面并点击 ENABLE 来启用 Cloud Support API。

    转到 Cloud Support API 页面

如果您需要服务帐号集成,请执行以下操作:

  1. 客户使用了解服务帐号中的说明预配一个或多个服务帐号。

  2. 客户可在 Cloud Console 的“IAM”标签页下向服务帐号授予 Organization Viewer 角色,也可以为服务帐号授予 resourcemanager.organizations.get 权限的任何其他角色。

    也可以通过编程方式完成此操作:

      gcloud organizations add-iam-policy-binding
      organizations/ord-id
      --role roles/resourcemanager.organizationViewer
      --member service-account
     

  3. 该客户通过 Cloud Console 中的支持设置页面添加一个或多个服务帐号作为支持用户。

  4. 客户通过共享凭据允许其 JIRA 连接器或其他应用访问服务帐号。如需了解相关步骤,请参阅身份验证概览

  5. 如果客户已有凭据管理工具,则可以针对 Google Cloud 服务帐号使用同一工具。

  6. 客户的应用使用服务帐号凭据(而不是最终用户凭据)进行常规 API 调用,如同最终用户那样。

如果您需要 OAuth 2.0 身份验证,请执行以下操作:

  1. 如果您尚未使用 OAuth2 向 Google 进行身份验证,请按照
    使用 OAuth 2.0 访问 Google API 指南对其进行设置。请特别注意增量授权部分。
  2. 确保将以下两个范围添加到应用使用的 OAuth2 客户端 ID:
    • 如需常规访问 Google Cloud:https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/cloud-platform.read-only
    • 如需检索或创建支持服务工单和其他支持相关数据的访问权限:https://www.googleapis.com/auth/cloudsupport

提取 API 定义

API 定义以 Google Cloud 发现文档的形式提供。

示例如下。将 <API_KEY> 替换为您在上一步中从使用方项目生成的 API 密钥。

curl 'https://cloudsupport.googleapis.com/$discovery/rest?key=<API_KEY>&labels=TRUSTED_TESTER&version=v1alpha2' > /tmp/cloudsupport.v1alpha2.json

REST 客户端

REST API

对于下列所有端点,<host> 的值应替换为 cloudsupport.googleapis.com

支持帐号

列出用户有权访问的支持帐号并管理支持帐号详细信息。

所需的角色
类型 角色
IAM Support Account Viewer(组织)
IAM Organization Viewer(组织)
支持 开发、生产或业务关键型

ListSupportAccounts

列出当前已通过身份验证的用户有权访问的所有支持帐号。

REST 格式
GET <host>/v1/supportAccounts
参数
名称 类型 说明
filter string

要应用于搜索结果的自由格式过滤器。用法示例:

filter="name=gcp-sa-1234"

filter="cloud_resource=organizations/my-org-1234"

page_size int64 要在响应中返回的支持帐号数量上限。对于大多数用户来说,此值的相关性不高,因为支持帐号数量非常小。
page_token string 标识要返回的结果页面的令牌。如果未指定,则返回第一页的结果。
示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  http://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234?filter=cloud_resource:organizations/8675309

GetSupportAccount

检索指定的支持帐号。

REST 格式
GET <host>/v1/{name=supportAccounts/*}
参数

请求网址中指定的支持帐号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234

用户管理

管理员用于以编程方式从支持角色中添加或移除用户。

所需的角色
类型 角色
IAM Support Account Viewer(组织)
IAM Organization Viewer(组织)
Support 开发、生产或业务关键型

GetUserRole

检索给定用户的 SupportRole。要检索的用户是根据请求消息中的 email 字段确定的,或者在未指定前者时根据经过身份验证的用户的凭据确定。

REST 格式
GET <host>/v1/{name=supportAccounts/*}:getUserRole
参数
名称 类型 说明
email string 要获取角色的用户的电子邮件地址。
示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:getUserRole?email=john@example.com

GetSupportRoles

检索与指定支持帐号关联的所有 SupporRole 的列表。

REST 格式
GET <host>/v1/{name=supportAccounts/*}:getRoles
参数

网址中指定的支持帐号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:getRoles

SetSupportRoles

更新与给定 SupportAccount 关联的 SupportRole 列表。

REST 格式
POST <host>/v1/{name=supportAccounts/*}:setRoles
参数
名称 类型 说明
roles SupportRole[] 与 SupportAccount 相关联的角色的完整列表。
示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{
  "roles": [
    {
      "email": "john@example.com",
      "role": "SITE_RELIABILITY",
    },
    {
      "email": "alex@example.com",
      "role": "OPERATION",
    },
    {
      "email": "tiger@example.com",
      "role": "ROLE_UNSPECIFIED",
    },
],
  "etag": "ZrTGhhB"
}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:setRoles

其中 role 属性可以采用以下值:

角色类型 说明
ROLE_UNSPECIFIED 删除此用户的支持角色。
BASIC “基本”支持角色。
DEVELOPER “开发”支持角色。
OPERATION “生产”支持角色。
SITE_RELIABILITY “业务关键型”支持角色。

SetSupportRoles 方法将返回 google.longrunning.Operation 的实例。如需检索 SetSupportRoles 的状态,您需要使用操作 ID 轮询 GetOperation 端点。操作 ID 将组合使用字母数字字符,格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

案例

检索、创建和更新邮件支持记录。

所需的角色
类型 角色
IAM Support Account Viewer(组织)
IAM Organization Viewer(组织)
Support Role 开发、生产或业务关键型

ListCases

检索与 SupportAccount 关联的邮件支持记录列表。

REST 格式
GET <host>/v1/{parent=supportAccounts/*}/cases
参数
名称 类型 说明
filter string 目前仅接受 "OPEN""CLOSED" 值。
page_size int64 每个请求可提取的案例数上限。
page_token string 标识要返回的结果页面的令牌。如果未指定,则返回第一页的结果。
示例
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases

GetCase

检索指定的邮件支持记录。

REST 格式
GET <host>/v1/{name=supportAccounts/*/cases/*}
参数

请求网址中指定的支持帐号和案例编号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678

CreateCase

创建一个案例并将其与给定的 SupportAccount 进行关联。

REST 格式
POST <host>/v1/{parent=supportAccounts/*}/cases
参数
名称 类型 说明
case Case

案例对象。

示例:


     { \
        display_name: "My test case for Istio", \
        description: "Istio network latency spike", \
        category: "Compute", \
        component: "Istio", \
        subcomponent: "Networking", \
        time_zone: "-07:00", \
        cc_addresses: ["foo@domain.com", "bar@domain.com"], \
        project_id: "my-gcp-test-project-1234", \
        priority: 3 \
      }
      

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ display_name: "My app is down", description: "Datastore appears to be down so my app is broken.", component: "Cloud Datastore", subcomponent: "Availability / Latency", time_zone: "-07:00", project_id: "my-super-project", category: "Storage & Databases", priority: 3 }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases

UpdateCase

更新邮件支持记录。目前只能更新优先级、主题和 cc_address 字段。

REST 格式
PATCH <host>/v1/{case.name=supportAccounts/*/cases/*}
参数
名称 类型 说明
case Case 已更新的邮件支持记录。
update_mask String[]

要更新的案例字段列表。

示例:

["case.priority"]

示例:更新案例
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ display_name: "My app is down", priority: 2, cc_addresses: ["james@example.com", "susan@example.com"]}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.cc_addresses,case.priority,case.display_name
示例:关闭案例
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ state: "CLOSED" }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.state

EscalateCase

上报邮件支持记录。上报邮件支持记录将启动客户服务上报管理流程。只有业务关键型生产角色的用户才能自动上报邮件支持记录。

REST 格式
POST <host>/v1/{name=supportAccounts/*/cases/*}:escalate
参数
名称 类型 说明
reason Enum

上报案例的原因。

有效值:

  • REASON_UNSPECIFIED:上报原因处于未知状态或未指定。
  • RESOLUTION_TIME:案例的解决时间太长。
  • TECHNICAL_EXPERTISE:支持人员不具有成功解决问题所需的专业知识认证。
  • BUSINESS_IMPACT:问题具有重大业务影响。
justification String 有关 reason 字段的自由文本说明,并提供关于案例上报原因的更多详细信息。
示例
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ reason: "TECHNICAL_EXPERTISE", justification: "There is no technical expertise."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:escalate

GetIssueTaxonomy

检索创建邮件支持记录时使用的问题类别和产品组件的分类。

REST 格式
GET <host>/v1:getIssueTaxonomy
参数
名称 类型 说明
product_type string 应始终设置为 "CLOUD_PLATFORM".
示例
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1:getIssueTaxonomy

附件

检索、创建或下载附加到邮件支持记录的文件。将文件附加到邮件支持记录的过程包含三个步骤:

  1. POST 附加到 :startAttachment 端点,以生成新的附件名称。
  2. POST 附加到 Bytestream.Write 端点,以上传附件的原始字节。
  3. POST 附加到 /attachments,以完全创建附件并将其与邮件支持记录关联。创建附件包括所有文件元数据,例如 MIME 类型(例如 image/jpeg)、大小(以字节为单位)和文件名 (r2_d2.jpg)。
所需的角色
类型 角色
IAM Cloud Support Account Viewer(组织)
IAM Organization Viewer(组织)
支持 开发、生产或业务关键型。

ListAttachments

检索与给定邮件支持记录关联的所有附件的元数据。

REST 格式
GET <host>/v1/{parent=supportAccounts/*/cases/*}/attachments
参数

请求网址中的支持帐号和案例编号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/attachments
Bytestream.Read

您可以使用 Bytestream.Read 端点发出以下 REST API 调用,以下载附件的原始字节,具体如下:

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X GET https://cloudsupport.googleapis.com/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?alt=media

StartAttachment

启动创建新附件的流程。该方法会返回一个字符串,表示附件的资源名称。后续 ByteStream.WriteCreateAttachment 端点调用中将使用该资源名称。

REST 格式
POST <host>/v1/{parent=supportAccounts/*/cases/*}:startAttachment
参数

请求网址中的支持帐号和案例编号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d {} https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:startAttachment
Bytestream.Write

您可以通过调用 Bytestream.Write 来上传原始附件字节,具体如下:

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X POST -T {"r2-d2.jpg"} https://cloudsupport.googleapis.com/upload/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?upload_type=media

CreateAttachment

创建附件元数据并将附件与指定的邮件支持记录相关联。附件名称必须先通过调用 :startAttachment 生成,并且附件大小上限为 32MB。

REST 请求
POST <host>/v1/{name=supportAccounts/*/cases/*}/attachments
参数
名称 类型 说明
attachment Attachment

附件对象。

示例:


{
  name: "supportAccounts/gcp-sa-1234/cases/998877/attachments/55115511", \
  file_name: "giraffe.jpg", \
  mime_type: "image/jpeg", \
  size: 986712, // in bytes \
}
示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name: "supportAccounts/gcp-sa-1234/cases/5678/attachments/9012", mime_type: "image/jpeg", file_name: "R2-D2.jpg", size: 4458 }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/attachments

注释

创建或列出有关邮件支持记录的评论。

所需的角色
类型 角色
IAM Cloud Support Account Viewer(组织)
IAM Organization Viewer(组织)
支持 开发、生产或业务关键型

ListComments

列出与指定邮件支持记录关联的所有评论。

REST
GET <host>/v1/{name=supportAccounts/*/cases/*}/comments
参数

请求网址中的支持帐号和案例编号。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/comments

CreateComment

向案例添加新评论。

REST 格式
POST <host>/v1/{name=supportAccounts/*/cases/*}/comments
参数
名称 类型 说明
comment 备注

评论对象。

示例:


{
text: "This is my comment", \
}
           

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name:"supportAccounts/gcp-sa-1234/cases/5678",text:"I am commenting on this case."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/comments

通知

列出客户服务发出的任何通知。

所需的角色
类型 角色
IAM Cloud Support Account Viewer(组织)
IAM Organization Viewer(组织)
支持 开发、生产或业务关键型

ListNotifications

列出已知会对客户产生积极影响的所有未结 Google Cloud 突发事件。响应将涵盖影响所有产品的问题,而不是特定于调用端点的用户的问题。

REST 格式
GET <host>/v1/{parent=supportAccounts/*}/notifications
参数
名称 类型 说明
page_size int32 要在响应中返回的通知数量上限。
page_token string 用于检索下一页结果的令牌。ListNotifications 端点目前不支持分页。
示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/notifications

IAM

与 Identity and Access Management 服务互动的端点。

TestIamPermissions

验证当前通过身份验证的用户是否具有给定客户服务资源的权限。仅支持帐号、案例、操作和评论才会被视为有效的客户服务资源。

例如,如需检查用户是否有权提取支持帐号的详细信息,应使用以下内容填充 TestIamPermissionsRequest

resource: "supportAccounts/{support_account_id}"
permission: "cloudsupport.accounts.get"
REST 格式
POST <host>/v1/{resource=**}:testIamPermissions
参数
名称 类型 说明
permissions string[]

要测试的权限列表。

示例:

`["cloudsupport.comments.list", "cloudsupport.cases.list"]`

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d '{permissions: "cloudsupport.accounts.get"}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:testIamPermissions

运维

用于检索长时间运行的操作的状态的端点。

GetOperation

检索现有操作的状态。

REST 格式
GET <host>/v1/operations/{name=supportAccounts/*/operations/*}
参数

请求网址中指定的支持帐号和操作标识符。

示例
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/operations/supportAccounts/gcp-sa-1234/operations/5678-0912

生成客户端库

克隆 Google API 客户端生成器

cd /tmp/; git clone https://github.com/google/apis-client-generator.git;

确保已安装 Python 2.7:

sudo apt-get install python

确保已安装 PIP:

sudo apt-get install python-pip

安装依赖项:

pip install google-apis-client-generator

生成客户端库。

该命令将生成以 WARNING:root:object without properties 开头的一两条警告。您可以忽略它们。系统仍会生成客户端库。

./generate.sh --input=/tmp/cloudsupport.v1alpha2.json --output_dir=/tmp/cloudsupport_generated --language=java

使用 API

准备工作

  • API 客户端库 Java 中添加依赖项
  • 添加在上一步生成的代码的依赖项
  • 确保成功构建代码

    // Shared constants
    String CLOUD_SUPPORT_SCOPE = "https://www.googleapis.com/auth/cloudsupport";
    
    // Customer specific config
    String SERVICE_ACCOUNT_ID = "<... service account id ...>";
    File SERVICE_ACCOUNT_PRIVATE_KEY = new File("<... p12 key file ...>");
    String SUPPORT_ACCOUNT_ID = "supportAccounts/gcp-sa-<......>";
    
    // Service setup
    JsonFactory jsonFactory = JacksonFactory.getDefaultInstance();
    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
    
    // This section is for service account authentication
    // If you are using OAuth2 instead, follow guide at
    // https://developers.google.com/api-client-library/java/google-oauth-java-client/oauth2
    GoogleCredential credential = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(SERVICE_ACCOUNT_ID)
      .setServiceAccountPrivateKeyFromP12File(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setServiceAccountScopes(Collections.singleton(CLOUD_SUPPORT_SCOPE))
      .build();
    
    // Main API service is ready to use!
    CloudSupport supportService = new CloudSupport.Builder(httpTransport, jsonFactory, credential).build();
    
    // Each call will look something like this:
    SupportAccount account = supportService.supportAccounts().get(SUPPORT_ACCOUNT_ID).execute();