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. Por el momento, la versión 2 de esta API solo está disponible como versión de fase 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 de alto nivel 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 desea usar para acceder a la API. Este proyecto 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 llamarla 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 incluye en la lista de entidades permitidas el acceso a la API del equipo de atención al cliente (aplicando las etiquetas de visibilidad correctas).

  5. El equipo de atención al cliente incluye la cuenta de asistencia al cliente en la lista de entidades permitidas para acceder a la cuenta de servicio.

  6. Para habilitar la API de Cloud Support, el cliente debe visitar la página de la API de Cloud Support en Google Cloud Console y hacer clic en HABILITAR.

    Ir a la página de la 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 Información sobre las cuentas de servicio.

  2. El cliente le 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/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 Asistencia > Configuración de la consola de Google Cloud.

  4. El cliente permite que sus conectores JIRA y otras aplicaciones accedan a la cuenta de servicio mediante el uso compartido de credenciales. Para conocer los pasos, consulta la Descripción general de la autenticación.

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

  6. 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:

  1. Si aún no te autenticas con Google mediante OAuth2, configúralo con
    siguiendo 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.
  2. 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

Recupera la definición de la API

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

Aquí tenemos un ejemplo. Sustituye <API_KEY> por una clave de API que hayas generado del proyecto de consumidor en 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 que se enumeran a continuación, el valor de <host> se debe reemplazar por cloudsupport.googleapis.com.

Casos

Recupera y crea casos de asistencia.

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

Obtener casos

Recupera el caso de asistencia 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 las 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 PIP instalado:

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 a partir de 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 del código que se generó 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();