Guia do usuário da API Cloud Support V2

Informações gerais

Para saber mais sobre por que você iria querer usar a API Cloud Support e para que ela serve, consulte Visão geral da API Cloud Support. Nesta página, ensinamos como começar a usar a versão 2 da API Cloud Support. Também há uma versão v2beta disponível, mas há poucas diferenças entre as duas. Algumas alterações e recursos podem estar disponíveis na v2beta antes da v2, mas a API v2 provavelmente é mais adequada para a maioria dos casos de uso.

Agora vamos conferir como configurar a API v2.

Getting Started

Antes de usar a API Cloud Support, faça o seguinte:

  1. Para ativar a API Cloud Support, acesse a página da API Cloud Support no console do Google Cloud e clique em ATIVAR.

  2. Provisione uma conta de serviço seguindo as instruções em Criar contas de serviço. Para saber mais sobre contas de serviço, consulte Visão geral das contas de serviço.

  3. Use a guia "IAM" no console do Google Cloud para conceder à conta de serviço o papel Organization Viewer ou algum outro papel que conceda a permissão resourcemanager.organizations.get.

    Também é possível usar o comando gcloud organizations add-iam-policy-binding:

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

    Para saber como encontrar o valor correto de "ORG_ID", consulte Recuperar o ID da organização.

  4. Conceda à conta de serviço o papel de Editor ou Leitor de suporte técnico. Para fazer isso, execute:

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

  5. Se você usa integrações de terceiros, como o JIRA, conceda ao aplicativo de terceiros acesso à conta de serviço. Para saber mais sobre autenticação, consulte Visão geral da autenticação.

Se você quiser usar o OAuth 2.0 para autenticação:

  1. Se você ainda não estiver usando o OAuth2 para autenticar com o Google, configure-o seguindo o OAuth 2.0 para acessar as APIs do Google. Preste ainda mais atenção na 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 para recuperar ou criar casos de suporte e outros dados relacionados ao suporte: https://www.googleapis.com/auth/cloudsupport

Controle de acesso e papéis do IAM

O Customer Care usa os seguintes papéis do IAM para controlar o acesso aos casos. É possível usá-los ou criar seus próprios papéis personalizados com as permissões que você quiser. Para saber mais sobre o IAM, consulte Controle de acesso com o IAM.

Papel Permissões
Tech Support Viewer cloudsupport.techCases.get
cloudsupport.techCases.list
cloudsupport.techCaseAttachments.list
cloudsupport.techCaseAttachments.download
cloudsupport.techCaseComments.list
cloudsupport.techCaseUpdates.list
Tech Support Editor Permissões do leitor de suporte técnico
cloudsupport.techCases.create
cloudsupport.techCases.update
cloudsupport.techCases.escalate
cloudsupport.techCases.close
cloudsupport.techCaseAttachments.create
cloudsupport.techCase Comments.create

Como decidir quais bibliotecas usar para chamar a API Cloud Support

Há três caminhos gerais para chamar a API.

  1. Use as bibliotecas de cliente do Cloud da API Cloud Support na linguagem que quiser usar. Eles estão disponíveis para uma grande variedade de idiomas, mas não são compatíveis com upload ou download de anexos. Para saber mais sobre esse tipo de biblioteca, consulte Bibliotecas de cliente do Cloud.

  2. Use a biblioteca de APIs do Google para Python e crie um stub para chamar a API Cloud Support. Essa é a abordagem legada para chamar a API. Você pode fazer upload ou download de anexos com ele. Para saber mais sobre esse tipo de biblioteca, consulte Bibliotecas de cliente das APIs do Google.

  3. Use cURL ou chame a API diretamente. Esse processo tem a vantagem de ser totalmente personalizável, mas exige que você configure tudo por conta própria.

Se você não precisa usar anexos, recomendamos o uso das bibliotecas de cliente do Cloud. Caso contrário, recomendamos usar a biblioteca de APIs do Google para Python.

Como usar as bibliotecas de cliente do Cloud

A API Cloud Support tem as bibliotecas de cliente do Cloud disponíveis para:

Para começar com um deles, basta acessar a página correspondente e seguir as instruções.

Como usar a biblioteca de APIs do Google em Python

Para começar a usar a biblioteca de APIs do Google em Python, faça o seguinte:

  1. Instale o pacote do Google Discovery com pip.

    pip install google-api-python-client

  2. Crie um stub no código.

    import googleapiclient.discovery

api_version = "v2"
supportApiService = googleapiclient.discovery.build(
    serviceName="cloudsupport",
    version=api_version,
    discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
)

  3. Chame o endpoint em que você tem interesse. Fornecemos exemplos de como fazer isso para cada endpoint na API Cloud Support. Por exemplo, consulte cases.list.

Quando você faz chamadas para a API com a biblioteca de APIs do Google para Python, ela usa as credenciais padrão do ambiente em que o programa está sendo executado. Verifique se a conta de serviço nesse ambiente tem as permissões mencionadas na seção Como começar.

Como usar cURL

Há duas maneiras principais de autenticar sua chamada de cURL. É possível usar uma conta de serviço ou o Application Default Credentials. Para saber mais sobre o Application Default Credentials, consulte Como funciona o Application Default Credentials.

Como autenticar com uma conta de serviço

  1. Autenticar usando a Google Cloud CLI.

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

  2. Envie a solicitação.

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

Como autenticar com o Application Default Credentials

  1. Autenticar usando a Google Cloud CLI.

    gcloud auth application-default login

  2. Envie a solicitação. Inclua um cabeçalho x-goog-user-project, que é necessário quando você chama a API Cloud Support com credenciais padrão do aplicativo.

    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