Synchroniser la documentation personnalisée via une API

OpenAPI | gRPC

Votre portail fournit une API spéciale pour la synchronisation du contenu personnalisé. Pour appeler cette API, vous devez réaliser les opérations suivantes :

Synchronisez votre contenu personnalisé manuellement au moins une fois.
Créez un compte de service avec l'autorisation et la clé appropriées.
Envoyez la requête HTTP de synchronisation de votre contenu.

Ce document fournit des instructions pour créer un compte de service ainsi que des exemples pour créer la requête via Python ou à l'aide de la ligne de commande.

Créer un compte de service autorisé

Pour utiliser une API afin de synchroniser votre contenu personnalisé, vous avez besoin d'un compte de service avec l'autorisation et la clé appropriées. Pour créer le compte de service, lui attribuer le rôle approprié et obtenir le fichier de clé requis, procédez comme suit :

Console

Créez un compte de service :
1. Dans Google Cloud Console, accédez à la page Comptes de service.
  
  Accéder à la page "Comptes de service"
2. Sélectionnez le projet pour lequel votre API a été configurée.
3. Cliquez sur Créer un compte de service.
4. Dans le champ Nom du compte de service, saisissez un nom. Google Cloud Console remplit le champ ID du compte de service en fonction de ce nom.
5. Facultatif : dans le champ Description du compte de service, saisissez une description du compte de service.
6. Cliquez sur Créer et continuer.
7. Cliquez sur OK pour terminer la création du compte de service.
  
  Ne fermez pas la fenêtre de votre navigateur. Vous en aurez besoin lors de la tâche suivante.
Téléchargez une clé JSON pour le compte de service que vous venez de créer :
1. Dans Google Cloud Console, cliquez sur l'adresse e-mail du compte de service que vous avez créé.
2. Cliquez sur Keys (Clés).
3. Cliquez sur Add key (Ajouter une clé), puis sur Create new key (Créer une clé).
4. Cliquez sur Créer. Un fichier de clé JSON est téléchargé sur votre ordinateur.
  
  Veillez à stocker le fichier de clé en toute sécurité, car il peut être utilisé pour s'authentifier en tant que compte de service. Vous pouvez déplacer et renommer ce fichier comme vous le souhaitez.
5. Cliquez sur Fermer.
Dans la console Google Cloud, accédez à la page Endpoints > Services de votre projet.

Services Endpoints
Cliquez sur le nom de l'API pour laquelle vous voulez synchroniser du contenu personnalisé afin de modifier ses autorisations d'accès.
Si le panneau latéral Autorisations n'est pas ouvert, cliquez sur +Autorisations.
Pour permettre au compte de service créé d'accéder à l'API, saisissez l'adresse e-mail du compte de service créé dans le champ Ajouter des membres.
Dans la liste déroulante Sélectionner un rôle, cliquez sur Service Management, puis sélectionnez le rôle Éditeur pour la configuration de service pour le compte de service.

Félicitations ! Vous avez créé le compte de service, téléchargé sa clé privée dans un fichier JSON et attribué le rôle approprié au compte de service.

gcloud

Saisissez la commande suivante pour afficher les ID de projet de vos projets Google Cloud :
```
gcloud projects list
```
Remplacez [YOUR_PROJECT_ID] dans la commande suivante pour définir le projet par défaut sur celui hébergeant l'API :
```
gcloud config set project [YOUR_PROJECT_ID]
```
Important : Vous devez créer le compte de service dans le projet dans lequel se trouve l'API.
Assurez-vous que Google Cloud CLI (gcloud) est autorisée à accéder à vos données et services sur Google Cloud:
```
gcloud auth login
```
Si vous avez plusieurs comptes, veillez à choisir le compte du projet Google Cloud dans lequel se trouve l'API. Si vous exécutez gcloud auth list, le compte que vous avez sélectionné s'affiche en tant que compte actif pour le projet.
Pour créer un compte de service, exécutez la commande suivante en remplaçant [SERVICE_ACCOUNT_NAME] par le nom que vous voulez utiliser et [Service Account to Sync Custom Content] par le nom à afficher :
```
gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
  --display-name "[Service Account to Sync Custom Content]"
```
Cette commande attribue au compte de service une adresse e-mail au format suivant :
```
[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
```
L'adresse e-mail est nécessaire pour les commandes suivantes.

Pour créer un fichier de clé de compte de service, remplacez [KEY_FILE] par le nom de fichier de votre clé :

gcloud iam service-accounts keys create ~/[KEY_FILE] \
  --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com

Pour permettre au compte de service d'accéder à l'API présentant le contenu personnalisé, exécutez la commande ci-dessous en remplaçant [YOUR_SERVICE_NAME] par le nom de l'API associée au contenu personnalisé :

gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
      --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
      --role roles/servicemanagement.configEditor

Envoyer une requête de synchronisation du contenu personnalisé

Les exemples suivants montrent comment envoyer une requête pour synchroniser le contenu personnalisé. Cette requête doit se présenter comme suit :

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Remplacez [YOUR_PROJECT_ID] et [YOUR_SERVICE_NAME] par les valeurs appropriées. Lorsque la requête aboutit, la réponse présente le code d'état HTTP 200.

Les exemples qui suivent montrent comment obtenir un jeton d'accès à partir des serveurs d'autorisation de Google et comment l'utiliser pour envoyer la requête au point de terminaison de votre portail à l'aide de Python ou de l'outil de ligne de commande :

Python

Installez les bibliothèques Python requises :
```
    pip install --upgrade google-auth
```

Pour créer un objet Credentials à partir des identifiants du compte de service et des champs d'application requis par le point de terminaison, puis demander la synchronisation du contenu, remplacez [YOUR_PROJECT_ID], /path/to/service.json et [YOUR_SERVICE_NAME] par les valeurs appropriées dans le script suivant:

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
SERVICE_ACCOUNT_FILE = "/path/to/service.json"
PROJECT_ID = "[YOUR_PROJECT_ID]"
SERVICE_NAME = "[YOUR_SERVICE_NAME]"

credentials = service_account.Credentials.from_service_account_file(
   SERVICE_ACCOUNT_FILE, scopes=SCOPES)
authed_session = AuthorizedSession(credentials)
endpoint =
"https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
result = authed_session.post(endpoint)
print result

Ligne de commande

Ouvrez Cloud Shell ou ouvrez une fenêtre de terminal si gcloud CLI est installé sur votre ordinateur Linux.
Pour vous authentifier auprès de votre compte de service, remplacez [KEY_FILE] ci-dessous par le chemin d'accès au fichier de clé du compte de service et exécutez la commande suivante :
```
gcloud auth activate-service-account --key-file [KEY_FILE]
```
Procurez-vous un jeton d'autorisation à l'aide de votre compte de service :
```
ACCESS_TOKEN=$(gcloud auth print-access-token)
```
Lorsque vous appelez l'API, transmettez la valeur du jeton en tant que jeton de support dans un en-tête d'autorisation. Remplacez [YOUR_PROJECT_ID] et [YOUR_SERVICE_NAME] par les valeurs appropriées :
```
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content
```