Guía del usuario de la API de Cloud Support

En esta página, se describe cómo comenzar a usar la versión 1 de la API de cloudsupport.googleapis.com. Actualmente, la versión 2 de esta API solo está disponible como versión previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Descripción general del proceso

En esta sección, se detalla el proceso general para comenzar a usar la API.

  1. El equipo de Atención al cliente crea una cuenta de asistencia para el cliente. Este es un requisito previo para todas las operaciones posteriores.
  2. El cliente especifica al equipo de Atención al cliente qué ID del proyecto le gustaría usar para acceder a la API. Este será el proyecto de consumidor designado para la API.

    Este proyecto será el recurso en el que está habilitada la API, pero las credenciales para llamar a la API se pueden usar desde cualquier proyecto de Google Cloud.

  3. El cliente genera una clave de API para el proyecto del consumidor. El cliente usará esta clave de API para realizar llamadas a la API. Para generar una clave de API, consulta Cómo usar claves de API.

  4. El equipo de atención al cliente permite el acceso a la API del equipo de atención al cliente (mediante las etiquetas de visibilidad correctas).

  5. El equipo de Atención al cliente agrega la cuenta de asistencia al cliente a la lista de entidades permitidas para acceder a la cuenta de servicio.

  6. El cliente habilita la API de Cloud Support en la página API de Cloud Support en Google Cloud Console y hace clic en HABILITAR.

    Ir a la página API de Cloud Support

Si quieres integrar la cuenta de servicio, haz lo siguiente:

  1. El cliente aprovisiona una o más cuentas de servicio mediante las instrucciones que se indican en Comprende las cuentas de servicio.

  2. El cliente le otorga a la cuenta de servicio la función Organization Viewer en la pestaña IAM en la consola o 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/ord-id
      --role roles/resourcemanager.organizationViewer
      --member service-account
     

  3. El cliente agrega una o más de estas cuentas de servicio como Usuario de asistencia mediante la página Configuraciónde asistenciade la consola.

  4. El cliente permite compartir sus credenciales para permitir que su conector JIRA y otras aplicaciones accedan a la cuenta de servicio. Para conocer los pasos, consulta Descripción general de la autenticación.

  5. Si el cliente ya tiene alguna herramienta de administración de credenciales, tiene sentido aprovechar la misma herramienta para las cuentas de servicio de Google Cloud.

  6. 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 aún no realizaste la autenticación con Google a través de OAuth2, configúrala mediante
    de acuerdo con el uso de las guías para OAuth 2.0 a fin de acceder a las API de Google. 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

Recupera la definición de API

La definición de la API se publica como un documento de descubrimiento de Google Cloud.

A continuación, se muestra un ejemplo. Sustituye <API_KEY> por una clave de API que generaste desde el proyecto de consumidor un paso anterior.

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

API de REST

Para todos los extremos enumerados a continuación, el valor de <host> se debe reemplazar por cloudsupport.googleapis.com.

Casos

Recupera y crea casos de ayuda.

Funciones requeridas
Tipo Función
IAM Visualizador de cuentas de asistencia (organización)
IAM Visualizador de organización (organización)

Obtener casos

Recupera el caso de ayuda especificado.

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

Cuenta de asistencia y número de caso especificados en la URL de la solicitud

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

CrearCaso

Crea un caso y lo asocia con la SupportAccount determinada.

Formato REST
POST <host>/v1/{parent=supportAccounts/*}/cases
Parámetros
Name Tipo Descripción
case Case

Un objeto de caso.

Ejemplo:


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

Ejemplo
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

Genera bibliotecas cliente

Clone el generador de clientes de API de Google:

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

Asegúrate de tener instalado Python 2.7:

sudo apt-get install python

Asegúrese de tener instalado PIP:

sudo apt-get install python-pip

Instala las dependencias:

pip install google-apis-client-generator

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.v1alpha2.json --output_dir=/tmp/cloudsupport_generated --language=java

Usar la API

Antes de comenzar

  • Agrega una dependencia en la Biblioteca cliente de la API de Java
  • Agrega una dependencia en el código generado en el paso anterior
  • Asegúrate de que tu código se compile correctamente

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