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 控制台中的 Cloud Support API 页面并点击启用来启用 Cloud Support API。

    转到 Cloud Support API 页面

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

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

  2. 客户在 Google Cloud 控制台中的“IAM”标签页下向服务帐号授予 Organization Viewer 角色，在授予 resourcemanager.organizations.get 权限的其他任何角色下。

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

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

  3. 客户通过 Google Cloud 控制台中的支持 > 设置页面将一个或多个服务帐号添加为支持用户。

  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-platform 或 https://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 API

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

案例

检索和创建支持请求。

必需的角色
类型 角色
IAM Support Account Viewer（组织）
IAM Organization Viewer（组织）

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

生成客户端库

克隆 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();