Synchroniser la documentation personnalisée via une API

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 :

  1. Synchronisez votre contenu personnalisé manuellement au moins une fois.
  2. Créez un compte de service avec l'autorisation et la clé appropriées.
  3. 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

  1. Dans Cloud Console, accédez à la page Comptes de service.

    Accéder à la page "Comptes de service"

  2. Cliquez sur Sélectionner un projet.

  3. Sélectionnez votre projet et cliquez sur Ouvrir.

  4. Cliquez sur  Créer un compte de service.

  5. Dans le champ Nom du compte de service, saisissez un nom à afficher pour votre compte de service.

  6. Cochez la case Indiquez une nouvelle clé privée.

  7. Dans le champ Type de clé, utilisez le type par défaut : JSON.

  8. Cliquez sur Enregistrer.

  9. Une boîte de dialogue affiche les informations de la clé. Fermez la boîte de dialogue pour continuer.

  10. Dans Cloud Console, accédez à la page Endpoints > Services du projet.

    Services Endpoints

  11. Cliquez sur le nom de l'API pour laquelle vous voulez synchroniser du contenu personnalisé afin de modifier ses autorisations d'accès.

  12. Si le panneau latéral Autorisations n'est pas ouvert, cliquez sur +Autorisations.

  13. 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.

  14. 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

  1. Saisissez la commande suivante pour afficher les ID de projet de vos projets Google Cloud :

    gcloud projects list
    
  2. 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]
    
  3. Assurez-vous que le SDK Cloud (gcloud) est autorisé à 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.

  4. 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.

  5. 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
    
  6. 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

  1. Installez les bibliothèques Python requises :
        pip install --upgrade google-auth
  2. 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 ci-dessous :
    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

Outil de ligne de commande

  1. Ouvrez Cloud Shell, ou ouvrez une fenêtre de terminal si le SDK Cloud est installé sur votre ordinateur Linux.
  2. 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]
  3. Obtenez un jeton d'autorisation à l'aide de votre compte de service :
    ACCESS_TOKEN=$(gcloud auth print-access-token)
  4. 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