Guide de l'utilisateur de l'API Cloud Support

Cette page explique comment débuter avec la version 1 de l'API cloudsupport.googleapis.com. La version 2 de cette API n'est actuellement disponible qu'en version pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Présentation du processus

Cette section décrit le processus général de démarrage avec l'API.

  1. L'équipe du Cloud Customer Care crée un compte d'assistance pour le client. Il s'agit d'une condition préalable à toutes les opérations supplémentaires.
  2. Le client spécifie à l'équipe Customer Care le numéro du projet qu'il souhaite utiliser pour accéder à l'API. Ce projet sera le projet client désigné pour l'API.

    Ce projet sera la ressource sur laquelle l'API est activée, mais les identifiants permettant d'appeler l'API peuvent être utilisés à partir de n'importe quel projet Google Cloud.

  3. Le client génère une clé API pour le projet client. Le client utilisera cette clé API pour appeler l'API. Pour générer une clé API, consultez la page Utiliser des clés API.

  4. L'équipe Customer Care ajoute à la liste d'autorisation l'accès à l'API des clients (en appliquant les libellés de visibilité appropriés).

  5. L'équipe Customer Care ajoute à la liste d'autorisation le compte de service client pour l'accès au compte de service.

  6. Le client peut activer l'API Cloud Support en accédant à la page de l'API Cloud Support dans Google Cloud Console et en cliquant sur ACTIVER.

    Accéder à la page de l'API Cloud Support

Si vous souhaitez intégrer le compte de service :

  1. Le client provisionne un ou plusieurs comptes de service en suivant les instructions de la section Comprendre les comptes de service.

  2. Le client attribue le rôle Organization Viewer au compte de service situé dans l'onglet IAM de Cloud Console, ou tout autre rôle qui accorde l'autorisation resourcemanager.organizations.get.

    Vous pouvez également effectuer cette opération de manière automatisée :

      gcloud organizations add-iam-policy-binding
      organizations/ord-id
      --role roles/resourcemanager.organizationViewer
      --member service-account
     

  3. Le client ajoute un ou plusieurs de ces comptes de service en tant qu'utilisateurs de l'assistance via la page Paramètres > d'assistance de Cloud Console.

  4. Le client permet à son connecteur JIRA ou à d'autres applications d'accéder au compte de service en partageant des identifiants. Consultez la page Présentation de l'authentification pour connaître la procédure.

  5. Si le client dispose déjà d'un outil de gestion des identifiants, il est judicieux d'utiliser le même outil pour les comptes de service Google Cloud.

  6. Les applications du client effectuent des appels d'API réguliers (comme le ferait un utilisateur final), en utilisant les identifiants du compte de service au lieu des identifiants de l'utilisateur final.

Si vous souhaitez utiliser l'authentification OAuth 2.0, procédez comme suit :

  1. Si vous ne vous êtes pas encore authentifié auprès de Google à l'aide de OAuth2, configurez-le en exécutant la commande
    . Pour cela, suivez les instructions d'accès à API OAuth 2.0. Portez une attention particulière à la section sur l'autorisation incrémentielle.
  2. Assurez-vous que les deux champs d'application suivants sont ajoutés aux ID clients OAuth2 utilisés par votre application :
    • Pour l'accès général à Google Cloud : https://www.googleapis.com/auth/cloud-platform ou https://www.googleapis.com/auth/cloud-platform.read-only
    • Pour obtenir ou créer des demandes d'assistance et d'autres données d'assistance, procédez comme suit : https://www.googleapis.com/auth/cloudsupport

Récupérer la définition de l'API

La définition de l'API est diffusée en tant que document de découverte Google Cloud.

Voici un exemple : Remplacez <API_KEY> par une clé API générée à partir du projet client lors d'une étape précédente.

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

Client REST

API REST

Pour tous les points de terminaison répertoriés ci-dessous, la valeur de <host> doit être remplacée par cloudsupport.googleapis.com.

Comptes d'assistance

Répertoriez les comptes d'assistance auxquels un utilisateur a accès et gérez les détails de ce compte.

Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance (organisation)
IAM Lecteur d'organisation (organisation)
Assistance Développement, Production ou Prioritaire

ListSupportAccounts

Répertorie tous les comptes SupportAccount auxquels l'utilisateur actuellement authentifié a accès.

Format REST
GET <host>/v1/supportAccounts
Paramètres
Nom Type Description
filter string

Filtre de format libre à appliquer au résultat de recherche. Exemples d'utilisation :

filter="name=gcp-sa-1234"

filter="cloud_resource=organizations/my-org-1234"

page_size int64 Nombre maximal de comptes de support à renvoyer dans la réponse. Pour la plupart des utilisateurs, ce résultat n'est pas très pertinent, car le nombre de supportAccounts est très faible.
page_token string Jeton identifiant la page des résultats à renvoyer. Si cette option n'est pas spécifiée, la première page de résultats est renvoyée.
Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  http://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234?filter=cloud_resource:organizations/8675309

GetSupportAccount

Récupérer le compte d'assistance spécifié.

Format REST
GET <host>/v1/{name=supportAccounts/*}
Paramètres

Compte d'assistance spécifié dans l'URL de la requête.

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

Gestion des utilisateurs

Utilisé par l'administrateur pour ajouter ou supprimer des utilisateurs des rôles d'assistance par programmation.

Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance (organisation)
IAM Lecteur d'organisation (organisation)
Support Développement, Production ou Prioritaire

GetUserRole

Récupérer le support SupportRole de l'utilisateur donné. L'utilisateur à récupérer est déterminé à partir du champ email du message de requête ou des identifiants de l'utilisateur authentifié si le premier n'est pas spécifié.

Format REST
GET <host>/v1/{name=supportAccounts/*}:getUserRole
Paramètres
Nom Type Description
email string Adresse e-mail de l'utilisateur dont le rôle doit être récupéré.
Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:getUserRole?email=john@example.com

GetSupportRoles

Récupérer la liste de tous les objets SupporRole associés au compte d'assistance spécifié.

Format REST
GET <host>/v1/{name=supportAccounts/*}:getRoles
Paramètres

Compte d'assistance spécifié dans l'URL.

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

SetSupportRoles

Met à jour la liste des objets RoleRole associés au compte SupportAccount donné.

Format REST
POST <host>/v1/{name=supportAccounts/*}:setRoles
Paramètres
Nom Type Description
roles SupportRole[] Liste complète des rôles à associer au SupportAccount.
Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{
  "roles": [
    {
      "email": "john@example.com",
      "role": "SITE_RELIABILITY",
    },
    {
      "email": "alex@example.com",
      "role": "OPERATION",
    },
    {
      "email": "tiger@example.com",
      "role": "ROLE_UNSPECIFIED",
    },
],
  "etag": "ZrTGhhB"
}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:setRoles

Où l'attribut role peut accepter les valeurs suivantes :

Type de rôle Description
ROLE_UNSPECIFIED Supprimez le rôle d'assistance de cet utilisateur.
BASIC Le rôle d'assistance "Basic"
DEVELOPER Le rôle d'assistance "Développement"
OPERATION Le rôle d'assistance "Production"
SITE_RELIABILITY Le rôle d'assistance "Prioritaire"

La méthode SetSupportRoles renvoie une instance de google.longrunning.Operation. Pour récupérer l'état de SetSupportRoles, vous devez interroger le point de terminaison GetOperation à l'aide de l'ID d'opération. L'ID d'opération est constitué d'une combinaison de caractères alphanumériques et se présente au format suivant : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Demandes

Récupérez, créez et mettez à jour des demandes d'assistance.

Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance (organisation)
IAM Lecteur d'organisation (organisation)
Support Role Développement, Production ou Prioritaire

ListCases

Récupérez la liste des demandes d'assistance associées au SupportAccount.

Format REST
GET <host>/v1/{parent=supportAccounts/*}/cases
Paramètres
Nom Type Description
filter string Actuellement, n'accepte que les valeurs "OPEN" ou "CLOSED".
page_size int64 Nombre maximal de cas à récupérer avec chaque requête.
page_token string Jeton identifiant la page des résultats à renvoyer. Si cette option n'est pas spécifiée, la première page de résultats est renvoyée.
Exemple
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases

GetCase

Récupérer la demande d'assistance spécifiée.

Format REST
GET <host>/v1/{name=supportAccounts/*/cases/*}
Paramètres

Compte d'assistance et numéro de demande spécifiés dans l'URL de la requête.

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

CreateCase

Crée une demande et l'associe au SupportAccount donné.

Format REST
POST <host>/v1/{parent=supportAccounts/*}/cases
Paramètres
Nom Type Description
case Case

Un objet de la demande.

Exemple :


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

Exemple
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

UpdateCase

Mettre à jour une demande d'assistance. À l'heure actuelle, seuls les champs de priorité, d'objet et cc_address peuvent être mis à jour.

Format REST
PATCH <host>/v1/{case.name=supportAccounts/*/cases/*}
Paramètres
Nom Type Description
case Case La nouvelle demande d'assistance.
update_mask String[]

Liste des champs "Demande" à mettre à jour.

Exemple :

["case.priority"]

Exemple : Mettre à jour la demande
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ display_name: "My app is down", priority: 2, cc_addresses: ["james@example.com", "susan@example.com"]}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.cc_addresses,case.priority,case.display_name
Exemple : Fermer la demande
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X PATCH -d '{ state: "CLOSED" }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678?update_mask=case.state

EscalateCase

Redéfinir la priorité d'une demande d'assistance. La remontée d'une demande d'assistance déclenche le processus de gestion de la transmission du Customer Care. La capacité à faire remonter une demande d'assistance est limitée aux utilisateurs détenant les rôles Prioritaire et Production.

Format REST
POST <host>/v1/{name=supportAccounts/*/cases/*}:escalate
Paramètres
Nom Type Description
reason Enum

Raison de l'élévation de la demande.

Valeurs correctes :

  • REASON_UNSPECIFIED : le motif d'escalade est dans un état inconnu ou n'a pas été spécifié.
  • RESOLUTION_TIME : la résolution de la demande est trop longue.
  • TECHNICAL_EXPERTISE : l'agent d'assistance ne dispose pas de l'expertise requise pour résoudre le problème.
  • BUSINESS_IMPACT : le problème a un impact commercial important.
justification String Description du texte libre pour accompagner le champ reason et fournir plus de détails sur les raisons de l'escalade.
Exemple
curl v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ reason: "TECHNICAL_EXPERTISE", justification: "There is no technical expertise."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:escalate

GetIssueTaxonomy

Récupérer la taxonomie des catégories de problèmes et des composants de produit utilisés lors de la création d'une demande d'assistance.

Format REST
GET <host>/v1:getIssueTaxonomy
Paramètres
Nom Type Description
product_type string Doit toujours être défini sur "CLOUD_PLATFORM".
Exemple
curl -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1:getIssueTaxonomy

Pièces jointes

Récupérez, créez ou téléchargez les fichiers associés à une demande d'assistance. Pour joindre un fichier à une demande d'assistance, vous devez suivre les trois étapes suivantes :

  1. POST au point de terminaison :startAttachment pour générer un nouveau nom de rattachement.
  2. POST au point de terminaison Bytestream.Write pour importer les octets bruts du rattachement.
  3. POST à /attachments pour créer entièrement le rattachement et l'associer à une demande d'assistance. La création du rattachement inclut toutes les métadonnées de fichier, telles que le type MIME (par exemple, image/jpeg), la taille (en octets) et le nom de fichier (r2_d2.jpg).
Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance Cloud (organisation)
IAM Lecteur d'organisation (organisation)
Assistance Développement, Production ou Prioritaire.

ListAttachments

Récupère les métadonnées de tous les rattachements associés à la demande d'assistance donnée.

Format REST
GET <host>/v1/{parent=supportAccounts/*/cases/*}/attachments
Paramètres

Compte d'assistance et numéro de demande dans l'URL de la requête.

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

Vous pouvez télécharger les octets bruts du rattachement à l'aide du point de terminaison Bytestream.Read en émettant l'appel d'API REST suivant :

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X GET https://cloudsupport.googleapis.com/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?alt=media

StartAttachment

Démarrez le processus de création d'un rattachement. La méthode renvoie une chaîne représentant le nom de ressource du rattachement. Le nom de la ressource est utilisé dans les appels aux points de terminaison ByteStream.Write et CreateAttachment qui suivent.

Format REST
POST <host>/v1/{parent=supportAccounts/*/cases/*}:startAttachment
Paramètres

Compte d'assistance et numéro de demande dans l'URL de la requête.

Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d {} https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678:startAttachment
Bytestream.Write

Vous pouvez importer les octets bruts du rattachement en appelant Bytestream.Write comme suit :

curl -v -H 'Authorization: Bearer <TOKEN>' -H "Content-Type: application/json" -X POST -T {"r2-d2.jpg"} https://cloudsupport.googleapis.com/upload/v1/media/supportAccounts/gcp-sa-1234/cases/5678/attachments/9012?upload_type=media

CreateAttachment

Créez les métadonnées de rattachement et associez-le à la demande d'assistance spécifiée. Le nom du rattachement doit être généré par un appel à :startAttachment, et la taille maximale du rattachement est de 32 Mo.

Requête REST
POST <host>/v1/{name=supportAccounts/*/cases/*}/attachments
Paramètres
Nom Type Description
attachment Attachment

Objet de rattachement.

Exemple :


{
  name: "supportAccounts/gcp-sa-1234/cases/998877/attachments/55115511", \
  file_name: "giraffe.jpg", \
  mime_type: "image/jpeg", \
  size: 986712, // in bytes \
}
Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name: "supportAccounts/gcp-sa-1234/cases/5678/attachments/9012", mime_type: "image/jpeg", file_name: "R2-D2.jpg", size: 4458 }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/attachments

Commentaires

Créer ou répertorier des commentaires sur une demande d'assistance

Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance Cloud (organisation)
IAM Lecteur d'organisation (organisation)
Assistance Développement, Production ou Prioritaire

ListComments

Répertorier tous les commentaires associés à la demande d'assistance spécifiée.

REST
GET <host>/v1/{name=supportAccounts/*/cases/*}/comments
Paramètres

Compte d'assistance et numéro de demande dans l'URL de la requête.

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

CreateComment

Ajoute un nouveau commentaire à une demande.

Format REST
POST <host>/v1/{name=supportAccounts/*/cases/*}/comments
Paramètres
Nom Type Description
comment Commentaire

Objet de commentaire.

Exemple :


{
text: "This is my comment", \
}
           

Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ name:"supportAccounts/gcp-sa-1234/cases/5678",text:"I am commenting on this case."}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678/comments

Notifications

Répertorier toutes les notifications émises par Customer Care.

Rôles requis
Type Rôle
IAM Lecteur de compte d'assistance Cloud (organisation)
IAM Lecteur d'organisation (organisation)
Assistance Développement, Production ou Prioritaire

ListNotifications

Répertorier tous les incidents Google Cloud ouverts qui ont un impact actif sur les clients. La réponse inclut les problèmes affectant tous les produits, et non ceux spécifiques à l'utilisateur qui a appelé le point de terminaison.

Format REST
GET <host>/v1/{parent=supportAccounts/*}/notifications
Paramètres
Nom Type Description
page_size int32 Nombre maximal de notifications à renvoyer dans la réponse.
page_token string Jeton permettant de récupérer la page de résultats suivante. Le point de terminaison ListNotifications n'est actuellement pas compatible avec la pagination.
Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json'  https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/notifications

IAM

Points de terminaison pour interagir avec les services Identity and Access Management.

TestIamPermissions

Vérifiez si l'utilisateur actuellement authentifié dispose d'autorisations sur la ressource Customer Care donnée. Seuls les comptes d'assistance, les demandes, les opérations et les commentaires sont considérés comme des ressources valides Customer Care.

Par exemple, pour vérifier si l'utilisateur a accès à la récupération des détails d'un compte d'assistance, le champ TestIamPermissionsRequest doit être renseigné avec les valeurs suivantes :

resource: "supportAccounts/{support_account_id}"
permission: "cloudsupport.accounts.get"
Format REST
POST <host>/v1/{resource=**}:testIamPermissions
Paramètres
Nom Type Description
permissions string[]

Liste des autorisations à tester.

Exemple :

`["cloudsupport.comments.list", "cloudsupport.cases.list"]`

Exemple
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -X POST -d '{permissions: "cloudsupport.accounts.get"}' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234:testIamPermissions

Opérations

Points de terminaison pour récupérer l'état des opérations de longue durée.

GetOperation

Récupérer l'état d'une opération existante.

Format REST
GET <host>/v1/operations/{name=supportAccounts/*/operations/*}
Paramètres

Identifiant de compte de service et identifiant d'opération spécifiés dans l'URL de la requête.

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

Générer des bibliothèques clientes

Clonez le générateur de clients des API Google :

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

Assurez-vous que Python 2.7 est installé :

sudo apt-get install python

Assurez-vous que PIP est installé :

sudo apt-get install python-pip

Installez les dépendances :

pip install google-apis-client-generator

Générez des bibliothèques clientes :

Cette commande génère un ou deux avertissements commençant par WARNING:root:object without properties. Vous pouvez les ignorer. La bibliothèque cliente sera toujours générée.

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

Utiliser l'API

Avant de commencer

  • Ajoutez une dépendance sur la bibliothèque cliente des API Java.
  • Ajoutez une dépendance au code généré à l'étape ci-dessus.
  • Assurez-vous que votre code est construit correctement.

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