Cloud Support API V2 User Guide

Overview

This page describes how to get started with version 2 of the cloudsupport.googleapis.com API, in particular, the v2 endpoint.

You can integrate the Cloud Support API to use Cloud Customer Care with your organization's customer relationship management (CRM) system. The Cloud Support API enables users to complete various support tasks directly in the CRM, including:

• Create and manage support cases.
• List, create, and download attachments for cases.
• List and create comments in cases.

The following sections review steps for getting started, as well as exploring key concepts surrounding the various elements related to the Support API.

Getting Started

This section details the high-level process for getting started with the Cloud Support API.

1. Enable the Cloud Support API by visiting the Cloud Support API page in the Google Cloud console and clicking ENABLE.

   Go to the Cloud Support API page

2. Provision one or more service accounts using the instructions at Understanding service accounts.

   If you have a credentials management tool already, it makes sense to leverage the same tool for Google Cloud service accounts.

3. Grant the service account the Organization Viewer role under the IAM tab in Google Cloud console, or any other role which grants the resourcemanager.organizations.get permission.

   This can also be done programmatically:

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

Note: Steps for finding the correct value 'ORG_ID' can be found here.

1. Grant the service account the Tech Support Editor or Tech Support Viewer role. This can be done programmatically:

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

2. If using third-party integrations like JIRA, give the third-party application access to the service account by sharing credentials. For steps, see Authentication overview.

3. The customer's applications make regular API calls (just like an end user would), using the service account credentials instead of end-user credentials.

If you want OAuth 2.0 authentication:

1. If not already authenticating with Google using OAuth2, set it up by following the using the guides for OAuth 2.0 to Access Google APIs. Pay extra attention to the section about incremental authorization.
2. Make sure the following two scopes are added to the OAuth2 client IDs used by your application:
   • For general access to Google Cloud: https://www.googleapis.com/auth/cloud-platform or https://www.googleapis.com/auth/cloud-platform.read-only
   • For access to retrieve or create support tickets and other support related data: https://www.googleapis.com/auth/cloudsupport

Access Control and IAM Roles

Premium Support uses the following IAM Roles to control access to cases. For more information, see the documentation on Access control.

Role	Permissions
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 permissions cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseComments.create

Note: You can also create custom roles with these permissions to grant access to the API endpoints below.

Generating Client Libraries Locally

The API definition is served as a Google Cloud discovery document. For more information, see Google API Discovery Service.

1. Use the command below to generate the definition file. curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2' > /tmp/cloudsupport.v2.json

2. Next, clone the Google APIs client generator: cd /tmp/; git clone https://github.com/google/apis-client-generator.git;

3. Make sure you have Python installed: sudo apt-get install python

4. Make sure PIP is installed: sudo apt-get install python-pip

5. Install dependencies: pip install google-apis-client-generator

6. Generate client libraries: This command will generate one or two warnings starting with WARNING:root:object without properties. They can be ignored. The client library will still be generated. ./generate.sh --input=/tmp/cloudsupport.v2.json --output_dir=/tmp/cloudsupport_generated --language=java

Using the Cloud Support API via Client Libraries (Python)

In this example, users can make use of the Client Libraries in Python, using only a few lines of code. This makes it easy to integrate into various Google Cloud products like App Engine or Compute Engine.

When using this method, the API will attempt to use the default credentials for whichever environment the code is running in (so be sure that the service account being used has the appropriate permissions mentioned in the Getting Started section).

import googleapiclient.discovery

SERVICE_NAME = "cloudsupport"
API_VERSION = "v2"
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()

Using the Cloud Support API via cURL

When the gcloud CLI is installed, it is simple to call the Support API and pass the appropriate credentials to authenticate. The below example shows how to do this for an API call which lists available cases in the organization parent.

Note: The actor associated with the token will depend on what account is configured in gcloud. You can specify gcloud to authenticate using the service account configured in the Getting Started section.

Authenticating with Service Account

Step 1: Authenticate

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

Step 2: Send Request

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

Authenticating with Application Default Credentials

Step 1: Authenticate

gcloud auth application-default login

Step 2: Send Request

NOTE: An additional header (x-goog-user-project) is required when calling the Cloud Support API using application default credentials.

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

Key Concepts

In order to use the Cloud Support API successfully, it is important to have a high-level understanding of some of the key concepts. We will explore some of these key concepts below.

Cases

The Case object is the entity which contains the details related to a specific Support Case, which are handled by our Support team. It contains fields such as the case creation timestamp, the priority, case classification, and the description of what the Support case is about. Every Support Case also has associated comments and attachments which get added throughout the lifetime of a support case.

Case Classification

Case Classification identifies the topic in which the Support Case is about. In general, it will contain a specific product, such as "Cloud Storage" or "Compute Engine" and a general issue type such as "Permissions" or "Latency".

For v2, the Case Classification object has an id which is a unique identifier for the full classification, as well as a displayName which is the human-readable description. This is one of the main changes from v2alpha.

A valid Case Classification ID is a required field when creating a Support Case. An accurate classification is important to have, as it is used to route the case to a specialist.

Case Comments

Case Comments are the main method in which Google's Support team communicates updates on a Support Case. When the user responds to Google Support, the user's responses also appear as Case Comments.

Case Attachments

Case Attachments contain details about files that were uploaded to the Support Case (from either the user or Google Support). Attachments might be uploaded in the Cloud Console at the same time as a comment when using the UI, however, attachments are associated on a "case" level, and not the "comment" level.

Actor Object

The Actor Object specifies an entity that performed a given action. For example, an actor could be the user who posted a comment on a support case, the user who uploaded an attachment, or the service account that created the support case (which in context of the Support API, is the service account email address).

Case Resource Structure

In the Cloud Support API V2, Support Cases can be parented by either Google Cloud Organizations or Projects. The "parent" identifier refers to the two paths prior to "/cases/".

Organizations are identified by a number, so the name of a case parented by an organization would look like the following:

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

Projects have two unique identifiers, an ID and a number, so a case parented by a project can be identified with either:

projects/PROJECT_ID/cases/CASE_NUMBER

projects/PROJECT_NUMBER/cases/CASE_NUMBER

The user can implement either of these identifiers when calling the API, however the API only will return responses using the project number.

Note: Each case will either have an Organization-based or a Project-based parent. If a case is associated through a project, it will not be accessible through the organization resource identifier, and vice versa.

IAM Permissions are inherited based on the ancestry of a resource, so projects inherit permissions from the organization that they belong to. For more information, see the documentation on Resource hierarchy.