Cloud Support API V2 用户指南

概览

如需详细了解您想要使用 Cloud Support API 的原因及其用途，请参阅 Cloud Support API 概览。本页面介绍了如何开始使用 Cloud Support API 版本 2。还有一个 v2beta 版本，但这两个版本之间有一些区别。某些变更和功能可能在 v2 之前的 v2beta 中提供，但 v2 API 可能更适合大多数用例。

现在，我们来讨论如何设置 v2 API。

开始使用

在使用 Cloud Support API 之前，请执行以下操作：

1. 通过访问 Google Cloud 控制台中的 Cloud Support API 页面并点击启用来启用 Cloud Support API。

2. 按照创建服务帐号中的说明预配服务帐号。如需详细了解服务帐号，请参阅服务帐号概览。

3. 使用 Google Cloud 控制台中的“IAM”标签页向服务帐号授予 Organization Viewer 角色或其他可授予 resourcemanager.organizations.get 权限的角色。

   您也可以使用 gcloud organizations add-iam-policy-binding 命令：

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

   如要了解如何查找“ORG_ID”的正确值，请参阅检索您的组织 ID。

4. 向服务帐号授予 Tech Support Editor 或 Tech Support Viewer 角色。为此，请运行以下命令：

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

5. 如果您使用的是 JIRA 等第三方集成，请向第三方应用授予对服务帐号的访问权限。如需详细了解身份验证，请参阅身份验证概览。

如果要使用 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

访问权限控制和 IAM 角色

Customer Care 使用以下 IAM 角色来控制对支持请求的访问权限。 您可以使用这些权限，也可以自行创建具有所需权限的任何自定义角色。如需详细了解 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	Tech Support Viewer 权限 cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseComments.create

确定要使用哪些库来调用 Cloud Support API

调用该 API 的一般路径有三种。

1. 根据您要使用的语言使用 Cloud Support API Cloud 客户端库。这些插件支持多种语言，但不支持上传或下载附件。如需详细了解此类库，请参阅 Cloud 客户端库

2. 使用 Python Google API 库构建一个存根来调用 Cloud Support API。 这是调用 API 的传统方法。您可以使用该应用上传或下载附件。 如需详细了解此类库，请参阅 Google API 客户端库。

3. 使用 c网址 或直接调用 API。这样做的好处是可以完全自定义，但需要您自行配置所有内容。

如果您不需要使用连接，我们建议您使用 Cloud 客户端库。否则，我们建议使用 Python Google API 库。

使用 Cloud 客户端库

Cloud Support API 提供适用于以下各项的 Cloud 客户端库：

• Java
• Python
• .NET
• Go
• 节点
• Ruby
• PHP

要开始使用，只需转到相应页面并按照说明操作即可。

使用 Python Google API 库

要开始使用 Python Google API 库，请执行以下操作：

1. 使用 pip 安装 Google 发现软件包。

   pip install google-api-python-client
   

2. 在代码中构建桩。

   import googleapiclient.discovery
   
   api_version = "v2"
   supportApiService = googleapiclient.discovery.build(
       serviceName="cloudsupport",
       version=api_version,
       discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
   )
   

3. 调用您感兴趣的端点。我们在 Cloud Support API 中提供了为每个端点执行此操作的示例。有关示例，请参阅 cases.list。

当您使用 Python Google API 库调用 API 时，它将使用运行您的程序的环境的默认凭据。确保该环境中的服务帐号具有使用入门部分中提及的权限。

使用 cURL

对 c网址 调用进行身份验证的方式主要有两种。您可以使用服务帐号，也可以使用应用默认凭据。如需详细了解应用默认凭据，请参阅应用默认凭据的工作原理。

使用服务账号进行身份验证

1. 使用 Google Cloud CLI 进行身份验证。

   gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL \
     --key-file=/path/key.json \
     --project=PROJECT_ID
   

2. 发送请求。

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

使用应用默认凭据进行身份验证

1. 使用 Google Cloud CLI 进行身份验证。

   gcloud auth application-default login
   

2. 发送请求。请务必添加 x-goog-user-project 标头，使用应用默认凭据调用 Cloud Support API 时，此标头是必需的。

   curl \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: $(gcloud config get-value project)" \
     https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases