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

Descripción general

En esta página, se describe cómo comenzar a usar la versión 2 de la API de cloudsupport.googleapis.com, en particular, el extremo v2.

Puedes integrar la API de Cloud Support para usar Atención al cliente de Cloud con el sistema de administración de relaciones con clientes (CRM) de tu organización. La API de Cloud Support permite a los usuarios completar varias tareas de asistencia directamente en la CRM, incluidas las siguientes:

Crea y administra casos de ayuda
Detalla, crea y descarga archivos adjuntos para casos.
Enumera y crea comentarios en los casos.

En las siguientes secciones, se revisan los pasos para comenzar y se exploran conceptos clave relacionados con los diversos elementos relacionados con la API de asistencia.

Comenzar

En esta sección, se detalla el proceso de alto nivel para comenzar a usar la API de Cloud Support.

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.

Ir a la página de la API de Cloud Support
Aprovisiona una o más cuentas de servicio con las instrucciones de la sección Información sobre las cuentas de servicio.

Si ya tienes una herramienta de administración de credenciales, tiene sentido aprovechar la misma herramienta para las cuentas de servicio de Google Cloud.
Otorga a la cuenta de servicio el rol Organization Viewer en la pestaña IAM de la consola de Google Cloud o cualquier otro rol que otorgue el permiso resourcemanager.organizations.get.

Esto también se puede hacer de forma programática:
```
  gcloud organizations add-iam-policy-binding \
  organizations/ORG_ID \
  --role roles/resourcemanager.organizationViewer \
  --member SERVICE_ACCOUNT
```

Otorga a la cuenta de servicio el rol de Editor o Visualizador de asistencia técnica. Esto se puede hacer de manera programática:

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

Si usas integraciones de terceros, como JIRA, comparte credenciales para darle a la aplicación de terceros acceso a la cuenta de servicio. Para conocer los pasos, consulta la Descripción general de la autenticación.
Las aplicaciones del cliente realizan llamadas normales a la API (como lo haría un usuario final) con las credenciales de la cuenta de servicio en lugar de las credenciales del usuario final.

Si quieres autenticar OAuth 2.0, haz lo siguiente:

Si aún no estás autenticando con Google mediante OAuth2, configúralo según las guías para 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 permisos a los ID de cliente de OAuth2 que usa tu aplicación:
- Para el acceso general a Google Cloud: https://www.googleapis.com/auth/cloud-platform o https://www.googleapis.com/auth/cloud-platform.read-only
- Para acceder a fin de recuperar o crear tickets de asistencia y otros datos relacionados, https://www.googleapis.com/auth/cloudsupport

Control de acceso y roles de IAM

La asistencia Premium usa las siguientes funciones de IAM para controlar el acceso a los casos. Para obtener más información, consulta la documentación sobre Control de acceso.

Role	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

Genera bibliotecas cliente de forma local

La definición de la API se entrega como un documento de descubrimiento de Google Cloud. Para obtener más información, consulta Servicio de descubrimiento de API de Google.

Usa el siguiente comando para generar el archivo de definición. curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2' > /tmp/cloudsupport.v2.json
A continuación, clona el generador de clientes de las API de Google: cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
Asegúrate de tener instalado Python: sudo apt-get install python
Asegúrese de que el PIP esté instalado: sudo apt-get install python-pip
Instala las dependencias: pip install google-apis-client-generator
Generar bibliotecas cliente: este comando generará una o dos advertencias a partir de WARNING:root:object without properties. Se pueden ignorar. Se seguirá generando la biblioteca cliente. ./generate.sh --input=/tmp/cloudsupport.v2.json --output_dir=/tmp/cloudsupport_generated --language=java

Cómo usar la API de Cloud Support a través de bibliotecas cliente (Python)

En este ejemplo, los usuarios pueden usar las bibliotecas cliente en Python con unas pocas líneas de código. Esto facilita la integración en varios productos de Google Cloud, como App Engine o Compute Engine.

Cuando uses este método, la API intentará usar las credenciales predeterminadas para cualquier entorno en el que se ejecute el código (así que asegúrate de que la cuenta de servicio que se usa tenga los permisos adecuados que se mencionan en la sección de introducción).

import googleapiclient.discovery

SERVICE_NAME = "cloudsupport"
API_VERSION = "v2"
API_DEFINITION_URL = "https://cloudsupport.googleapis.com/$discovery/rest?version=" + API_VERSION
PARENT = "organizations/" + ORGANIZATION_ID

supportApiService = googleapiclient.discovery.build(
    serviceName=SERVICE_NAME,
    version=API_VERSION,
    discoveryServiceUrl=API_DEFINITION_URL)

case_list = supportApiService.cases().list(parent=PARENT).execute()

Usa la API de Cloud Support a través de cURL

Cuando gcloud CLI está instalada, es fácil llamar a la API de asistencia y pasar las credenciales adecuadas para autenticar. En el siguiente ejemplo, se muestra cómo hacerlo para una llamada a la API que enumera los casos disponibles en el elemento superior de la organización.

Autentica con una cuenta de servicio

Paso 1: Autentica

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

Paso 2: 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

Paso 1: Autentica

gcloud auth application-default login

Paso 2: Envía la solicitud

NOTA: Se requiere un encabezado adicional (x-goog-user-project) cuando se llama 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

Conceptos clave

Para usar la API de Cloud Support de forma correcta, es importante tener una comprensión general de algunos de los conceptos clave. Exploraremos algunos de estos conceptos clave a continuación.

Casos

El objeto Case es la entidad que contiene los detalles relacionados con un caso de ayuda específico, que lo maneja nuestro equipo de asistencia al cliente. Contiene campos como la marca de tiempo de creación del caso, la prioridad, la clasificación y la descripción de qué se trata el caso de asistencia. Cada caso de asistencia también tiene comentarios y archivos adjuntos asociados que se agregan durante el ciclo de vida de un caso de ayuda.

Clasificación de casos

La Clasificación de casos identifica el tema del que se trata el Caso de ayuda. En general, contendrá un producto específico, como “Cloud Storage” o “Compute Engine”, y un tipo de problema general, como “Permisos” o “Latencia”.

En la versión 2, el objeto de clasificación de casos tiene un id (identificador único de la clasificación completa) y un displayName (descripción legible). Este es uno de los principales cambios desde v2alpha.

Para crear un caso de asistencia, se requiere un campo de ID de clasificación válido. Es importante contar con una clasificación precisa, ya que se utiliza para derivar el caso a un especialista.

Comentarios del caso

Los comentarios de casos son el método principal en el que el equipo de asistencia al cliente de Google comunica las actualizaciones de los casos de ayuda. Cuando el usuario responde al servicio de Atención al cliente de Google, sus respuestas también aparecen como comentarios de caso.

Archivos adjuntos de caso

Los adjuntos del caso contienen detalles sobre los archivos que se subieron al caso de asistencia (ya sea del usuario o del equipo de Atención al cliente de Google). Es posible que los archivos adjuntos se suban en Cloud Console al mismo tiempo que un comentario cuando se usa la IU. Sin embargo, los adjuntos se asocian a nivel de “caso” y no a nivel de “comentario”.

Objeto actor

El objeto de Actor especifica una entidad que realizó una acción determinada. Por ejemplo, un actor puede ser el usuario que publicó un comentario sobre un caso de asistencia, el usuario que subió un archivo adjunto o la cuenta de servicio que creó el caso de asistencia (que, en el contexto de la API de asistencia, es la dirección de correo electrónico de la cuenta de servicio).

Estructura de recursos del caso

En la API de Cloud Support V2, los casos de ayuda pueden ser superiores a las organizaciones o los proyectos de Google Cloud. El identificador "superior" hace referencia a las dos rutas de acceso anteriores a "/cases/".

Las organizaciones se identifican con un número, por lo que el nombre de un caso superior de una organización se vería de la siguiente manera:

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

Los proyectos tienen dos identificadores únicos, un ID y un número, de modo que un caso que es propiedad de un proyecto se puede identificar de las siguientes maneras:

projects/PROJECT_ID/cases/CASE_NUMBER

projects/PROJECT_NUMBER/cases/CASE_NUMBER

El usuario puede implementar cualquiera de estos identificadores cuando llama a la API. Sin embargo, la API solo mostrará respuestas con el número de proyecto.

Los permisos de IAM se heredan según el principal de un recurso, por lo que los proyectos heredan los permisos de la organización a la que pertenecen. Para obtener más información, consulta la documentación sobre la jerarquía de recursos.