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 v2beta.

Puedes integrar la API de Cloud Support para usar Cloud Customer Care con tu sistema de administración de relaciones con clientes (CRM) de tu organización. La API de Cloud Support permite que los usuarios completen 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 distintos 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.

  1. Para habilitar la API de Cloud Support, visita la página API de Cloud Support en Google Cloud Console y haz clic en HABILITAR.

    Ir a la página API de Cloud Support

  2. Aprovisiona una o más cuentas de servicio con las instrucciones de la 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.

  3. Otorga a la cuenta de servicio la función Organization Viewer en la pestaña IAM en la consola o en cualquier otra función que otorgue el permiso resourcemanager.organizations.get.

    También puedes hacerlo de manera programática:

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

  1. Otorga a la cuenta de servicio las funciones de Editor de asistencia técnica 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

  2. Si usas integraciones de terceros como JIRA, comparte credenciales para otorgar a la aplicación de terceros acceso a la cuenta de servicio. Para conocer los pasos, consulta Descripción general de la autenticación.

  3. Las aplicaciones del cliente realizan llamadas regulares a la API (como lo haría un usuario final) con las credenciales de la cuenta de servicio, en lugar de las credenciales de los usuarios finales.

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

  1. Si todavía no te autenticas con Google mediante OAuth2, sigue las guías para OAuth 2.0 a acceder a las API de Google a fin de configurarlo. Presta especial atención a la sección sobre la autorización incremental.
  2. Asegúrate de que se agreguen los siguientes dos alcances 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
    • Si deseas acceder para recuperar o crear tickets de asistencia y otros datos relacionados, https://www.googleapis.com/auth/cloudsupport

Control de acceso y funciones 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.

Función 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

Generar bibliotecas cliente de manera local

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

  1. Usa el comando a continuación para generar el archivo de definición.
curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2beta' > /tmp/cloudsupport.v2beta.json
  1. A continuación, clone el generador de clientes de las API de Google:
cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
  1. Asegúrese de tener Python instalado:
sudo apt-get install python
  1. Asegúrese de que el PIP esté instalado:
sudo apt-get install python-pip
  1. Instala las dependencias:
pip install google-apis-client-generator
  1. Genera bibliotecas cliente:

Este comando generará una o dos advertencias que comiencen con WARNING:root:object without properties. Se pueden ignorar. Se seguirá generando la biblioteca cliente.

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

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 solo unas pocas líneas de código. lo que facilita la integración en varios productos de GCP, como App Engine o Compute Engine.

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

import googleapiclient.discovery

SERVICE_NAME = "cloudsupport"
API_VERSION = "v2beta"
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()

Usar la API de Cloud Support a través de la CLI

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

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

Conceptos clave

Para usar la API de Cloud Support con éxito, es importante tener un conocimiento de alto nivel de algunos de los conceptos clave. A continuación, exploraremos algunos de estos conceptos clave.

Casos

El objeto Case es la entidad que contiene los detalles relacionados con un caso de ayuda específico, que 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 del caso de asistencia. Cada caso de ayuda 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 sobre el que se trata el caso de ayuda. En general, contendrá un producto específico, como Cloud Storage, Compute Engine y un tipo de problema general, como Permisos y Latencia.

Para la versión v2beta, el objeto de clasificación de casos tiene un id que es un identificador único para la clasificación completa, así como un displayName que es la descripción legible. Este es uno de los principales cambios de la versión 2.2.

Un ID de clasificación de caso válido es un campo obligatorio cuando se crea un caso de asistencia. Es importante tener una clasificación precisa, ya que se usa para enviar 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 actualizaciones sobre un caso de ayuda. Cuando el usuario responde a la Atención al cliente de Google, sus respuestas también se muestran como comentarios de caso.

Archivos adjuntos de casos

Los adjuntos de caso contienen detalles sobre los archivos que se subieron al caso de ayuda (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 archivos adjuntos están asociados a un nivel de “mayúsculas y minúsculas” y no al nivel de “comentario”.

Objeto de actor

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

Estructura del recurso del caso

En la API de Cloud Support V2, los casos de ayuda pueden ser superiores de las organizaciones o los proyectos de Google Cloud. El identificador "parent" alude a las dos rutas de acceso anteriores a &cases; cases.

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

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

Los proyectos tienen dos identificadores únicos, un ID y un número, de manera que un caso que sea superior a un proyecto se pueda 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 llame a la API. Sin embargo, la API solo mostrará respuestas con el número del proyecto.

Los permisos de IAM se heredan según la ascendencia 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 jerarquía de recursos.