Présentation

Une spécification OpenAPI utilise un format standard pour décrire une API RESTful. Rédigées au format JSON ou YAML, les spécifications OpenAPI sont lisibles par machine, mais également faciles à lire et à comprendre pour les humains.

La spécification décrit les différents éléments d'une API, dont le chemin de base, les verbes et les chemins d'accès aux ressources, les opérations, les en-têtes, les paramètres de requête et les réponses. En outre, les spécifications OpenAPI sont couramment utilisées pour générer la documentation des API.

Dans cet atelier, vous allez examiner une spécification OpenAPI pour un service de backend de retail. Vous utiliserez ensuite cette spécification OpenAPI pour créer un proxy d'API qui permettra d'ajouter des fonctionnalités et des mesures de sécurité à l'API de backend.

Objectifs

Dans cet atelier, vous allez apprendre à effectuer les tâches suivantes :

• Explorer une spécification OpenAPI et comprendre ses différents composants
• Créer un proxy d'API à partir d'une spécification OpenAPI à l'aide de l'assistant de proxy
• Suivre un proxy d'API

Préparation

Pour chaque atelier, nous vous attribuons un nouveau projet Google Cloud et un nouvel ensemble de ressources pour une durée déterminée, sans frais.

1. Connectez-vous à Google Skills dans une fenêtre de navigation privée.

2. Vérifiez le temps imparti pour l'atelier (par exemple : 01:15:00) : vous devez pouvoir le terminer dans ce délai. Une fois l'atelier lancé, vous ne pourrez pas le mettre sur pause. Si nécessaire, vous pourrez le redémarrer, mais vous devrez tout reprendre depuis le début.

3. Lorsque vous êtes prêt, cliquez sur Démarrer l'atelier.

4. Notez vos identifiants pour l'atelier (Nom d'utilisateur et Mot de passe). Ils vous serviront à vous connecter à la console Google Cloud.

5. Cliquez sur Ouvrir la console Google.

6. Cliquez sur Utiliser un autre compte, puis copiez-collez les identifiants de cet atelier lorsque vous y êtes invité. Si vous utilisez d'autres identifiants, des messages d'erreur s'afficheront ou des frais seront facturés.

7. Acceptez les conditions d'utilisation et ignorez la page concernant les ressources de récupération des données.

Activer Google Cloud Shell

Google Cloud Shell est une machine virtuelle qui contient de nombreux outils pour les développeurs. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud.

Google Cloud Shell vous permet d'accéder à vos ressources Google Cloud grâce à une ligne de commande.

1. Dans la barre d'outils située en haut à droite dans la console Cloud, cliquez sur le bouton "Ouvrir Cloud Shell".

   

2. Cliquez sur Continuer.

Le provisionnement et la connexion à l'environnement prennent quelques instants. Une fois connecté, vous êtes en principe authentifié et le projet est défini sur votre ID_PROJET. Par exemple :

gcloud est l'outil de ligne de commande pour Google Cloud. Il est préinstallé sur Cloud Shell et permet la complétion par tabulation.

• Vous pouvez lister les noms des comptes actifs à l'aide de cette commande :

gcloud auth list

Résultat :

Credentialed accounts: - @.com (active)

Exemple de résultat :

Credentialed accounts: - google1623327_student@qwiklabs.net

• Vous pouvez lister les ID de projet à l'aide de cette commande :

gcloud config list project

Résultat :

[core] project =

Exemple de résultat :

[core] project = qwiklabs-gcp-44776a13dea667a6 Remarque : Pour consulter la documentation complète sur gcloud, accédez au guide de présentation de la gcloud CLI.

Tâche 1 : Examiner la spécification OpenAPI du service de backend

Dans cette tâche, vous allez explorer la spécification OpenAPI qui a été créée pour un service de backend que vous utiliserez dans vos proxys d'API.

Télécharger la spécification OpenAPI

• Dans Cloud Shell, téléchargez la spécification OpenAPI pour le service de backend à l'aide de la commande curl suivante :

  curl https://storage.googleapis.com/cloud-training/developing-apis/specs/retail-backend.yaml?$(date +%s) --output ~/retail-backend.yaml

  Avec cette commande curl, vous téléchargez un fichier nommé retail-backend.yaml et le stockez dans un fichier portant le même nom dans le répertoire d'accueil. Plus tard dans cet atelier, vous utiliserez cette même spécification pour créer un proxy d'API.

  Remarque : "?$(date +%s)" ajoute à l'URL un paramètre de requête représentant la date et l'heure actuelles sous forme de chaîne. Cette variable dynamique modifie l'URL et force curl à récupérer la dernière version d'un fichier, même si une version précédente est présente dans le cache.

Afficher la spécification OpenAPI dans l'éditeur Cloud Shell

1. Dans Cloud Shell, cliquez sur Ouvrir l'éditeur.

   

2. Dans l'éditeur, sélectionnez le fichier retail-backend.yaml.

   

Explorer les sections de la spécification

1. Examinez la spécification OpenAPI.

   Il s'agit de la spécification OpenAPI pour le service de backend qui sera utilisé dans de nombreux ateliers du cours. Voyons les sections qu'elle comporte.

   Le champ openapi spécifie la version de la spécification OpenAPI. Il s'agit ici d'OpenAPI version 3, comme l'indique le numéro de version en haut du fichier :

   openapi: "3.0.0"

   L'objet info fournit des métadonnées sur l'API. La version affichée est celle de la spécification "Retail Backend" :

   info: version: 1.0.0 title: Retail Backend description: Retail backend database used for Developing APIs course contact: name: Google Cloud (Apigee) email: apigee@example.org url: https://cloud.google.com/apigee license: name: MIT url: https://opensource.org/licenses/MIT

   Le tableau servers contient la liste des objets serveur qui spécifient les informations de connectivité pour les serveurs cibles. Cette spécification contient un seul service de backend, que votre proxy d'API appellera :

   servers: - url: "https://gcp-cs-training-01-test.apigee.net/training/db" description: Retail backend for Developing APIs course

   Le tableau tags ajoute des métadonnées aux tags utilisés dans les opérations, qui sont présentés ci-dessous. Les tags peuvent être partagés par plusieurs opérations et servir à fournir des descriptions détaillées ou des liens vers de la documentation externe.

   tags: - name: categories description: Product Categories - name: products description: Products - name: orders description: Orders - name: stores description: Stores

   L'objet paths contient les chemins relatifs vers les points de terminaison individuels et leurs opérations. L'un de ces chemins, /categories/{categoryId}, permet de définir une seule catégorie. L'opération get ci-dessous permet de récupérer une catégorie en fonction de l'ID. L'objet "get" affiche les paramètres et les réponses. Pour les opérations qui contiennent un corps de requête, comme PATCH /products/{productId}, le corps de la requête sera également spécifié.

   /categories/{categoryId}: get: summary: Get a specific category operationId: getCategoryById tags: - categories parameters: - name: categoryId in: path required: true description: category id schema: type: integer responses: '200': description: Selected category content: application/json: schema: $ref: "#/components/schemas/Category" '404': description: Category not found content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error"

   L'objet components contient des objets réutilisables dans différentes parties de la spécification OpenAPI. L'objet composant securitySchemes contient les définitions des différents types de schémas de sécurité utilisés par les opérations. Cette spécification définit un seul schéma d'authentification de base, qui est indiqué dans l'opération PATCH /products/{productId}. L'objet composant schemas contient les types de données d'entrée et de sortie. L'objet Category est ici renvoyé lorsque l'opération GET /categories/{categoryId} aboutit :

   components: securitySchemes: basicAuth: type: http description: basic auth scheme: basic schemas: Category: type: object description: product category required: - color - id - name properties: color: description: use this color for displaying this category type: string id: description: integer id (used for access) type: integer format: int32 minimum: 0 name: description: category name type: string

   N'hésitez pas à explorer la spécification ou à consulter la documentation sur les spécifications OpenAPI.

2. Pour en savoir sur cette spécification OpenAPI, utilisez le panneau Gemini Code Assist dans l'éditeur. Développez l'élément de contexte dans la section Prompts et vérifiez que le fichier retail-backend.yaml actuel est sélectionné.

3. Saisissez ce prompt :

   Explain the contents of this file.

4. Cliquez sur Envoyer ().

   Gemini génère une réponse qui décrit le contenu de la spécification OpenAPI du service de backend. Elle inclut un résumé général et reprend les principales sections définies afin d'expliquer leur objectif.

Télécharger la spécification OpenAPI sur votre ordinateur

1. Cliquez sur Ouvrir le terminal.

2. Sélectionnez le menu Plus () de Cloud Shell, puis cliquez sur Télécharger.

3. Saisissez retail-backend.yaml, puis sélectionnez Télécharger.

   Cela vous permet de télécharger le fichier sur votre ordinateur local.

Tâche 2 : Créer un proxy d'API à l'aide de la spécification OpenAPI

Dans cette tâche, vous allez créer un proxy d'API à l'aide de la spécification OpenAPI du service de backend.

Épingler la page de la console Apigee

1. Dans la console Google Cloud, accédez au menu de navigation (), puis recherchez Apigee dans la section Produits favoris.

   La page de la console Apigee s'ouvre.

2. Si Apigee n'apparaît pas, recherchez Apigee dans la barre de recherche en haut de la page et accédez au service Apigee.

3. Pour épingler Apigee dans la console, cliquez sur l'icône Favoris ().

   La page de la console Apigee figure désormais parmi vos produits favoris dans le menu de navigation.

Utiliser l'assistant pour créer un proxy

1. Dans le menu de navigation de gauche, sélectionnez Développement de proxys > Proxys d'API.

2. Pour démarrer l'assistant de proxy, sélectionnez + Créer.

3. Dans Proxy template (Modèle de proxy), sélectionnez OpenAPI spec template > Reverse proxy (Most common) (Modèle de spécification OpenAPI > Proxy inverse (le plus courant)).

4. Dans OpenAPI specs (Spécifications OpenAPI), cliquez sur Browse (Parcourir), sélectionnez le fichier retail-backend.yaml que vous avez téléchargé, puis cliquez sur Open (Ouvrir).

5. Cliquez sur Suivant.

6. Spécifiez les informations suivantes pour les détails du proxy :

   Propriété	Valeur
   Nom du proxy	retail-v1
   Chemin de base	/retail/v1
   Description	Mon API de retail

   La cible a été extraite du tableau servers de la spécification OpenAPI. Ne la modifiez pas.

   Remarque : Vérifiez que vous utilisez "/retail/v1" comme chemin de base, et non "/retail-v1".

7. Cliquez sur Suivant.

   Les opérations trouvées dans la spécification OpenAPI sont listées.

8. Dans "Flux", cliquez sur Sélectionner toutes les lignes dans la ligne d'en-tête.

   Tous les flux devraient maintenant être sélectionnés.

9. Cliquez sur Suivant.

10. Dans Environnements de déploiement, choisissez l'environnement eval, puis cliquez sur OK.

    Remarque : Laissez le champ "Compte de service" vide.

11. Cliquez sur Créer.

    Votre proxy sera généré et marqué comme prêt pour le déploiement.

La disponibilité de l'environnement d'exécution peut être retardée

Le provisionnement complet d'une organisation Apigee prend généralement 30 minutes ou plus. L'essentiel de ce temps est consacré au provisionnement du cluster d'exécution, de la base de données d'exécution et des services nécessaires pour exécuter vos proxys d'API. Lorsque vous créez une organisation Apigee pour le long terme, ce délai ne pose pas de problème. En revanche, vous ne souhaitez pas attendre une demi-heure avant de commencer chaque atelier.

Il peut arriver que l'organisation soit déjà entièrement provisionnée lorsque vous accédez à l'atelier. Parfois, le provisionnement de l'organisation Apigee ne commence qu'au moment où vous démarrez l'atelier.

Les opérations du plan de gestion de l'organisation sont disponibles quelques minutes après le début du processus de provisionnement. Au lieu d'attendre que l'environnement d'exécution soit entièrement provisionné, vous pouvez utiliser ces ateliers pour effectuer des opérations, comme modifier un proxy, avant que l'environnement d'exécution ne soit prêt. Si vous déployez un proxy dans un environnement avant que l'environnement d'exécution ne soit disponible, il ne pourra pas recevoir de trafic tant que le provisionnement de l'environnement d'exécution ne sera pas terminé.

Lorsque vous maintenez le pointeur sur l'icône État d'un proxy déployé, comme indiqué ci-dessous, vous pouvez constater qu'aucune instance n'indique d'état. Ceci est normal tant que l'environnement d'exécution de l'organisation Apigee n'a pas été entièrement provisionné.

Obtenir plus d'informations sur le déploiement de proxys Apigee

Pour en savoir plus sur le processus de déploiement de proxys d'API dans un environnement Apigee, vous pouvez utiliser Gemini Cloud Assist dans la console Google Cloud.

Ouvrir Gemini Cloud Assist

1. Pour ouvrir Gemini Cloud Assist, accédez à la console Google Cloud, puis cliquez sur Ouvrir ou fermer le chat Gemini Cloud Assist ().

2. Si vous y êtes invité dans le panneau Cloud Assist, cliquez sur Obtenir Gemini Cloud Assist.

3. Vous pouvez également afficher les API qui peuvent être activées (requises et recommandées).

4. Sélectionnez Activer Gemini Cloud Assist sans frais.

5. Cliquez sur Commencer à discuter.

Prompter Gemini

1. Saisissez ce prompt :

   In Apigee X, explain the deployment process of an API proxy to an Apigee environment.

2. Cliquez sur Envoyer ().

   Lisez la réponse générée par Gemini Cloud Assist.

3. Si vous le souhaitez, sélectionnez Afficher le contenu associé pour parcourir la documentation connexe.

Vérifier l'état du déploiement

L'état d'un proxy déployé et prêt à recevoir du trafic est indiqué en vert dans l'onglet "Présentation".

Lorsqu'un proxy est marqué comme déployé, mais que l'environnement d'exécution n'est pas encore disponible et que l'environnement n'est pas encore associé, une icône d'avertissement rouge peut s'afficher. Maintenez le pointeur sur l'icône État pour afficher l'état actuel.

Si le proxy est déployé et s'affiche en vert, il est prêt à gérer le trafic d'API. Si le proxy n'est pas déployé, car il n'y a pas de pod d'exécution, vous pouvez vérifier l'état du provisionnement.

Vérifier l'état du provisionnement

• Pour vérifier que l'instance d'exécution a été installée et que l'environnement d'évaluation a été associé, exécutez les commandes suivantes dans Cloud Shell :

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***"; Ces commandes utilisent l'API Apigee pour déterminer quand l'instance d'exécution a été créée et quand l'environnement d'évaluation a été associé à l'instance. Vous pouvez copier cette commande dans Cloud Assist si vous souhaitez que Gemini vous explique comment elle fonctionne.

  Lorsque le script renvoie ORG IS READY TO USE, vous pouvez passer aux étapes suivantes.

En attendant

• Web API Design: The Missing Link, un e-book sur les principes de conception des API
• Spécification OpenAPI

Tâche 3 : Explorer et suivre le proxy d'API

Démarrer l'outil de débogage

1. Sélectionnez l'onglet Développer.

   Cet onglet permet de modifier le proxy qui a été généré. Des flux conditionnels ont été créés pour chacune des opérations figurant dans la spécification OpenAPI. Ces flux apparaissent dans le point de terminaison du proxy, dans le menu de navigation à gauche. Lorsque vous cliquez sur un flux conditionnel, ses sections de requête et de réponse sont sélectionnées dans le volet de l'éditeur visuel. Le code default.xml affiché ci-dessous représente le code des flux de point de terminaison du proxy.

   

   Vous allez modifier un grand nombre de ces flux conditionnels dans les prochains ateliers.

2. Sélectionnez l'onglet Déboguer.

   L'outil de débogage permet de suivre les requêtes API gérées par le proxy.

3. Cliquez sur Démarrer une session de débogage.

4. Dans le volet Démarrer une session de débogage, sélectionnez eval dans le menu déroulant "Environnement".

   Le numéro de la révision déployée s'affiche également dans le menu déroulant.

5. Cliquez sur Démarrer.

   La session de débogage dure 10 minutes.

Tester le proxy d'API à l'aide du DNS privé

L'environnement d'évaluation de l'organisation Apigee peut être appelé à l'aide du nom d'hôte eval.example.com. L'entrée DNS pour ce nom d'hôte a été créée dans votre projet et elle est résolue en adresse IP de l'instance d'exécution Apigee. Cette entrée DNS a été créée dans une zone privée, ce qui signifie qu'elle n'est visible que sur le réseau interne.

Cloud Shell ne réside pas sur le réseau interne. Par conséquent, les commandes Cloud Shell ne peuvent pas résoudre cette entrée DNS. Une machine virtuelle (VM) de votre projet peut accéder au DNS de la zone privée. Une machine virtuelle nommée apigeex-test-vm a été créée automatiquement à cette fin. Vous pouvez effectuer des appels de proxy d'API à partir de cette machine.

La commande curl sera utilisée pour envoyer des requêtes API à un proxy d'API. L'option -k indique à curl d'ignorer la vérification du certificat TLS. Pour cet atelier, l'environnement d'exécution Apigee utilise un certificat autosigné. Pour un environnement de production, vous devez utiliser des certificats créés par une autorité de certification (CA) de confiance.

1. Dans Cloud Shell, ouvrez un nouvel onglet, puis une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   La première commande gcloud récupère la zone de la VM de test, tandis que la seconde ouvre la connexion SSH vers la VM.

2. Si vous y êtes invité, saisissez Y pour continuer.

   Pour chaque question posée dans Cloud Shell, cliquez sur Entrée ou Retour pour spécifier la valeur par défaut.

   L'identité avec laquelle vous êtes connecté est propriétaire du projet. La connexion SSH à cette machine est donc autorisée.

   Votre session Cloud Shell s'exécute désormais dans la VM.

Appeler le proxy d'API

1. Pour appeler le proxy hébergé dans l'environnement "eval", envoyez une requête à votre proxy d'API à l'aide de la commande suivante dans la session SSH Cloud Shell :

   curl -i -k -X GET https://eval.example.com/retail/v1/categories

   Une transaction associée à cette requête devrait apparaître dans le volet "Transactions" à gauche. Lorsqu'une transaction est sélectionnée, une trace de la requête et de la réponse vous est présentée via Apigee. Si vous avez correctement défini l'URL de votre backend et mis à jour l'URL d'envoi des requêtes, vous devriez voir un code d'état 200.

   Remarque : Le trafic des sessions de débogage Apigee est récupéré via une interrogation asynchrone des nouveaux appels d'API. Il se peut donc que vous constatiez un délai entre le moment où une requête API est terminée et le moment où elle apparaît dans l'outil de débogage.

2. Cliquez sur les boutons Retour et Suivant pour parcourir les étapes de la transaction.

   La requête était GET /retail/v1/categories. Elle a été envoyée au service de backend, qui a répondu par un tableau JSON contenant les catégories.

Félicitations !

Dans cet atelier, vous avez découvert les spécifications OpenAPI et exploré certaines de leurs fonctionnalités. Vous avez utilisé la spécification OpenAPI d'un service de backend de retail afin de créer un proxy d'API, puis vous avez suivi les appels effectués par le biais de ce proxy.

Terminer l'atelier

Une fois l'atelier terminé, cliquez sur Terminer l'atelier. Google Skills supprime les ressources que vous avez utilisées, puis efface le compte.

Si vous le souhaitez, vous pouvez noter l'atelier. Sélectionnez un nombre d'étoiles, saisissez un commentaire, puis cliquez sur Envoyer.

Voici à quoi correspond le nombre d'étoiles que vous pouvez attribuer à un atelier :

• 1 étoile = très insatisfait(e)
• 2 étoiles = insatisfait(e)
• 3 étoiles = ni insatisfait(e), ni satisfait(e)
• 4 étoiles = satisfait(e)
• 5 étoiles = très satisfait(e)

Si vous ne souhaitez pas donner votre avis, vous pouvez fermer la boîte de dialogue.

Pour soumettre des commentaires, suggestions ou corrections, veuillez accéder à l'onglet Assistance.

Copyright 2026 Google LLC Tous droits réservés. Google et le logo Google sont des marques de Google LLC. Tous les autres noms de société et de produit peuvent être des marques des sociétés auxquelles ils sont associés.