Guide de l'utilisateur de l'API Cloud Support version 2

Présentation

Cette page explique comment utiliser la version 2 de l'API cloudsupport.googleapis.com, en particulier le point de terminaison v2.

Vous pouvez intégrer l'API Cloud Support pour utiliser Cloud Customer Care avec le système de gestion de la relation client (CRM) de votre organisation. L'API Cloud Support permet aux utilisateurs d'effectuer diverses tâches d'assistance directement dans le CRM, par exemple:

• Créer et gérer des demandes d'assistance
• Répertorier, créer et télécharger des pièces jointes associées aux demandes d'assistance
• Répertorier et créer des commentaires dans les demandes

Les sections suivantes présentent les étapes à suivre pour les premiers pas, ainsi que les concepts clés entourant les différents éléments liés à l'API Support.

Getting Started

Cette section détaille le processus général pour commencer à utiliser l'API Cloud Support.

1. Pour activer l'API Cloud Support, accédez à la page API Cloud Support dans la console Google Cloud, puis cliquez sur ACTIVER.

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

2. Provisionnez un ou plusieurs comptes de service en suivant les instructions de la section Comprendre les comptes de service.

   Si vous disposez déjà d'un outil de gestion des identifiants, il est logique d'utiliser le même outil pour les comptes de service Google Cloud.

3. Attribuez au compte de service le rôle Organization Viewer dans l'onglet IAM de la console Google Cloud 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/ORG_ID \
     --role roles/resourcemanager.organizationViewer \
     --member SERVICE_ACCOUNT

Remarque :Pour trouver la valeur correcte pour "ORG_ID", cliquez ici.

1. Attribuez au compte de service le rôle "Éditeur de l'assistance technique" ou "Lecteur de l'assistance technique". Vous pouvez le faire par programmation:

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

2. Si vous utilisez des intégrations tierces telles que JIRA, autorisez l'application tierce à accéder au compte de service en partageant les identifiants. Pour connaître la procédure à suivre, consultez Présentation de l'authentification.

3. 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 du protocole OAuth2, configurez-le en suivant les guides de la page OAuth 2.0 pour accéder aux API Google. 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

Contrôle des accès et rôles IAM

L'assistance Premium utilise les rôles IAM suivants pour contrôler l'accès aux demandes. Pour en savoir plus, consultez la documentation sur le contrôle des accès.

Rôle	Autorisations
Tech Support Viewer	cloudsupport.techCases.get cloudsupport.techCases.list cloudsupport.techCaseAttachments.list cloudsupport.techCaseAttachments.download cloudsupport.techCaseComments.list cloudsupport.techCaseUpdates.list
Tech Support Editor	Autorisations de Lecteur de l'assistance technique cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseComments.create

Remarque :Vous pouvez également créer des rôles personnalisés avec ces autorisations afin d'accorder l'accès aux points de terminaison de l'API ci-dessous.

Générer des bibliothèques clientes localement

La définition de l'API est utilisée comme document de découverte Google Cloud. Pour en savoir plus, consultez le service de découverte des API Google.

1. Exécutez la commande ci-dessous pour générer le fichier de définition. curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2' > /tmp/cloudsupport.v2.json

2. Ensuite, clonez le générateur de clients d'API Google : cd /tmp/; git clone https://github.com/google/apis-client-generator.git;

3. Assurez-vous que Python est installé : sudo apt-get install python

4. Assurez-vous que PIP est installé : sudo apt-get install python-pip

5. Installez les dépendances : pip install google-apis-client-generator

6. Générer 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 quand même générée../generate.sh --input=/tmp/cloudsupport.v2.json --output_dir=/tmp/cloudsupport_generated --language=java

Utiliser l'API Cloud Support via les bibliothèques clientes (Python)

Dans cet exemple, les utilisateurs peuvent utiliser les bibliothèques clientes en Python, avec seulement quelques lignes de code. Vous pouvez ainsi l'intégrer facilement à divers produits Google Cloud comme App Engine ou Compute Engine.

Lorsque vous employez cette méthode, l'API tente d'utiliser les identifiants par défaut pour l'environnement dans lequel le code est exécuté (assurez-vous que le compte de service utilisé dispose des autorisations appropriées mentionnées dans la section "Premiers pas").

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

Utiliser l'API Cloud Support via cURL

Une fois gcloud CLI installée, il est simple d'appeler l'API Support et de transmettre les identifiants appropriés pour l'authentification. L'exemple ci-dessous montre comment procéder pour un appel d'API qui répertorie les cas disponibles dans l'organisation parente.

Remarque :L'acteur associé au jeton dépend du compte configuré dans gcloud. Vous pouvez spécifier gcloud de vous authentifier à l'aide du compte de service configuré dans la section "Premiers pas".

Authentification avec un compte de service

Étape 1: Authentification

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

Étape 2: Envoyez une requête

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

S'authentifier à l'aide des identifiants par défaut de l'application

Étape 1: Authentification

gcloud auth application-default login

Étape 2: Envoyez une requête

REMARQUE: Un en-tête (x-goog-user-project) supplémentaire est requis lors de l'appel de l'API Cloud Support à l'aide des identifiants par défaut de l'application.

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

Concepts clés

Pour utiliser efficacement l'API Cloud Support, il est important de connaître certains concepts clés. Nous allons examiner certains de ces concepts clés ci-dessous.

Demandes

L'objet Demande est l'entité contenant les détails d'une demande d'assistance spécifique, qui sont gérés par notre équipe d'assistance. Il contient des champs tels que l'horodatage de la création, la priorité, la classification et la description de la demande d'assistance. Chaque demande d'assistance est associée à des commentaires et à des pièces jointes qui sont ajoutés tout au long de la durée de vie de la demande.

Classification des cas

La classification des demandes identifie le sujet faisant l'objet de la demande d'assistance. En général, il contient un produit spécifique, tel que "Cloud Storage" ou "Compute Engine", ainsi qu'un type de problème général, tel que "Autorisations" ou "Latence".

Pour la version 2, l'objet "Classification de cas" possède un identifiant unique id pour la classification complète, ainsi qu'une description lisible par displayName. Il s'agit de l'une des principales modifications de la version v2alpha.

Vous devez indiquer un ID de classification du dossier valide lorsque vous créez une demande d'assistance. Il est important de disposer d'une classification précise, car elle permet d'acheminer le cas à un spécialiste.

Commentaires sur la demande

Les commentaires de la demande sont la principale méthode utilisée par l'équipe d'assistance Google pour communiquer des informations sur une demande d'assistance. Lorsque l'utilisateur répond à l'assistance Google, ses réponses apparaissent également sous la forme de commentaires sur la demande.

Pièces jointes pour le boîtier

Les pièces jointes aux demandes contiennent des informations sur des fichiers importés dans la demande d'assistance (de l'utilisateur ou de l'assistance Google). Les pièces jointes peuvent être importées en même temps dans Cloud Console en tant que commentaires lors de l'utilisation de l'interface utilisateur. Cependant, elles sont associées au niveau de la "case" et non "au niveau du commentaire".

Objet acteur

L'objet acteur spécifie une entité qui a effectué une action donnée. Par exemple, un acteur peut être l'utilisateur qui a publié un commentaire sur une demande d'assistance, l'utilisateur qui a importé une pièce jointe ou le compte de service qui a créé la demande d'assistance (qui, dans le contexte de l'API Support, est l'adresse e-mail du compte de service).

Structure des ressources du cas

Dans la version 2 de l'API Cloud Support, les demandes d'assistance peuvent être parents de organisations ou de projets Google Cloud. L'identifiant "parent" fait référence aux deux chemins avant "/cases/".

Les organisations sont identifiées par un numéro. Le nom d'une demande parent d'une organisation se présente donc comme suit:

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

Les projets ont deux identifiants uniques, un ID et un nombre. Dès lors, un cas parent d'un projet peut être identifié avec:

projects/PROJECT_ID/cases/CASE_NUMBER

projects/PROJECT_NUMBER/cases/CASE_NUMBER

L'utilisateur peut implémenter l'un de ces identifiants lors de l'appel de l'API. Toutefois, l'API ne renverra que les réponses à l'aide du numéro de projet.

Remarque :Chaque cas aura un parent basé sur l'organisation ou un projet. Si une demande est associée via un projet, elle n'est pas accessible via l'identifiant de ressource de l'organisation, et inversement.

Les autorisations IAM sont héritées en fonction de l'ascendance d'une ressource. Par conséquent, les projets héritent des autorisations de l'organisation à laquelle ils appartiennent. Pour en savoir plus, consultez la section Hiérarchie des ressources.