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 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/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 Google 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 API

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

Cases

Retrieve and create support cases.

Required Roles
Type Role
IAM Support Account Viewer (Organization)
IAM Organization Viewer (Organization)

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

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