Essayez l'API

Les développeurs peuvent consulter la documentation de référence SmartDocs de l'API, mais ils peuvent également utiliser le panneau Essayer cette API pour interagir avec votre API sans quitter la documentation. Les développeurs peuvent envoyer des requêtes à l'API et consulter les réponses depuis votre portail. En leur permettant d'essayer l'API sur votre portail, vous aidez vos utilisateurs à comprendre ce qu’ils doivent faire pour que leur propre code fonctionne avec votre API.

Si l'API nécessite une clé API ou une authentification, vous devez configurer votre portail afin que vos utilisateurs puissent interagir avec l'API. Cette page décrit les exigences à respecter et la configuration à réaliser pour que les développeurs puissent utiliser la fonction Essayer cette API. Pour chaque tâche, le ou les rôles Identity and Access Management minimaux requis pour l'exécution sont fournis. Pour en savoir plus sur les autorisations IAM, consultez les pages suivantes :

Prerequisites

  • Vous devez avoir déployé le backend de l'API.
  • Si votre API nécessite une clé API, votre document OpenAPI doit être configuré comme décrit dans la section Restreindre l'accès à l'API avec des clés API.
  • Si votre API nécessite une authentification, votre document OpenAPI doit être configuré avec la méthode d'authentification choisie. Consultez la page Choisir une méthode d'authentification.

  • Votre API doit être accessible via DNS.

    • Si vous avez déployé votre API dans l'environnement flexible App Engine, une entrée DNS avec un nom au format YOUR_PROJECT_ID.appspot.com est créée automatiquement. Dans l'exemple précédent, YOUR_PROJECT_ID correspond à l'ID du projet Google Cloud sur lequel vous avez déployé votre API. Cela signifie que vous pouvez tester votre API sur votre portail sans configuration supplémentaire.
    • Pour d'autres backends (tels que Compute Engine ou GKE), si votre API n'est pas configurée pour utiliser un nom de domaine personnalisé (par exemple, myapi.mycompany.com), vous devez la configurer pour qu'elle utilise le domaine cloud.goog.

Configurer les paramètres de l'explorateur d'API

Si votre API nécessite une clé API et/ou une authentification Firebase ou Auth0, vous devez configurer ces paramètres pour que vos utilisateurs puissent essayer votre API. Cette section explique comment configurer une clé API et les paramètres d'authentification.

Configurer une clé API

Pour configurer une clé API sur votre portail, procédez comme suit :

  1. Dans Google Cloud Console, accédez à API et services > Identifiants.

    Accéder à la page "Identifiants"

  2. Dans la liste déroulante Projet en haut de la fenêtre Google Cloud Console, sélectionnez le projet Google Cloud dans lequel vous avez créé l'API.

    • Pour utiliser une clé API existante, procédez comme suit :

      1. Cliquez sur Modifier la clé API() à côté de la clé API que vous voulez utiliser.
      2. À droite de la clé API, cliquez sur Copier () pour copier la clé API dans le presse-papiers.
      3. Cliquez sur Cancel (Annuler).

    • Pour créer une clé API, procédez comme suit :

      1. Cliquez sur Créer des identifiants, puis sélectionnez Clé API.
      2. Copiez la clé dans le presse-papier.
      3. Cliquez sur Fermer.

  3. Revenez vers votre portail.

  4. Cliquez sur Paramètres ().

  5. Cliquez sur l'onglet API et sélectionnez votre API dans la liste déroulante.

  6. Dans la section Paramètres de l'explorateur d'API, collez la clé API dans le champ Clé API Google.

  7. Cliquez sur Save (Enregistrer).

Configurer Firebase

Pour configurer Firebase, procédez comme suit :

  1. Ouvrez la console Firebase.

    • Si vous n'avez pas de projet Firebase existant, procédez comme suit :

      1. Cliquez sur Ajouter un projet et sélectionnez le nom du projet Google Cloud dans lequel se trouve votre API.
      2. Sur la carte Authentification, cliquez sur Démarrer.
      3. Cliquez sur l'onglet Méthode de connexion.
      4. Dans la section Fournisseurs de connexion, activez les fournisseurs que vous souhaitez utiliser.
      5. Dans la section Domaines autorisés, cliquez sur Ajouter un domaine et ajoutez le nom de domaine de votre portail (par exemple, endpointsportal.example-api.example.com).
      6. Cliquez sur Configuration Web. L'extrait de code personnalisé s'affiche. Laissez la console Firebase ouverte, car vous aurez besoin d'informations provenant de cet extrait de code dans les étapes suivantes.

    • Si vous avez un projet Firebase existant, procédez comme suit :

      1. Accédez à Développer > Authentification.
      2. Cliquez sur l'onglet Méthode de connexion.
      3. Dans la section Domaines autorisés, cliquez sur Ajouter un domaine et ajoutez le nom de domaine de votre portail (par exemple, endpointsportal.example-api.example.com).
      4. Cliquez sur Configuration Web. L'extrait de code personnalisé s'affiche. Laissez la console Firebase ouverte, car vous aurez besoin d'informations provenant de cet extrait de code dans les étapes suivantes.

  2. Ouvrez un nouvel onglet dans le navigateur et accédez au portail.

  3. Cliquez sur Paramètres .

  4. Sur la page Paramètres, cliquez sur l'onglet API et sélectionnez votre API dans la liste déroulante.

  5. Dans la section Paramètres de l’explorateur d’API, procédez comme suit :

    1. Copiez la valeur du champ apiKey depuis l'extrait de code Firebase, puis collez-la dans le champ Clé API Google.
    2. Copiez la valeur du champ authDomain depuis l'extrait de code Firebase, puis collez-la dans le champ Domaine d'authentification Firebase.

  6. Cliquez sur Save (Enregistrer).

Pour plus d'informations, consultez la documentation de Firebase.

Configurer Auth0

Appliquez la liste détaillée ci-dessous pour configurer Auth0 et votre portail :

Tâche 1 : assurez-vous qu'il existe une API Auth0 pour le service Cloud Endpoints.

Tâche 2 : configurez les paramètres de l'application Auth0.

Tâche 3 : configurez les paramètres Auth0 dans votre portail.

Tâche 1 : assurez-vous qu'il existe une API Auth0 pour le service Cloud Endpoints

  1. Connectez-vous au tableau de bord Auth0.

  2. Dans la barre de navigation de gauche, cliquez sur API. S'il existe une audience d'API sous la forme https://SERVICE_NAME, où SERVICE_NAME est le nom de votre service Endpoints, c'est que vous avez déjà créé une API. Passez à la tâche suivante pour configurer les paramètres de l'application Auth0.

    Sinon, créez une API en procédant comme suit :

    1. Cliquez sur + Créer une API.
    2. Saisissez un nom.

    3. Dans le champ Identifier, saisissez une URL au format suivant : https://SERVICE_NAME

      Remplacez SERVICE_NAME par le nom de votre service Endpoints. Si vous n'êtes pas sûr du nom du service, consultez la page Obtenir le nom du service et l'ID de configuration pour savoir comment identifier le nom de votre service Endpoints.

    4. Cliquez sur Créer.

Tâche 2 : configurez les paramètres de l'application Auth0

  1. Dans la barre de navigation de gauche du tableau de bord Auth0, cliquez sur Applications.
  2. Sélectionnez votre application Auth0, ou cliquez sur + Créer une application pour en créer une.

  3. Dans l'onglet Paramètres de votre application, faites défiler la liste, et ajoutez l'URL de redirection OAuth de votre portail dans le champ URL de rappel autorisées. L'URL de redirection OAuth de votre portail correspond à l'URL de votre portail suivie de /oauth/redirect (par exemple, https://endpointsportal.example-api.example.com/oauth/redirect).

    Le champ "URL de rappel autorisées" accepte plusieurs URL séparées par une virgule. Assurez-vous que l'URL que vous renseignez ne se termine pas par un caractère "/".

  4. Cliquez sur Enregistrer les modifications.

    Laissez l'onglet de navigateur Paramètres de l'application Auth0 ouvert, car vous aurez besoin d'informations provenant de cette page dans les étapes suivantes.

Tâche 3 : configurez les paramètres Auth0 dans votre portail

  1. Ouvrez un nouvel onglet dans le navigateur et accédez au portail.
  2. Cliquez sur Paramètres .
  3. Sur la page Paramètres, cliquez sur l'onglet API et sélectionnez votre API dans la liste déroulante.

  4. Dans la section Paramètres de l’explorateur d’API, procédez comme suit :

    1. Copiez la valeur du champ ID client depuis le tableau de bord Auth0 et collez-la dans le champ ID client Auth0.
    2. Copiez la valeur du champ Domaine depuis le tableau de bord Auth0 et collez-la dans le champ Domaine Auth0.

  5. Cliquez sur Save (Enregistrer).

Pour en savoir plus sur la configuration de l'application Auth0, consultez la page Présentation du tableau de bord Auth0 dans la documentation Auth0.