Cloud Support API V2 用户指南

概览

本页面介绍了如何开始使用 cloudsupport.googleapis.com API 的版本 2,尤其是 v2beta 端点。

您可以集成 Cloud Support API 以使用 Cloud Customer Care 与贵组织的客户关系管理 (CRM) 系统。借助 Cloud Support API,用户可以直接在 CRM 中完成各种支持任务,包括:

  • 创建和管理支持案例。
  • 列出、创建和下载案例的附件。
  • 列出和创建案例注释。

以下各部分介绍了入门步骤,并探讨了与 Support API 相关的各种元素的关键概念。

开始使用

本部分详细介绍了 Cloud Support API 使用入门。

  1. 访问 Google Cloud Console 中的 Cloud Support API 页面并点击启用,以启用 Cloud Support API。

    转到 Cloud Support API 页面

  2. 按照了解服务帐号中的说明预配一个或多个服务帐号。

    如果您已经拥有凭据管理工具,那么可以对 Google Cloud 服务帐号使用相同的工具。

  3. 在控制台中的 IAM 标签页下向服务帐号授予 Organization Viewer 角色,或授予 resourcemanager.organizations.get 权限的任何其他角色。

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

      gcloud organizations add-iam-policy-binding \
      organizations/ORG_ID \
      --role roles/resourcemanager.organizationViewer \
      --member SERVICE_ACCOUNT

  1. 向服务帐号授予 Tech Support Editor 或 Tech Support Viewer 角色。您可以通过编程方式完成此操作:

      gcloud organizations add-iam-policy-binding \
      organizations/ORG_ID \
      --role roles/cloudsupport.techSupportEditor \
      --member SERVICE_ACCOUNT

  2. 如果使用 JIRA 等第三方集成,请通过共享凭据向第三方应用授予对服务帐号的访问权限。如需了解相关步骤,请参阅身份验证概览

  3. 客户的应用使用服务帐号凭据(而不是最终用户凭据)进行常规 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

访问权限控制和 IAM 角色

高级支持服务使用以下 IAM 角色来控制对案例的访问权限。如需了解详情,请参阅有关访问权限控制的文档。

角色 权限
Tech Support Viewer cloudsupport.techCases.get
cloudsupport.techCases.list
cloudsupport.techCaseAttachments.list
cloudsupport.techCaseAttachments.download
cloudsupport.techCaseComments.list
cloudsupport.techCaseUpdates.list
Tech Support Editor 技术支持查看者权限
cloudsupport.techCases.create
cloudsupport.techCases.update
cloudsupport.techCases.escalate
cloudsupport.techCases.close
cloudsupport.techCaseAttachments.create
cloudsupport.techCaseComments.create

在本地生成客户端库

API 定义以 Google Cloud 发现文档的形式提供。如需了解详情,请参阅 Google API Discovery Service

  1. 使用以下命令生成定义文件。
curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2beta' > /tmp/cloudsupport.v2beta.json
  1. 接下来,克隆 Google API 客户端生成器
cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
  1. 确保您已安装 Python:
sudo apt-get install python
  1. 确保已安装画中画:
sudo apt-get install python-pip
  1. 安装依赖项:
pip install google-apis-client-generator
  1. 生成客户端库。

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

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

通过客户端库使用 Cloud Support API (Python)

在此示例中,用户只需几行代码即可使用 Python 版客户端库。这样可以轻松集成到 App Engine 或 Compute Engine 等各种 GCP 产品中。

使用此方法时,API 将尝试对代码运行的环境使用默认凭据(因此,请确保正在使用的服务帐号具有“使用入门”部分提到的相应权限)。

import googleapiclient.discovery

SERVICE_NAME = "cloudsupport"
API_VERSION = "v2beta"
API_DEFINITION_URL = "https://cloudsupport.googleapis.com/$discovery/rest?version=" + API_VERSION
PARENT = "organizations/" + ORGANIZATION_ID

supportApiService = googleapiclient.discovery.build(
    serviceName=SERVICE_NAME,
    version=API_VERSION,
    discoveryServiceUrl=API_DEFINITION_URL)

case_list = supportApiService.cases().list(parent=PARENT).execute()

通过 CLI 使用 Cloud Support API

安装 Cloud CLI 后,可轻松调用 Support API 并传递相应的凭据以进行身份验证。以下示例演示了如何为列出组织父级中的可用案例的 API 调用执行此操作。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \\
https://cloudsupport.googleapis.com/v2beta/organizations/ORGANIZATION_ID/cases

主要概念

为了成功使用 Cloud Support API,请务必理解一些关键概念。我们将探索其中的一些重要概念。

案例

案例对象是包含与特定支持案例相关的详细信息的实体,由我们的支持团队处理。它包含案例创建时间戳、优先级、案例分类以及有关支持案例内容的说明等字段。每个支持案例还具有在关联支持生命周期内添加的关联评论和附件。

案例分类

案例分类用于标识支持案例的主题。通常包含特定产品(例如“Cloud Storage”或“Compute Engine”)和常规问题类型(例如“权限”或“延迟时间”)。

对于 v2beta,案例分类对象具有一个 id(一个完整分类的唯一标识符),以及一个 displayName(直观易懂的说明)。这是 v2alpha 变更中的一项主要变更。

创建支持请求时,必须填写有效的案例分类 ID。请务必选择准确的分类,因为它用于将案例转给专家。

支持请求评论

案例备注是 Google 支持团队传达支持请求更新的主要方式。当用户回复 Google 支持时,其回复也会显示为案例评论。

充电盒附件

案例附件包含有关上传到支持案例(来自用户或 Google 支持团队)的文件的详细信息。使用界面时,附件可能会与注释同时上传在 Cloud Console 中,但是,附件是在“案例”级别关联的,而不是在“评论”级别的关联。

操作者对象

执行器对象可指定执行指定操作的实体。例如,执行者可以是对支持请求发表评论的用户、上传附件的用户或创建支持请求的服务帐号(在 Support API 上下文中,指服务帐号电子邮件地址)。

案例资源结构

在 Cloud Support API V2 中,Google Cloud 组织或项目可以提供支持案例。“父级”标识符是指在“/cases/”之前的两个路径

组织由数字标识,因此组织育儿的案例名称可能如下所示:

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

项目有两个唯一标识符(ID 和数字),因此您可以使用以下任一项来标识由项目标识的案例:

projects/PROJECT_ID/cases/CASE_NUMBER
projects/PROJECT_NUMBER/cases/CASE_NUMBER

用户可以在调用 API 时实现上述任一标识符,但 API 仅使用项目编号返回响应。

IAM 权限是基于资源的祖先继承的,因此项目会继承其所属组织的权限。如需了解详情,请参阅有关资源层次结构的文档。