Guide de démarrage rapide de Cloud Endpoints

Ce guide de démarrage rapide vous accompagne dans le déploiement d'un exemple d'API, géré par Cloud Endpoints. L'exemple de code comprend :

  • une API REST que vous pouvez interroger pour trouver le nom d'un aéroport à partir de son code IATA à trois lettres ;
  • un script qui importe la configuration de l'API dans Endpoints ;
  • un script qui déploie un backend d'environnement flexible App Engine pour héberger l'exemple d'API.

Après avoir envoyé des requêtes à l'exemple d'API, vous pouvez afficher les graphiques d'activité Endpoints et les journaux de la suite d'opérations Google Cloud dans Google Cloud Console. Ces outils vous permettent de surveiller vos API et de mieux comprendre leur utilisation.

Ce guide de démarrage rapide utilise des scripts pour simplifier les étapes de configuration et vous permettre de visualiser rapidement les graphiques d'activité et les journaux. Pour savoir comment configurer et déployer un exemple d'API, choisissez un tutoriel pour l'un des frameworks d'API :

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Cloud.

    Accéder à la page de sélection du projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

Démarrer Cloud Shell

  1. Dans Cloud Console, assurez-vous que vous êtes dans le projet que vous souhaitez utiliser pour l'exemple d'API.

  2. Ouvrez Cloud Shell.

    Ouvrir Cloud Shell

    Une session Cloud Shell s'ouvre dans un nouveau cadre en bas de Cloud Console et affiche une invite de ligne de commande. L'initialisation de la session peut prendre quelques secondes.

    Session Cloud Shell

  3. Si vous utilisez un projet existant, vérifiez que vous disposez de la version la plus récente de tous les composants gcloud installés :

    gcloud components update
    

Obtenir l'exemple de code

  1. Dans Cloud Shell, exécutez la commande suivante pour obtenir l'exemple d'API et les scripts :

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. Accédez au répertoire qui contient l'exemple de code :

    cd endpoints-quickstart
    

Déployer la configuration Endpoints

Pour publier une API REST dans Endpoints, vous avez besoin d'un fichier de configuration OpenAPI qui décrit l'API. L'exemple d'API est fourni avec un fichier OpenAPI préconfiguré appelé openapi.yaml.

Cloud Endpoints utilise Service Management, un service d'infrastructure de Google Cloud, pour créer et gérer des API et des services. Pour gérer une API à l'aide de Cloud Endpoints, vous devez déployer le fichier de configuration OpenAPI de cette API sur Service Management.

Pour déployer la configuration Endpoints :

  1. Dans Cloud Shell, dans le répertoire endpoints-quickstart, exécutez la commande suivante :

    cd scripts
    
  2. Exécutez le script suivant qui est inclus dans l'exemple :

    ./deploy_api.sh
    

Cloud Endpoints utilise le champ host du fichier de configuration OpenAPI pour identifier le service. Le script deploy_api.sh définit l'ID de votre projet Google Cloud dans le nom configuré dans le champ host. Lorsque vous préparez un fichier de configuration OpenAPI pour votre propre service, vous devez effectuer cette opération manuellement.

Le script déploie ensuite la configuration OpenAPI dans Service Management avec la commande suivante : gcloud endpoints services deploy openapi.yaml

Lors de la création et de la configuration du service, Service Management fournit des informations à Cloud Console. Vous pouvez ignorer en toute sécurité les avertissements indiquant que les chemins dans openapi.yaml ne nécessitent pas de clé API. Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration et le nom du service :

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

Activer les services requis

Cloud Endpoints nécessite au minimum l'activation des services Google suivants :

Nom Titre
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Dans la plupart des cas, le déploiement de la configuration Endpoints active ces services obligatoires.

Utilisez la commande suivante pour vérifier que les services nécessaires sont activés :

gcloud services list

Si les services requis ne sont pas répertoriés, activez-les :

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Activez également votre service Endpoints :

gcloud services enable YOUR-PROJECT-ID.appspot.com

Pour en savoir plus sur les commandes gcloud, consultez la page Services gcloud.

Déployer le backend de l'API

Vous avez déployé la configuration OpenAPI sur Service Management, mais vous n'avez pas encore déployé le code permettant de diffuser le backend de l'API. Le script deploy_app.sh inclus dans l'exemple crée un environnement flexible App Engine pour héberger le backend de l'API, puis déploie l'API sur App Engine.

Pour déployer le backend de l'API :

  • Dans Cloud Shell, dans le répertoire endpoints-quickstart/scripts, exécutez le script suivant :

    ./deploy_app.sh
    

Le script exécute la commande suivante pour créer un environnement flexible App Engine dans la région us-central : gcloud app create --region="$REGION"

La création du backend de l'environnement flexible App Engine prend plusieurs minutes. Une fois l'application créée, le résultat est le suivant :

Success! The app is now created.

Le script exécute ensuite la commande gcloud app deploy pour déployer l'exemple d'API sur App Engine.

Le résultat est :

Deploying ../app/app_template.yaml...You are about to deploy the following services:

Le déploiement de l'API sur App Engine prend plusieurs minutes. Une fois l'API déployée sur App Engine, le résultat est le suivant :

Deployed service [default] to [https://example-project.appspot.com]

Envoyer des requêtes à l'API

  • Dans Cloud Shell, après avoir déployé l'exemple d'API, vous pouvez lui envoyer des requêtes en exécutant le script suivant :

    ./query_api.sh
    

Le script répercute la commande curl qu'il utilise pour envoyer une requête à l'API, puis affiche le résultat. Le résultat est :

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

L'API s'attend à recevoir un paramètre de requête, iataCode, défini sur un code d'aéroport IATA valide, comme SEA ou JFK. Exemple :

./query_api.sh JFK

Remarque : App Engine peut prendre quelques minutes pour répondre favorablement aux requêtes. Si vous envoyez une requête et que vous recevez une erreur HTTP 502, 503 ou une autre erreur de serveur, attendez une minute et envoyez-la de nouveau.

Vous venez de déployer et de tester une API dans Endpoints.

Suivre l'activité de l'API

Les API déployées avec Cloud Endpoints vous permettent de surveiller les métriques d'opérations critiques dans Cloud Console et d'obtenir des informations sur vos utilisateurs et leur utilisation à l'aide de Cloud Logging.

  1. Dans Cloud Shell, exécutez le script de génération de trafic pour remplir les graphiques et les journaux :

    ./generate_traffic.sh
    
  2. Dans Cloud Console, consultez les graphiques d'activité de votre API.

    Accéder à la page Services Endpoints

    Il peut s'écouler quelques instants avant que les requêtes ne soient reflétées dans les graphiques. En attendant que les données soient affichées :

    • Si le panneau latéral Autorisations n'est pas ouvert, cliquez sur +Autorisations. Le panneau "Autorisations" vous permet de contrôler qui a accès à votre API et le niveau d'accès.

    • Cliquez sur Historique de déploiement. Cet onglet affiche l'historique de vos déploiements d'API, y compris l'heure de déploiement et l'utilisateur qui a déployé la modification.

    • Cliquez sur Vue d'ensemble. Vous voyez le trafic entrant. Une fois le script de génération de trafic exécuté pendant une minute, vous voyez trois lignes sur le graphique Latence totale (50e, 95e et 98e centiles). Ces données fournissent une estimation des temps de réponse.

  3. Faites défiler l'écran jusqu'au tableau situé sous les graphiques et, sous Liens, cliquez sur Afficher les journaux pour GET/airportName. La page Visionneuse de journaux affiche les journaux des requêtes pour l'API.

  4. Ouvrez Cloud Shell.

    Ouvrir Cloud Shell

  5. Pour arrêter le script, saisissez Ctrl+C.

Ajouter un quota à l'API

Endpoints vous permet de définir des quotas vous permettant de contrôler la fréquence à laquelle les applications peuvent appeler votre API. Vous pouvez utiliser des quotas pour protéger votre API contre une utilisation excessive par un seul client.

  1. Dans Cloud Shell, déployez la configuration Endpoints présentant un quota.

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    

    Une fois que vous avez déployé une configuration Endpoints mise à jour, celle-ci devient active en une minute.

  2. Dans Cloud Console, accédez à la page Identifiants.

    Accéder à la page Identifiants

  3. Cliquez sur Créer des identifiants, puis sur Clé API. Une nouvelle clé API s'affiche à l'écran.

  4. Cliquez sur Copier..

  5. Saisissez la commande suivante dans Cloud Shell. Remplacez YOUR_API_KEY par la clé API que vous venez de créer.

    export API_KEY=YOUR_API_KEY
    
  6. Envoyez une demande à votre API en utilisant la clé API que vous venez de générer.

    ./query_api_with_key.sh $API_KEY
    

    Le résultat ressemble à ce qui suit :

    curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
    San Francisco International Airport
    
  7. L'API a désormais une limite de cinq requêtes par seconde. Exécutez la commande ci-dessous pour envoyer du trafic à l'API et déclencher la limite de quota.

    ./generate_traffic_with_key.sh $API_KEY
    
  8. Après avoir exécuté le script pendant 5 à 10 secondes, saisissez Ctrl-C pour l'arrêter.

  9. Envoyez une autre demande authentifiée à l'API.

    ./query_api_with_key.sh $API_KEY
    

    Le résultat ressemble à ce qui suit :

    {
     "code": 8,
     "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "internal"
      }
     ]
    }
    

Si vous obtenez une réponse différente, essayez d'exécuter le script generate_traffic_with_key.sh, puis réessayez.

Félicitations ! Vous avez réussi à limiter le débit de votre API. Vous pouvez également définir des limites variables en fonction des différentes méthodes d'API, créer plusieurs types de quotas et effectuer le suivi de l'utilisation des API par vos clients.

Pour plus d'informations, consultez la page À propos des quotas.

Créer un portail développeur pour l'API

Vous pouvez utiliser le portail Cloud Endpoints pour créer un portail des développeurs, c'est-à-dire un site Web qui vous permet d'interagir avec l'exemple d'API. Pour en savoir plus, consultez la page Présentation du portail Cloud Endpoints.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce guide démarrage rapide soient facturées sur votre compte Google Cloud :

Afin d'éviter que des frais ne vous soient facturés, vous pouvez supprimer votre projet Cloud. Cette démarche interrompra la facturation de toutes les ressources utilisées dans le projet.

  1. Dans Cloud Console, accédez à la page Gérer les ressources.

    Accéder à la page Gérer les ressources

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer .
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étape suivante