Guia do usuário da API Cloud Support

Esta página descreve como começar a usar a versão 1 da API cloudsupport.googleapis.com. Atualmente, a versão 2 dessa API está disponível somente como uma versão pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

Visão geral do processo

Nesta seção, detalhamos o processo de alto nível para começar a usar a API.

  1. A equipe do Customer Care cria uma conta de suporte para o cliente. Esse é um pré-requisito para todas as operações posteriores.

  2. O cliente especifica à equipe do Customer Care qual ID de projeto ele quer usar para acessar a API. Esse projeto será o projeto do consumidor designado para a API.

    Esse projeto será o recurso em que a API está ativada, mas as credenciais para chamar a API podem ser usadas em qualquer projeto do Google Cloud.

  3. O cliente gera uma chave de API para o projeto do consumidor. O cliente usará essa chave de API para fazer chamadas. Para gerar uma chave de API, consulte Como usar chaves de API.

  4. A equipe do Customer Care autoriza o acesso da API à equipe do cliente (aplicando os rótulos de visibilidade corretos).

  5. A equipe do Customer Care autoriza a conta de suporte ao cliente para acessar a conta de serviço.

  6. O cliente ativa a API Cloud Support visitando a página da API Cloud Support no Console do Google Cloud e clicando em ATIVAR.

    Acessar a página API Cloud Support

Se você quiser a integração da conta de serviço:

  1. O cliente provisiona uma ou mais contas de serviço seguindo as instruções em Noções básicas sobre contas de serviço.

  2. O cliente concede à conta de serviço o papel Organization Viewer na guia do IAM no Console do Google Cloud ou qualquer outro papel que conceda a permissão resourcemanager.organizations.get.

    Isso também pode ser feito de maneira programática: 

      gcloud organizations add-iam-policy-binding
  organizations/ord-id
  --role roles/resourcemanager.organizationViewer
  --member service-account

  3. O cliente adiciona uma ou mais dessas contas de serviço como um usuário de suporte na página Suporte > Configurações no Console do Google Cloud.

  4. O cliente permite que o conector JIRA ou outros aplicativos acessem a conta de serviço compartilhando credenciais. Para ver as etapas, consulte Visão geral da autenticação.

  5. Se o cliente já tiver alguma ferramenta de gerenciamento de credenciais, convém utilizar a mesma ferramenta para as contas de serviço do Google Cloud.

  6. Os aplicativos do cliente fazem chamadas de API regulares (como um usuário final faria), usando as credenciais da conta de serviço em vez de credenciais do usuário final.

Se você quiser a autenticação do OAuth 2.0:

  1. Se você ainda não estiver autenticando com o Google usando OAuth2, configure-o até
    seguindo os guias disponíveisOAuth 2.0 para acessar as APIs do Google de dados. Preste ainda mais atenção à seção sobre autorização incremental.
  2. Verifique se os dois escopos a seguir foram adicionados aos IDs do cliente OAuth2 usados pelo aplicativo:
    • Para acesso geral ao Google Cloud: https://www.googleapis.com/auth/cloud-platform ou https://www.googleapis.com/auth/cloud-platform.read-only
    • Para acessar a recuperação ou criar tíquetes de suporte e outros dados relacionados ao suporte: https://www.googleapis.com/auth/cloudsupport

Como buscar a definição da API

A definição da API é exibida como um documento de descoberta do Google Cloud.

Veja um exemplo: Substitua <API_KEY> por uma chave de API gerada no projeto do consumidor, uma etapa anterior.

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

API REST

Para todos os endpoints listados abaixo, o valor de <host> precisa ser substituído por cloudsupport.googleapis.com.

Casos

Recupere e crie casos de suporte.

Papéis necessários
Tipo Papel
IAM Visualizador da conta de suporte (organização)
IAM Visualizador da organização (organização)

GetCase

Recuperar a consulta de suporte especificada.

Formato REST
GET <host>/v1/{name=supportAccounts/*/cases/*}
Parâmetros

Número da conta e do caso de suporte especificados no URL da solicitação.

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

CreateCase

Cria um caso e o associa à SupportAccount fornecida.

Formato REST
POST <host>/v1/{parent=supportAccounts/*}/cases
Parâmetros
Nome Tipo Descrição
case Case

Um objeto de caso.

Exemplo:


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

Exemplo
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

Como gerar bibliotecas de cliente

Clone o gerador de clientes das APIs do Google:

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

Verifique se o Python 2.7 está instalado:

sudo apt-get install python

Verifique se o PIP está instalado:

sudo apt-get install python-pip

Instale as dependências:

pip install google-apis-client-generator

Gerar bibliotecas de cliente:

Este comando gerará um ou dois avisos que começam com WARNING:root:object without properties. Eles podem ser ignorados. A biblioteca de cliente ainda será gerada.

./generate.sh --input=/tmp/cloudsupport.v1alpha2.json --output_dir=/tmp/cloudsupport_generated --language=java

Como usar a API

Antes de começar

  • Adicione uma dependência às bibliotecas de cliente de APIs para Java
  • Adicione uma dependência no código gerado na etapa acima.

  • Garantir a compilação do código

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