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.
Enable the Cloud Support API by visiting the Cloud Support API page in the Google Cloud console and clicking ENABLE.
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.
Grant the service account the
Organization Viewer
role under the IAM tab in Google Cloud console, or any other role which grants theresourcemanager.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
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
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.
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:
- 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.
- 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
orhttps://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
- For general access to Google Cloud:
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 |
Generating Client Libraries Locally
The API definition is served as a Google Cloud discovery document. For more information, see Google API Discovery Service.
Use the command below to generate the definition file.
curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2' > /tmp/cloudsupport.v2.json
Next, clone the Google APIs client generator:
cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
Make sure you have Python installed:
sudo apt-get install python
Make sure PIP is installed:
sudo apt-get install python-pip
Install dependencies:
pip install google-apis-client-generator
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.
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.
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.