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

Présentation

Pour en savoir plus sur l'intérêt de l'API Cloud Support et son utilité, consultez la page Présentation de l'API Cloud Support. Cette page vous explique comment utiliser la version 2 de l'API Cloud Support. Une version v2beta est également disponible, mais il existe quelques différences entre les deux. Certaines modifications et fonctionnalités peuvent être disponibles dans la version 2beta avant la version 2, mais la version 2 de l'API convient probablement mieux à la plupart des cas d'utilisation.

Voyons maintenant comment configurer la version 2 de l'API.

Getting Started

Avant de pouvoir utiliser l'API Cloud Support, procédez comme suit:

Pour activer l'API Cloud Support, accédez à la page de l'API Cloud Support dans la console Google Cloud et cliquez sur ACTIVER.
Provisionnez un compte de service en suivant les instructions de la section Créer des comptes de service. Pour en savoir plus sur les comptes de service, consultez la page Présentation des comptes de service.
Utilisez l'onglet "IAM" de la console Google Cloud pour attribuer au compte de service le rôle Organization Viewer ou un autre rôle accordant l'autorisation resourcemanager.organizations.get.

Vous pouvez également exécuter la commande gcloud organizations add-iam-policy-binding :
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT
```
Pour savoir comment trouver la valeur correcte pour "ORG_ID", consultez Récupérer l'ID de votre organisation.
Attribuez au compte de service le rôle "Éditeur de l'assistance technique" ou "Lecteur de l'assistance technique". Pour ce faire, exécutez la commande suivante:
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/cloudsupport.techSupportEditor \\
--member SERVICE_ACCOUNT
```
Si vous utilisez des intégrations tierces telles que JIRA, autorisez l'application tierce à accéder au compte de service. Pour en savoir plus sur l'authentification, consultez Présentation de l'authentification.

Si vous souhaitez utiliser OAuth 2.0 pour l'authentification:

Si vous n'utilisez pas déjà OAuth2 pour l'authentification auprès de Google, configurez-le en suivant les instructions de la page OAuth 2.0 pour l'accès aux API Google. Portez une attention particulière à la section sur l'autorisation incrémentielle.
Assurez-vous que les deux champs d'application suivants sont ajoutés aux ID client 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 accéder à la récupération ou à la création de demandes d'assistance et d'autres données liées à l'assistance: https://www.googleapis.com/auth/cloudsupport

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

Customer Care utilise les rôles IAM suivants pour contrôler l'accès aux demandes. Vous pouvez les utiliser ou créer vos propres rôles personnalisés avec les autorisations de votre choix. Pour en savoir plus sur IAM, consultez la page Contrôle des accès avec IAM.

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 du Lecteur de l'assistance technique cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCases.create cloudsupport.techCaseComments.create

Choisir les bibliothèques à utiliser pour appeler l'API Cloud Support

Il existe trois chemins d'accès généraux pour appeler l'API.

Utilisez les bibliothèques clientes Cloud de l'API Cloud Support correspondant au langage que vous souhaitez utiliser. Ils sont disponibles dans une grande variété de langues, mais ils ne permettent pas d'importer ni de télécharger des pièces jointes. Pour en savoir plus sur ce type de bibliothèque, consultez la section Bibliothèques clientes Cloud.
Utilisez la bibliothèque d'API Google pour Python afin de créer un bouchon pour appeler l'API Cloud Support. Il s'agit de l'ancienne approche pour appeler l'API. Vous pouvez importer ou télécharger des pièces jointes avec ce fichier. Pour en savoir plus sur ce type de bibliothèque, consultez Bibliothèques clientes des API Google.
Utilisez cURL ou appelez directement l'API. Cette approche présente l'avantage d'être entièrement personnalisable, mais vous oblige à tout configurer vous-même.

Si vous n'avez pas besoin d'utiliser de pièces jointes, nous vous recommandons d'utiliser les bibliothèques clientes Cloud. Sinon, nous vous recommandons d'utiliser la bibliothèque d'API Google pour Python.

Utiliser les bibliothèques clientes Cloud

L'API Cloud Support dispose de bibliothèques clientes Cloud disponibles pour:

Pour commencer, il vous suffit d'accéder à sa page et de suivre les instructions.

Utiliser la bibliothèque d'API Google pour Python

Pour commencer à utiliser la bibliothèque d'API Google pour Python, procédez comme suit:

Installez le package de découverte Google avec pip.
```
pip install google-api-python-client
```

Créez un bouchon dans votre code.

import googleapiclient.discovery

api_version = "v2"
supportApiService = googleapiclient.discovery.build(
    serviceName="cloudsupport",
    version=api_version,
    discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
)

Appelez le point de terminaison qui vous intéresse. Vous trouverez ci-dessous des exemples illustrant cette approche pour chaque point de terminaison dans l'API Cloud Support. Par exemple, consultez cases.list.

Lorsque vous appelez l'API avec la bibliothèque d'API Google pour Python, celle-ci utilise les identifiants par défaut de l'environnement dans lequel votre programme s'exécute. Assurez-vous que le compte de service de cet environnement dispose des autorisations mentionnées dans la section Premiers pas.

Utiliser cURL

Il existe deux façons principales d'authentifier votre appel cURL. Vous pouvez utiliser un compte de service ou les identifiants par défaut de l'application. Pour en savoir plus sur les identifiants par défaut de l'application, consultez Fonctionnement des identifiants par défaut de l'application.

Assurer l'authentification via un compte de service

Authentifiez-vous à l'aide de Google Cloud CLI.

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

Envoyez la 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

Authentifiez-vous à l'aide de Google Cloud CLI.
```
gcloud auth application-default login
```

Envoyez la requête. Veillez à inclure un en-tête x-goog-user-project, qui est requis lorsque vous appelez l'API Cloud Support avec les 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