Cloud Support API user guide

This page describes how to get started with version 1 of the cloudsupport.googleapis.com API. Version 2 of this API is currently only available as a Pre-GA release. For more information, see the launch stage descriptions.

Process overview

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

  1. Customer Care team creates a support account for the customer. This is a prerequisite for all further operations.
  2. The customer specifies to the Customer Care team which project id they would like to use to access the API. This project will be the designated consumer project for the API.

    This project will be the resource on which the API is enabled, but the credentials to call the API can be used from any Google Cloud project.

  3. The customer generates an API key for the consumer project. The customer will use this API key make calls to the API. To generate an API key, see Using API keys.

  4. Customer Care team allowlists the customer team API access (by applying the correct visibility labels).

  5. Customer Care team allowlists the customer support account for service account access.

  6. The customer enables 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

If you want service account integration:

  1. The customer provisions one or more service accounts using the instructions at Understanding service accounts.

  2. The customer grants the service account the Organization Viewer role under the IAM tab in 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/ord-id
      --role roles/resourcemanager.organizationViewer
      --member service-account
     

  3. The customer adds one or more of these service accounts as a Support User through the Support > Settings page in Cloud Console.

  4. The customer lets their JIRA connector or other applications access the service account by sharing credentials. For steps, see Authentication overview.

  5. If the customer has some credentials management tool already, it makes sense to leverage the same tool for Google Cloud service accounts.

  6. 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

Fetching the API definition

The API definition is served as a Google Cloud discovery document.

Here is an example. Substitute <API_KEY> with an API key you have generated from the consumer project a previous step.

curl 'https://cloudsupport.googleapis.com/$discovery/rest?key=<API_KEY>&labels=TRUSTED_TESTER&version=v1alpha2' > /tmp/cloudsupport.v1alpha2.json

REST client

REST API

For all endpoints listed below, the value for <host> should be replaced with cloudsupport.googleapis.com.

Support Accounts

List the Support Accounts to which a user has access and manage Support Account details.

Required Roles
Type Role
IAM Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Development, Production, or Business Critical

ListSupportAccounts

Lists all SupportAccounts to which the currently authenticated user has access.

REST Format
GET <host>/v1/supportAccounts
Parameters
Name Type Description
filter string

Free form filter to apply to search result. Example usages:

filter="name=gcp-sa-1234"

filter="cloud_resource=organizations/my-org-1234"

page_size int64 Maximum number SupportAccounts to return in the response. For most users, this will not be very relevant as the number of SupportAccounts will be very low.
page_token string A token identifying the page of results to return. If unspecified, the first page of results is returned.
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  http://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234?filter=cloud_resource:organizations/8675309

GetSupportAccount

Retrieve the specified Support Account.

REST Format
GET <host>/v1/{name=supportAccounts/*}
Parameters

Support Account specified in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234

User Management

Used by the administrator to programmatically add or remove users from support roles.

Required Roles
Type Role
IAM Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Development, Production, or Business Critical

GetUserRole

Retrieve the SupportRole of the given user. The user to be retrieved is determined from either the email field in the request message, or the credentials of the authenticated user if the former is not specified.

REST Format
GET <host>/v1/{name=supportAccounts/*}:getUserRole
Parameters
Name Type Description
email string The email address for the user whose role is to be fetched.
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:getUserRole?email=john@example.com

GetSupportRoles

Retrieve a list of all SupporRoles associated with the specified Support Account.

REST Format
GET <host>/v1/{name=supportAccounts/*}:getRoles
Parameters

Support Account specified in the URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:getRoles

SetSupportRoles

Update the list of SupportRoles associated with the given SupportAccount.

REST Format
POST <host>/v1/{name=supportAccounts/*}:setRoles
Parameters
Name Type Description
roles SupportRole[] The full list of roles to be associated with the SupportAccount.
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{
  "roles": [
    {
      "email": "john@example.com",
      "role": "SITE_RELIABILITY",
    },
    {
      "email": "alex@example.com",
      "role": "OPERATION",
    },
    {
      "email": "tiger@example.com",
      "role": "ROLE_UNSPECIFIED",
    },
],
  "etag": "ZrTGhhB"
}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:setRoles

Where the role attribute can take on the following values:

Role Type Description
ROLE_UNSPECIFIED Delete this users support role.
BASIC The "Basic" support role.
DEVELOPER The "Development" support role.
OPERATION The "Production" support role.
SITE_RELIABILITY The "Business Critical" support role.

SetSupportRoles method will return an instance of google.longrunning.Operation. To retrieve the status of SetSupportRoles, you will need to poll the GetOperation endpoint using the operation ID. The operation ID will be a mix of alpha-numeric characters and have the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Cases

Retrieve, create, and update support cases.

Required Roles
Type Role
IAM Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Role Development, Production, or Business Critical

ListCases

Retrieve the list of support cases associated with the SupportAccount.

REST Format
GET <host>/v1/{parent=supportAccounts/*}/cases
Parameters
Name Type Description
filter string Currently only accepts the values "OPEN" or "CLOSED".
page_size int64 Maximum number of cases to fetch with each request.
page_token string A token identifying the page of results to return. If unspecified, the first page of results is returned.
Example
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases

GetCase

Retrieve the specified support case.

REST Format
GET <host>/v1/{name=supportAccounts/*/cases/*}
Parameters

Support Account and Case number specified in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678

CreateCase

Creates a case and associates it with the given SupportAccount.

REST Format
POST <host>/v1/{parent=supportAccounts/*}/cases 
Parameters
Name Type Description
case Case

A case object.

Example:

     { \
        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 \
      }
      

Example
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

UpdateCase

Update a support case. At present only the priority, subject and cc_address fields may be updated.

REST Format
PATCH <host>/v1/{case.name=supportAccounts/*/cases/*} 
Parameters
Name Type Description
case Case The updated support Case.
update_mask String[]

The list of Case fields to be updated.

Example:

["case.priority"]

Example: Update case
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ display_name: "My app is down", priority: 2, cc_addresses: ["james@example.com", "susan@example.com"]}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.cc_addresses,case.priority,case.display_name
Example: Close case
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ state: "CLOSED" }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.state

EscalateCase

Escalate a support case. Escalating a support case will initiate the Customer Care escalation management process. The ability to self-escalate a support case is restricted to users who hold the Business Critical and Production roles, only.

REST Format
POST <host>/v1/{name=supportAccounts/*/cases/*}:escalate
Parameters
Name Type Description
reason Enum

The reason why the case is being escalated.

Valid values:

  • REASON_UNSPECIFIED: The escalation reason is in an unknown state or has not been specified.
  • RESOLUTION_TIME: The case is taking too long to resolve.
  • TECHNICAL_EXPERTISE: The support agent does not have the expertise required to successfully resolve the issue.
  • BUSINESS_IMPACT: The issue is having a significant business impact.
justification String Free text description to accompany the reason field and provide more detail as to why the case was escalated.
Example
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ reason: "TECHNICAL_EXPERTISE", justification: "There is no technical expertise."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:escalate

GetIssueTaxonomy

Retrieve the taxonomy of issue categories and product components used when creating a support case.

REST Format
GET <host>/v1:getIssueTaxonomy
Parameters
Name Type Description
product_type string Should always be set to "CLOUD_PLATFORM".
Example
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1:getIssueTaxonomy

Attachments

Retrieve, create or download files attached to a support case. Attaching a file to a support case is new attachment is a three-step process:

  1. POST to the :startAttachment endpoint to generate a new Attachment name.
  2. POST to the Bytestream.Write endpoint to upload the raw bytes of the attachment.
  3. POST to /attachments to fully create the Attachment and associate it with a support case. Create the attachment includes all file metadata such as the mime type (such as image/jpeg), size (in bytes), and file name (r2_d2.jpg).
Required Roles
Type Role
IAM Cloud Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Development, Production, or Business Critical.

ListAttachments

Retrieves metadata for all the attachments associated with the given support case.

REST Format
GET <host>/v1/{parent=supportAccounts/*/cases/*}/attachments
Parameters

Support Account and Case number in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/attachments
Bytestream.Read

You can download the raw bytes of the attachment using the Bytestream.Read endpoint by issuing the following REST API call as follows:

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X GET https://cloudsupport.googleapis.com/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?alt=media

StartAttachment

Initiate the process of creating a new Attachment. The method returns a string which represents the resource name for the Attachment. The resource name is used in the calls to the ByteStream.Write and CreateAttachment endpoints which follow.

REST Format
POST <host>/v1/{parent=supportAccounts/*/cases/*}:startAttachment
Parameters

Support Account and Case number in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d {} https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:startAttachment
Bytestream.Write

You can upload the raw attachment bytes by calling Bytestream.Write as follows:

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X POST -T {"r2-d2.jpg"} https://cloudsupport.googleapis.com/upload/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?upload_type=media

CreateAttachment

Create the attachment metadata and associate the attachment with the specified support case. The attachment name must first be generated by a call to :startAttachment, and the maximum attachment size is 32MB.

REST Request
POST <host>/v1/{name=supportAccounts/*/cases/*}/attachments
Parameters
Name Type Description
attachment Attachment

An attachment object.

Example:

{
  name: "supportAccounts/gcp-sa-1234/cases/998877/attachments/55115511", \
  file_name: "giraffe.jpg", \
  mime_type: "image/jpeg", \
  size: 986712, // in bytes \
}
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name: "supportAccounts/gcp-sa-1234/cases/5678/attachments/9012", mime_type: "image/jpeg", file_name: "R2-D2.jpg", size: 4458 }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/attachments

Comments

Create or list comments on a support case.

Required Roles
Type Role
IAM Cloud Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Development, Production, or Business Critical

ListComments

List all comments associated with the specified support case.

REST
GET <host>/v1/{name=supportAccounts/*/cases/*}/comments
Parameters

Support Account and Case number in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/comments

CreateComment

Adds a new comment to a case.

REST Format
POST <host>/v1/{name=supportAccounts/*/cases/*}/comments
Parameters
Name Type Description
comment Comment

The comment object.

Example:

{
text: "This is my comment", \
}
           

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name:"supportAccounts/gcp-sa-1234/cases/5678",text:"I am commenting on this case."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/comments

Phone Support

Retrieve a list of world-wide contact numbers for Customer Care, and generate a PIN to call phone support.

Required Permissions
Type Permission
IAM Cloud Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Role Development, Production, or Business Critical

ListPhoneContacts

List the world-wide contact numbers used to reach Customer Care.

REST
GET <host>/v1/phoneContacts
Parameters

None.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/phoneContacts

GenerateEpin

Generates a unique PIN that can be used to authenticate against telephony system for Google Cloud support.

REST Format
POST <host>/v1/{name=supportAccounts/*}:generateEpin
Parameters
Name Type Description
project_id string Google Cloud project ID associated with this PIN. Setting this field helps a support agent retrieve project details prior to the phone call.
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{project_id: "my-app-project"}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:generateEpin

Notifications

List any notifications related issued by Customer Care.

Required Roles
Type Role
IAM Cloud Support Account Viewer (Organization)
IAM Organization Viewer (Organization)
Support Development, Production, or Business Critical

ListNotifications

List all open Google Cloud incidents known to be actively impacting customers. The response will include issues impacting all products, not those specific to the user who invoked the endpoint.

REST Format
GET <host>/v1/{parent=supportAccounts/*}/notifications
Parameters
Name Type Description
page_size int32 Maximum number Notifications to return in the response.
page_token string A token to retrieve the next page of results. The ListNotifications endpoint currently does not support pagination.
Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/notifications

IAM

Endpoints to interact with Identity and Access Management services.

TestIamPermissions

Verify whether the currently authenticated user has permissions on the given Customer Care resource. Only Support Accounts, Cases, Operations, and Comments are considered valid Customer Care resources.

For example, to check whether the user has access to fetch details of a Support Account, TestIamPermissionsRequest should be populated with:

resource: "supportAccounts/{support_account_id}"
permission: "cloudsupport.accounts.get"
REST Format
POST <host>/v1/{resource=**}:testIamPermissions
Parameters
Name Type Description
permissions string[]

List of permissions to test.

Example:

`["cloudsupport.comments.list", "cloudsupport.cases.list"]`

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d '{permissions: "cloudsupport.accounts.get"}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:testIamPermissions

Operations

Endpoints to retrieve the status of long-running Operations.

GetOperation

Retrieve the status of an existing Operation.

REST Format
GET <host>/v1/operations/{name=supportAccounts/*/operations/*}
Parameters

Support Account and Operation identifier specified in the request URL.

Example
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/operations/supportAccounts/gcp-sa-1234/operations/5678-0912

Generating client libraries

Clone Google APIs client generator:

cd /tmp/; git clone https://github.com/google/apis-client-generator.git;

Make sure you have Python 2.7 installed:

sudo apt-get install python

Make sure you have PIP 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.v1alpha2.json --output_dir=/tmp/cloudsupport_generated --language=java

Using the API

Before you begin

  • Add a dependency on the API Client Libraries Java
  • Add a dependency on the code that was generated in the above step
  • Make sure your code builds successfully

    // 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();