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 Les graphiques d'activité Endpoints et les journaux Google Cloud Observability 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 :
Avant de commencer
- Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
Démarrer Cloud Shell
Dans la console Google Cloud, assurez-vous que vous êtes dans le projet que vous souhaitez utiliser pour l'exemple d'API.
Ouvrez 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.
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
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
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 :
Dans Cloud Shell, dans le répertoire
endpoints-quickstart
, exécutez la commande suivante :cd scripts
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 génère
à 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 |
---|---|
endpoints.googleapis.com |
Google Cloud Endpoints |
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.comgcloud 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 de l'environnement flexible App Engine prend plusieurs minutes backend. 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
Grâce aux API déployées avec Endpoints, vous pouvez surveiller les métriques critiques des opérations dans la console Google Cloud, et d'obtenir des insights et l'utilisation avec Cloud Logging.
Dans Cloud Shell, exécutez le script de génération de trafic pour remplir les graphiques et les journaux :
./generate_traffic.sh
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.
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.
Ouvrez Cloud Shell.
Pour arrêter le script, saisissez
Control+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.
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.
Dans la console Google Cloud, accédez à la page Identifiants.
Cliquez sur Créer des identifiants, puis sur Clé API. Une nouvelle clé API s'affiche à l'écran.
Cliquez sur Copier.file_copy.
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
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
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
Après avoir exécuté le script pendant 5 à 10 secondes, saisissez
Control+C
pour l'arrêter.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.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- 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 :
Pour en savoir plus sur les différents frameworks d'API acceptés par Endpoints :
Pour savoir comment configurer et déployer un exemple d'API, choisissez un tutoriel pour l'un des frameworks d'API :