Concevoir et modifier des API

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Suivez les instructions de cette page pour utiliser Cloud Code afin de concevoir et de modifier des API.

Rôles supplémentaires nécessaires pour concevoir des API

Vous aurez besoin des rôles listés ci-dessous pour effectuer certaines étapes de conception et de test de l'API décrites sur cette page.

Tâche	Rôles requis
Concevoir des API à l'aide de Gemini Code Assist	Utilisateur Gemini pour Google Cloud Consommateur de Service Usage Consultez la section Attribuer des rôles IAM dans un projet Google Cloud pour Gemini Code Assist.
Utilisez le contexte d'entreprise de vos API existantes dans le hub d'API lorsque vous concevez des API.	Lecteur Cloud API Hub
Enregistrer vos nouvelles API dans le hub d'API	Éditeur ou administrateur de Cloud API Hub
Modifier les API du hub d'API dans Cloud Code	Éditeur ou administrateur de Cloud API Hub
Configurer et gérer un serveur fictif distant pour tester les API	Administrateur du registre d'artefacts Compte de service Cloud Build Administrateur Cloud Run Administrateur de Service Usage Consultez la documentation de référence sur les rôles de base et prédéfinis d'IAM.

Concevoir des API avec Gemini Code Assist

Preview — Gemini Code Assist

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.

Vous pouvez utiliser Cloud Code pour concevoir des API OpenAPI (OAS), version 3.0 à l'aide de Gemini Code Assist. Gemini Code Assist peut inclure le contexte de l'entreprise pour l'assistance par IA générative dans le processus de développement d'API. Le contexte d'entreprise utilise les API du hub d'API du projet pour fournir le contexte lors de la génération de nouvelles API. Il n'est disponible qu'avec les projets utilisant le hub d'API.

Consultez la page Utiliser Gemini Code Assist pour en savoir plus sur les étapes de configuration afin d'utiliser la fonctionnalité de cette section.

Remarque:Actuellement, Gemini Code Assist permet de concevoir des API combinant de nouveaux objets avec des objets existants (si le contexte d'entreprise est activé). Elle n'est pas compatible avec les scénarios de réutilisation d'objets sans création d'objets.

Générer une API

Pour générer une API, procédez comme suit :

1. Cliquez sur la baguette magique dans le menu de navigation de gauche pour utiliser Gemini Code Assist afin de créer une spécification d'API. Assurez-vous d'utiliser cette méthode pour créer des spécifications d'API au lieu du chat Gemini Code Assist, qui n'est pas compatible avec toutes les fonctionnalités lors de la création de spécifications d'API.
   
2. Saisissez une requête décrivant la nouvelle API dans la fenêtre de saisie Créer une spécification d'API.
   1. Si vous le souhaitez, sélectionnez un modèle de requête parmi les chips de modèle affichés. Un modèle de requête fournit un framework pour votre requête pour vous aider à démarrer.
   2. Saisissez une requête. Consultez la section Écrire des requêtes de spécifications d'API efficaces.
      
      
3. Gemini Code Assist génère une spécification OAS définissant l'API.
4. Consultez les spécifications :
   1. Cliquez sur Afficher le code pour examiner la spécification dans l'éditeur de code.
   2. Le panneau de rendu de l'API affiche les aperçus de l'API tels que visibles par les développeurs, y compris la description de l'API et d'autres documents.
   3. Si vous disposez déjà d'API sur votre hub d'API, ce contexte d'entreprise est utilisé pour réutiliser les objets sur cette génération OAS à partir des autres API, et est énuméré dans le panneau OUTPUT :
      
   4. Vos commentaires nous sont très utiles. Fournissez des commentaires sur la spécification générée en cliquant sur l'icône "J'aime" ou "Je n'aime pas" dans le panneau Swagger.
      
   5. Si vous souhaitez modifier les requêtes de prévisualisation et générer à nouveau la spécification, cliquez sur les flèches d'historique au-dessus des requêtes pour passer aux requêtes précédentes.
      
5. Testez la spécification. Une fois la nouvelle spécification terminée, vous pouvez la tester à l'aide d'un serveur de simulation. Consultez la page Tester votre API à l'aide d'un serveur fictif.
6. Cliquez sur Enregistrer pour enregistrer votre nouvelle API avec le nom de votre choix.
7. Pour créer un proxy d'API Apigee à partir de cette spécification, cliquez sur Créer un proxy d'API dans le menu Plus. Le processus de création crée un groupe de proxys. Le nouveau proxy doit s'afficher dans la liste du menu de gauche de vos proxys. Pour en savoir plus sur la création de proxys d'API à partir de Cloud Code, consultez le tutoriel de création de proxys d'API intégré à Cloud Code.
   

Écrire des requêtes de spécifications d'API efficaces

La précision et la pertinence d'une spécification d'API générée dépendent en grande partie de la requête fournie au modèle.

Voici des exemples de bonnes requêtes :

• Créez une API permettant aux clients de payer une commande à l'aide de divers modes de paiement, comme les cartes de crédit et de débit.
• Accepte les bons de commande pour les achats de grains de café spécialisés via une API.
• Nous sommes une entreprise spécialisée dans les pizzas, et nous souhaitons créer une solution de livraison de pizza personnalisée en ligne. Crée une API pour accepter les commandes de pizza.
• API pour l'entreprise de livraison de repas. Les clients peuvent commander des pizzas, des burgers ou des sandwichs dans une seule commande. Chacun de ces types d'aliments possède son propre schéma. Les pizzas possèdent des ingrédients et une taille. Les burgers possèdent des ingrédients et un type de steak. Les sandwichs comprennent des types de pains, de viande, des légumes, du fromage et des instructions personnalisées.

Ces exemples présentent des requêtes moins efficaces. Essayez d'éviter les requêtes structurées comme suit:

• Créer une API pour mon magasin Cette requête contient trop peu d'informations pour que le modèle puisse générer une spécification complète et précise.
• Créer une API de remboursement qui réutilise l'objet de commande. Vous n'avez pas besoin de spécifier les objets que Gemini Code Assist doit réutiliser lors de la création d'API. Gemini Code Assist détecte automatiquement les objets les mieux adaptés à réutiliser.

Enregistrer l'API avec API Hub

Une fois votre API examinée et finalisée, rendez-la disponible pour les développeurs en l'enregistrant avec le hub d'API :

1. Cliquez sur Enregistrer dans le hub d'API.
2. Suivez les instructions pour enregistrer l'API. Consultez la page Enregistrer des API pour en savoir plus sur l'enregistrement avec le hub d'API et sur les informations que vous devez fournir.

Mettre à jour les API de votre hub d'API à partir de Cloud Code

Vous pouvez enregistrer une nouvelle version des spécifications du hub d'API lorsque vous les modifiez à partir de Cloud Code.

Pour enregistrer la spécification en tant que nouvelle version, cliquez sur le bouton Plus d'options du panneau Swagger et cliquez sur Publier dans le hub d'API. Indiquez le nouvel ID de version de l'API. La nouvelle version doit s'afficher dans la liste des versions de cette API dans la liste API Hub de Cloud Code.

Utiliser le fichier de paramètres pour contrôler les comportements de Gemini Code Assist

Cette section explique comment gérer la disponibilité de Gemini Code Assist et la manière dont cette fonctionnalité est disponible à partir du fichier de paramètres.

Désactiver ou activer Gemini Code Assist

Une fois que vous avez configuré Apigee dans Cloud Code (consultez la section Configurer Apigee dans Cloud Code), vous pouvez ajouter cette ligne à votre fichier de paramètres pour désactiver temporairement tous les services Gemini Code Assist :

"cloudcode.apigee.gemini.enable": false

Supprimez la ligne ou définissez-la sur true (valeur par défaut) pour réactiver Gemini Code Assist.

Contrôler le contexte d'entreprise dans la génération de spécifications

La génération OAS peut inclure un schéma, des métadonnées et des définitions de sécurité issus des autres API de votre organisation. Le processus recherche des API similaires sur la base des noms d'objet et des descriptions de votre catalogue de hub d'API figurant dans le catalogue de hub d'API auquel vous êtes autorisé à accéder. L'état de déploiement des API du hub d'API n'est pas pris en compte.

Le contexte d'entreprise est activé par défaut.

Vous pouvez :

• Consultez le nombre de modifications incluses dans le contexte de l'entreprise, le cas échéant, dans le panneau Swagger :
• Consultez les modifications incluses dans le panneau Sortie :

Pour désactiver le contexte d'entreprise pour la génération de nouvelles spécifications, ajoutez ces lignes dans le fichier settings.json après "cloudcode.apigee.gemini.enable": true :

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }

Où :

• enabled indique si le contexte d'entreprise a été activé globalement. Définissez la valeur sur false pour désactiver le contexte d'entreprise.
• includeMetadata détermine si le contexte des métadonnées est inclus. Ce paramètre inclut ou exclut les métadonnées des autres API du hub d'API. includeMetadata ne s'applique que lorsque enabled est défini sur true.
• includeSchema détermine si le contexte du schéma est inclus. Ce paramètre inclut ou exclut les informations de schéma issues d'autres API dans le hub d'API. includeSchema ne s'applique que lorsque enabled est défini sur true.
• includeSecurity détermine si le contexte lié à la sécurité est inclus. Ce paramètre inclut ou exclut les informations de sécurité provenant d'autres API dans le hub d'API. includeSecurity ne s'applique que lorsque enabled est défini sur true.

Modifier les API

Pour utiliser Cloud Code afin de modifier des API existantes qui font partie de votre catalogue API Hub, suivez ces instructions. Les modifications que vous apportez dans Cloud Code peuvent être réenregistrées dans le hub d'API.

Ces instructions sont destinées aux utilisateurs qui n'utilisent pas le module complémentaire Gemini Code Assist pour Apigee. Pour en savoir plus sur les fonctionnalités supplémentaires disponibles avec Gemini Code Assist lors de la conception et de la modification des API, consultez la page Concevoir une API avec Gemini Code Assist.

Remarque : Pour le moment, toute modification apportée à l'API dans le hub d'API doit être enregistrée en tant que nouvelle version.

Pour modifier une spécification d'API, procédez comme suit:

1. Assurez-vous que le projet que vous avez sélectionné dans Cloud Code est le projet dont le catalogue du hub d'API contient l'API que vous souhaitez modifier.
2. Dans le menu de gauche, développez l'arborescence API Hub.
3. Sélectionnez l'API et la version à modifier dans la liste.
4. Modifiez la spécification dans le panneau de modification. Vous pouvez également afficher les opérations de l'API dans le panneau Swagger.
5. Vous pouvez éventuellement tester votre API à l'aide d'un serveur fictif.
6. Enregistrez les modifications en tant que nouvelle Version via le bouton En savoir plus dans le panneau Swagger, puis Publier sur le hub d'API. Confirmez ou mettez à jour la version lorsque vous y êtes invité, puis enregistrez les modifications dans le hub d'API. La nouvelle version doit s'afficher dans la liste des versions de cette API dans la liste API Hub de Cloud Code.

Tester votre API à l'aide d'un serveur fictif

Vous pouvez tester votre API à l'aide d'un serveur fictif local ou d'un serveur fictif distant basé sur Google Cloud. Le serveur local de simulation est installé et disponible par défaut, tandis que vous devez configurer et gérer les serveurs de simulation Google Cloud.

Utiliser le serveur fictif local

Le serveur local de simulation accepte les requêtes adressées à cette API et émule les réponses. Il n'est utilisable que pendant la session en cours par l'utilisateur actuel. Cependant, contrairement au serveur de simulation distant, il ne nécessite aucune configuration ni gestion, et n'entraîne aucuns frais.

Remarque : Le serveur local de simulation peut ne pas fonctionner correctement lors de l'utilisation de l'explorateur distant VS Code. En outre, il arrive que le serveur fictif local ne puisse pas démarrer. Dans ce cas, il ne sera pas disponible dans la liste déroulante.

Pour utiliser le serveur fictif local:

1. Sélectionnez le serveur de simulation local (serveur de développement) dans le menu déroulant Servers (Serveurs).
   
2. Ouvrez un chemin d'accès, puis cliquez sur Essayer.
   
3. Renseignez tous les paramètres de requête, puis cliquez sur Exécuter.
   
4. Vous pouvez également envoyer des requêtes à l'aide de curl depuis une requête. Utilisez l'adresse et le port du serveur dans le menu déroulant Serveurs.

Utiliser un serveur fictif distant

Un serveur fictif distant vous permet de créer une instance de serveur fictif persistante qui, contrairement au serveur fictif local, peut être partagée et utilisée par d'autres personnes de votre organisation pour tester la nouvelle API avant qu'elle ne soit en production. Les serveurs de simulation distants ne peuvent être utilisés qu'avec des API enregistrées dans le hub d'API.

À l'heure actuelle, il est possible de créer des serveurs distants de simulation dans Google Cloud. Les serveurs fictifs distants de Google Cloud ne sont pas automatiquement mis à jour pour les modifications que vous apportez à l'API après le déploiement du serveur fictif. Attendez donc d'avoir entièrement créé l'API avant d'ajouter le serveur fictif.

Le déploiement d'un serveur fictif distant Google Cloud crée un service Cloud Run. Il crée une image de conteneur pour le serveur de simulation à l'aide de Cloud Build et l'importe dans Cloud Artifact Registry dans votre projet Google. vous êtes responsable des coûts et de la maintenance qui en résultent après leur création. Vous êtes également responsable de leur suppression une fois qu'elles ne sont plus nécessaires. Consultez la page Qu'est-ce que Cloud Run ? Gérer les services et la documentation Artifact Registry.

Important : Une fois que vous avez créé un serveur distant Google Cloud de simulation, vous êtes responsable des coûts résultant de son utilisation, de sa gestion et de sa suppression une fois qu'il n'est plus nécessaire. Consultez la page https://cloud.google.com/run/pricing pour obtenir des informations sur la tarification, y compris sur les options de version gratuite.

Pour déployer un serveur de simulation distant, procédez comme suit :

1. Sélectionnez Déployer un serveur fictif (Google Cloud) dans le menu Plus.
2. Si votre API n'est pas déjà enregistrée dans le hub d'API, enregistrez-la lorsque vous y êtes invité.
3. Spécifiez les détails du serveur de simulation distant : ID du projet, Nom du serveur et Région, puis cliquez sur Créer pour créer le serveur distant de simulation.
   Important : Ne créez pas plusieurs serveurs fictifs distants portant le même nom, même si l'interface utilisateur ne vous empêchera pas de le faire pour le moment.
4. La génération du serveur fictif distant prend plusieurs minutes. Vous pouvez suivre la progression dans le panneau OUTPUT (Sortie) de Google Cloud.
5. Une fois la création du serveur de simulation distant terminée, l'URL du serveur distant s'affiche dans la liste des serveurs du panneau Swagger et dans le panneau SORTIE.
6. Pour utiliser le serveur fictif, ouvrez un chemin d'accès, puis cliquez sur Essayer.
   
   
   Renseignez tous les paramètres de requête, puis cliquez sur Exécuter.
   
   
   Vous pouvez également envoyer des requêtes à l'aide de curl depuis une requête. Utilisez l'adresse et le port du serveur dans le menu déroulant Serveurs.

Pour partager l'accès au serveur de simulation avec d'autres utilisateurs :

1. Attribuez le rôle d'appelant aux autres utilisateurs pour le service déployé. Consultez la section Authentifier les développeurs.
2. Lorsque les utilisateurs envoient une requête au serveur fictif, ils suivent les instructions de la section Tester votre service privé.

Pour gérer les serveurs distants de simulation déployés, procédez comme suit :

1. Accédez au hub d'API et recherchez l'API pour afficher tous les déploiements de l'API, y compris les serveurs fictifs distants.
2. Utilisez l'URL de la ressource pour accéder au déploiement et le gérer en arrêtant, en supprimant et en effectuant d'autres actions sur le serveur fictif.