Déployer une API gérée par Cloud Endpoints

Déployer une API gérée par 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 d'observabilité Google Cloud dans la console Google Cloud. 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 :

• Cloud Endpoints pour OpenAPI : tutoriels
• Cloud Endpoints pour gRPC : tutoriels
• Cloud Endpoints Frameworks : tutoriels

Avant de commencer

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

Démarrer Cloud Shell

1. Dans la console Google Cloud, 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 la console Google Cloud et affiche une invite de ligne de commande. L'initialisation de la session peut prendre quelques secondes.

   

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
   

Remarque :Si vous utilisez une machine Linux ou macOS et souhaitez suivre ce guide de démarrage rapide à l'aide de votre interface système locale, téléchargez la Google Cloud CLI et exécutez ces instructions de démarrage rapide avec votre interface de ligne de commande locale à la place de Cloud Shell.

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 à la console Google Cloud. 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
servicecontrol.googleapis.com	API Service Control
servicemanagement.googleapis.com	API Service Management

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

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.

Remarque : Si vous souhaitez nous donner votre avis sur ce tutoriel, n'hésitez pas à nous faire part de vos commentaires au bas de cette page. Ils nous sont utiles pour améliorer nos tutoriels.
Si vous rencontrez une erreur, rejoignez le groupe Google google-cloud-endpoints et faites-nous part de ce qui n'a pas fonctionné. Ce groupe reçoit les réponses d'autres utilisateurs Endpoints et d'ingénieurs Google qui supervisent le groupe.

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 la console Google Cloud, 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
   

   Remarque :Ce script génère des requêtes dans une boucle et expire automatiquement au bout de cinq minutes. Pour arrêter le script plus tôt, saisissez Control+C dans Cloud Shell.

2. Dans la console Google Cloud, consultez les graphiques d'activité de votre API.

   Accédez à 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 Explorateur 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 Control+C.

Ajouter un quota à l'API

Bêta

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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 la console Google Cloud, 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 Control+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 sur cette page soient facturées sur votre compte Google Cloud, procédez comme suit :

Vous pouvez supprimer votre projet Google Cloud. Cette démarche interrompra la facturation de toutes les ressources utilisées dans le projet.

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :
• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Étape suivante

• Pour obtenir une présentation d'Endpoints :

  • À propos de Cloud Endpoints
  • Endpoints : présentation de l'architecture

• Pour en savoir plus sur les différents frameworks d'API acceptés par Endpoints :

  • Spécification OpenAPI
  • Endpoints pour les API gRPC
  • À propos d'Endpoints Frameworks

• Pour savoir comment configurer et déployer un exemple d'API, choisissez un tutoriel pour l'un des frameworks d'API :

  • Cloud Endpoints pour OpenAPI : Tutoriels
  • Cloud Endpoints pour gRPC : Tutoriels
  • Endpoints Frameworks : tutoriels