Guide de l'utilisateur de l'API Cloud Support V2

Présentation

Cette page explique comment démarrer avec la version 2 de l'API cloudsupport.googleapis.com, en particulier le point de terminaison v2beta.

Vous pouvez intégrer l'API Cloud Support à 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, parmi lesquelles:

  • 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 expliquent comment se lancer, et comment explorer les concepts clés concernant les différents éléments liés à l'API Support.

Getting Started

Cette section décrit en détail la procédure générale à suivre pour commencer à utiliser l'API Cloud Support.

  1. Activez 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

  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 judicieux 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 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

  1. Attribuez au compte de service le rôle d'éditeur de l'assistance technique ou de 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 correspondants. 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 n'utilisez pas encore OAuth2 avec Google, configurez-le en suivant les guides de 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 d'utilisateur du service d'assistance technique
cloudsupport.techCases.create
cloudsupport.techCases.update
cloudsupport.techCases.escalate
cloudsupport.techCases.close
cloudsupport.techCases.create
cloudsupport.techCaseComments

Générer des bibliothèques clientes localement

La définition de l'API est diffusée en tant que document de découverte Google Cloud. Pour plus d'informations, consultez le Service de découverte des API Google.

  1. Générez le fichier de définition à l'aide de la commande ci-dessous.
curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2beta' > /tmp/cloudsupport.v2beta.json
  1. Ensuite, clonez le générateur de clients des API Google :
cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
  1. Assurez-vous d'avoir installé Python:
sudo apt-get install python
  1. Assurez-vous que le PIP est installé:
sudo apt-get install python-pip
  1. Installez les dépendances :
pip install google-apis-client-generator
  1. 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.v2beta.json --output_dir=/tmp/cloudsupport_generated --language=java

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

Dans cet exemple, les utilisateurs peuvent utiliser les bibliothèques clientes en Python, en seulement quelques lignes de code. Ce service facilite l'intégration dans divers produits GCP tels qu'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 donc 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 = "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()

Utiliser l'API Cloud Support via la CLI

Lorsque Cloud CLI est installé, il est facile 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.

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

Concepts clés

Pour utiliser correctement l'API Cloud Support, il est important de maîtriser certains des concepts clés. Voici quelques-uns de ces concepts clés.

Demandes

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

Classification des cas

La classification de demandes identifie le sujet sur lequel porte la demande d'assistance. En général, il comporte un produit spécifique, tel que Cloud Storage ou Compute Engine, et un type de problème général, tel que les autorisations ou la latence.

Dans la version v2beta, l'objet de classification de la casse comporte un id (identifiant unique de la classification complète) et une displayName (description lisible). Il s'agit de l'une des principales modifications apportées à la version 2alpha.

Lorsque vous créez une demande d'assistance, vous devez obligatoirement indiquer un ID de classification du dossier valide. Il est important que la classification soit précise, car elle est utilisée pour acheminer le dossier vers un spécialiste.

Commentaires sur la demande

Les commentaires de demande constituent la principale méthode permettant à l'équipe d'assistance Google de communiquer des informations sur une demande d'assistance. Lorsque l'utilisateur répond à l'assistance Google, les réponses de l'utilisateur apparaissent également comme commentaires sur la demande.

Accessoires pour étuis

Les pièces jointes aux demandes contiennent des informations sur les fichiers importés dans la demande d'assistance (par l'utilisateur ou par l'assistance Google). Lorsque vous utilisez l'interface utilisateur, les pièces jointes peuvent être importées dans Cloud Console en même temps qu'un commentaire. Toutefois, elles sont associées à un niveau, et non à un niveau.

Objet d'un 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 (dans le contexte de l'API Support), 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 parentes par des organisations ou des projets Google Cloud. L'identifiant "parent" fait référence aux deux chemins antérieurs à /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 possèdent deux identifiants uniques, un identifiant et un numéro. Un ticket associé à un projet peut donc être identifié à l'aide de l'une des méthodes suivantes:

projects/PROJECT_ID/cases/CASE_NUMBER
projects/PROJECT_NUMBER/cases/CASE_NUMBER

L'utilisateur peut mettre en œuvre l'un ou l'autre de ces identifiants lors de l'appel de l'API, mais l'API ne renvoie des réponses qu'à l'aide du numéro de projet.

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