Guía del usuario de la API de Cloud Support V2

Descripción general

Para obtener más información sobre por qué es recomendable usar la API de Cloud Support y para qué sirve, consulta Descripción general de la API de Cloud Support. En esta página, se explica cómo comenzar a usar la versión 2 de la API de Cloud Support. También hay una versión v2beta disponible, pero hay algunas diferencias entre ambas. Es posible que algunos cambios y funciones estén disponibles en la versión v2beta antes de la v2, pero la API v2 probablemente sea más adecuada para la mayoría de los casos de uso.

Ahora veremos cómo configurar la API v2.

Getting Started

Antes de poder usar la API de Cloud Support, haz lo siguiente:

Para habilitar la API de Cloud Support, visita la página de la API de Cloud Support en Google Cloud Console y haz clic en HABILITAR.
Sigue las instrucciones que se indican en Crea cuentas de servicio para aprovisionar una cuenta de servicio. Para obtener más información sobre las cuentas de servicio, consulta la Descripción general de las cuentas de servicio.
Usa la pestaña IAM en la consola de Google Cloud para otorgar a la cuenta de servicio la función Organization Viewer o alguna otra función que otorgue el permiso resourcemanager.organizations.get.

También puedes usar el comando gcloud organizations add-iam-policy-binding:
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT
```
Para obtener información sobre cómo encontrar el valor correcto para "ORG_ID", consulta Recupera el ID de la organización.
Otorga a la cuenta de servicio la función de Editor de asistencia técnica o Visualizador de asistencia técnica. Para ello, ejecuta el siguiente comando:
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/cloudsupport.techSupportEditor \\
--member SERVICE_ACCOUNT
```
Si usas integraciones de terceros, como JIRA, otorga a la aplicación de terceros acceso a la cuenta de servicio. Para obtener más información sobre la autenticación, consulta Descripción general de la autenticación.

Si quieres usar OAuth 2.0 para la autenticación, haz lo siguiente:

Si aún no usas OAuth2 para autenticar con Google, configúralo con OAuth 2.0 para acceder a las API de Google. Presta especial atención a la sección sobre la autorización incremental.
Asegúrate de que se agreguen los siguientes dos alcances a los IDs de cliente de OAuth2 que usa tu aplicación:
- Para obtener acceso general a Google Cloud, usa https://www.googleapis.com/auth/cloud-platform o https://www.googleapis.com/auth/cloud-platform.read-only.
- Si quieres obtener acceso para recuperar o crear casos de ayuda y otros datos relacionados con la asistencia, visita https://www.googleapis.com/auth/cloudsupport.

Control de acceso y roles de IAM

El equipo de Atención al cliente usa los siguientes roles de IAM para controlar el acceso a los casos. Puedes usarlas o crear tus propias funciones personalizadas con los permisos que desees. Para obtener más información sobre IAM, consulta Control de acceso con IAM.

Rol	Permisos
`Tech Support Viewer`	cloudsupport.techCases.get cloudsupport.techCases.list cloudsupport.techCaseAttachments.list cloudsupport.techCaseAttachments.download cloudsupport.techCaseComments.list cloudsupport.techCaseUpdates.list
`Tech Support Editor`	Permisos de visualizador de asistencia técnica cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseComments.create

Decide qué bibliotecas usar para llamar a la API de Cloud Support

Existen tres rutas generales para llamar a la API.

Usa las bibliotecas cliente de Cloud de la API de Cloud Support para el lenguaje que deseas usar. Están disponibles para una gran variedad de idiomas, pero no admiten la carga ni la descarga de archivos adjuntos. Para obtener más información sobre este tipo de biblioteca, consulta Bibliotecas cliente de Cloud.
Usa la biblioteca de la API de Google para Python a fin de compilar un stub para llamar a la API de Cloud Support. Este es el enfoque heredado para llamar a la API. Puedes subir o descargar archivos adjuntos. Para obtener más información sobre este tipo de biblioteca, consulta Bibliotecas cliente de la API de Google.
Usa cURL o llama directamente a la API de otro modo. Esto tiene la ventaja de que es completamente personalizable, pero requiere que lo configures todo tú mismo.

Si no necesitas usar adjuntos, te recomendamos que uses las bibliotecas cliente de Cloud. De lo contrario, recomendamos usar la biblioteca de las API de Google para Python.

Usa bibliotecas cliente de Cloud

La API de Cloud Support tiene bibliotecas cliente de Cloud disponibles para lo siguiente:

Para comenzar con una, ve a su página y sigue las instrucciones que se indican allí.

Usa la biblioteca de la API de Google para Python

Para comenzar a usar la biblioteca de la API de Google para Python, haz lo siguiente:

Instala el paquete de Google discovery con pip.
```
pip install google-api-python-client
```

Compila un stub en tu 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}",
)

Llama al extremo que te interesa. Incluimos ejemplos de cómo hacerlo para cada extremo en la API de Cloud Support. Por ejemplo, consulta cases.list.

Cuando realices llamadas a la API con la biblioteca de la API de Google para Python, se usarán las credenciales predeterminadas del entorno en el que se ejecuta tu programa. Asegúrate de que la cuenta de servicio en ese entorno tenga los permisos mencionados en la sección Comienza ahora.

Usa cURL

Existen dos formas principales de autenticar tu llamada a cURL. Puedes usar una cuenta de servicio o credenciales predeterminadas de la aplicación. Para obtener más información sobre las credenciales predeterminadas de la aplicación, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

Autenticar con una cuenta de servicio

Autentica con Google Cloud CLI.

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

Envía la solicitud.

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

Autentica con una credencial predeterminada de la aplicación

Autentica con Google Cloud CLI.
```
gcloud auth application-default login
```

Envía la solicitud. Asegúrate de incluir un encabezado x-goog-user-project, que es obligatorio cuando llamas a la API de Cloud Support con las credenciales predeterminadas de la aplicación.

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