Créer un proxy d'API simple

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

Consultez la documentation d'Apigee Edge.

Apigee vous permet d'exposer rapidement des services de backend en tant qu'API. Pour ce faire, vous devez créer un proxy d'API offrant une façade pour le service de backend que vous souhaitez exposer. Fournissez seulement l'adresse réseau du service de backend, ainsi que certaines informations qui permettront à Apigee de créer le proxy d'API qui sera exposé aux développeurs.

Le proxy d'API dissocie l'implémentation de votre service de backend de l'API que les développeurs utilisent. L'objectif est de protéger les développeurs des futurs changements qui seront apportés à vos services de backend. Lorsque vous mettrez à jour vos services de backend, les développeurs, tenus à l'écart de ces changements, pourront continuer à appeler l'API sans interruption.

Cette rubrique fournit des informations sur les différents types de proxys et les paramètres associés. Pour obtenir des instructions détaillées sur la création de proxys, consultez les sections suivantes :

Créer un proxy d'API à l'aide de l'interface utilisateur

Le moyen le plus simple de créer un proxy d'API consiste à utiliser l'assistant de création de proxy.

Pour accéder à l'assistant de création de proxy à l'aide de l'interface utilisateur d'Apigee, procédez comme suit :

  1. Connectez-vous à l'UI Apigee.
  2. Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
  3. Cliquez sur Créer.
    Bouton "Créer un proxy"

L'assistant de création de proxy affiche les différentes étapes à suivre pour générer et ajouter des fonctionnalités minimales à un proxy d'API.

Première page de l'assistant de création de proxy vous invitant à sélectionner le proxy inverse, aucune cible ou un groupe de proxys pour personnaliser le flux de l'assistant.

La première page de l'assistant vous permet de créer un proxy d'API à partir des sources suivantes :

Type Description
Proxy inverse (le plus courant)

Un proxy d'API qui achemine les requêtes entrantes vers des services de backend HTTP existants. Il peut s'agir d'une API JSON ou XML. Consultez la section Créer un proxy inverse pour un service HTTP plus loin sur cette page.

Cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) pour générer le proxy à partir d'une spécification OpenAPI valide. Pour plus d'informations sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys plus loin sur cette page.
Aucune cible

Un proxy d'API sans backend de l'API ("aucune cible"). Cette méthode s'apparente à la création d'un proxy inverse pour un service HTTP décrite précédemment, sauf que vous ne devez pas spécifier une API existante lorsque vous définissez les détails du proxy d'API.

Cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) pour générer le proxy à partir d'une spécification OpenAPI valide. Pour plus d'informations sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys plus loin sur cette page.
Importer le groupe de proxys Un groupe de proxys d'API existant (par exemple, l'un des exemples de proxys d'API disponibles sur GitHub). Voir Importer un proxy d'API à partir d'un groupe de proxys d'API.

Les sections suivantes détaillent chaque type de proxy.

Créer un proxy inverse pour un service HTTP

Apigee génère des proxys inverses basés sur les informations suivantes :

  • URL du service de backend
  • Chemin d'URI qui identifie de manière unique l'API qui sera exposée par le proxy d'API aux applications grand public.

L'URL du service de backend représente généralement une application compatible avec le service appartenant à votre organisation. Elle peut également pointer vers une API accessible au public. Il peut s'agir d'une API ou d'un service que vous contrôlez (par exemple, une application RH interne ou une application Rails dans le cloud), ou bien d'une API ou d'un service tiers (par exemple, Twitter ou Instagram).

Les informations sur le proxy suivantes sont disponibles après l'accès à l'assistant de création de proxy et en sélectionnant un type de proxy :

Champ Description
Nom Nom affiché pour votre API. Indiquez des caractères alphanumériques, des tirets (-) ou des traits de soulignement (_).
Chemin de base

Fragment d'URI qui apparaît après l'adresse http://[host] ou https://[host] du proxy d'API. Apigee utilise l'URI de chemin de base pour faire correspondre et acheminer les messages de requête entrantes vers le proxy d'API approprié.

Le chemin de base est suivi des URL des éventuelles ressources supplémentaires. Voici la structure d'URL complète que les clients utilisent pour appeler votre proxy d'API :

https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH

Utiliser des caractères génériques dans les chemins de base

Utilisez un ou plusieurs caractères génériques /*/ dans les chemins d'accès de base du proxy d'API pour assurer la pérennité de vos proxys d'API. Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.
Description (Facultatif) Description de l'API.
Cible (API existante) URL du service de backend que ce proxy d'API appelle.

Importer un proxy d'API à partir d'un package de proxy d'API

Les proxys d'API sont souvent définis comme des ensembles de fichiers XML accompagnés d'autres fichiers sources. En définissant vos proxys d'API en tant qu'ensemble de fichiers extérieurs à Apigee, vous pouvez les conserver dans un système de gestion de code source, puis les importer dans Apigee à des fins de test et de déploiement.

Pour importer des proxys d'API à partir d'un groupe de proxys d'API, procédez comme suit :

  1. Accédez à l'assistant de création de proxy, comme décrit dans la section Créer un proxy d'API à l'aide de l'interface utilisateur plus haut sur cette page.
  2. Cliquez sur Importer le groupe de proxys.

  3. Sur la page Importer le groupe de proxys de l'assistant de proxy, saisissez les informations suivantes :

    Champ Description
    Dossier ZIP Fichier ZIP contenant la configuration du proxy d'API. Accédez au fichier par glisser-déposer ou en effectuant un clic.
    Nom Nom affiché pour votre API. Correspond par défaut au nom du fichier ZIP sans l'extension.
  4. Cliquez sur Suivant.

  5. Sur la page Summary (Résumé), sélectionnez les environnements de déploiement, si vous le souhaitez, puis cliquez sur Create and deploy (Créer et déployer).

    Un accusé de réception s'affiche pour confirmer que votre nouveau proxy d'API a bien été créé.

  6. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Créer des proxys d'API gRPC

En plus des proxys d'API REST, Apigee est actuellement compatible avec les proxys d'API gRPC, pour le moment exclusivement en passthrough. Avec compatibilité passthrough, la charge utile gRPC est opaque au niveau d'Apigee et le trafic est acheminé depuis le client gRPC vers le serveur cible gRPC préconfiguré dans la configuration cible.

À ce stade, les proxys d'API gRPC Apigee :

  • acceptent les requêtes gRPC unaires ;
  • ne peuvent pas utiliser de règles qui affectent la charge utile ;
  • peuvent être utilisés dans les produits d'API qui ne sont pas associés à des proxys GraphQL ou REST. Les quotas spécifiques aux produits d'API et les autres paramètres d'opération s'appliquent à tous les proxys du produit ;
  • ne sont pas compatibles avec Apigee hybrid ;
  • utilisent deux variables de flux spécifiques à gRPC : request.grpc.rpc.name et request.grpc.service.name ;
  • peuvent être surveillés avec ces variables Apigee Analytics spécifiques à gRPC : x_apigee_grpc_rpc_name, x_apigee_grpc_service_name et x_apigee_grpc_status ;
  • renvoient des codes d'état gRPC.

Vous devez également configurer votre équilibreur de charge pour qu'il soit compatible avec gRPC. Consultez les pages Utiliser gRPC avec vos applications et Créer un routage pour gRPC à l'aide des commandes gcloud CLI.

Pour créer un proxy d'API gRPC, définissez d'abord un serveur cible gRPC (consultez la section Créer des TargetServers), puis spécifiez ce serveur cible lors de la création du proxy.

Créer un routage pour gRPC à l'aide des commandes gcloud CLI

Cette section présente des exemples de commandes permettant de créer un routage pour des proxys gRPC à l'aide de gcloud CLI. Ces instructions incluent la configuration des équilibreurs de charge, d'un serveur cible et d'un MIG.

Cette section n'est pas un guide complet de création du routage. Ces exemples peuvent ne pas convenir à tous les cas d'utilisation. En outre, ces instructions supposent que vous maîtrisez le routage externe (MIG) et la configuration gRPC des équilibreurs de charge cloud.

Définir des variables d'environnement

Les variables d'environnement suivantes sont utilisées dans les commandes figurant dans les sous-sections. 

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Ajout de sécurité

Sur la page Règles communes de l'assistant de création de proxy, sélectionnez le type d'autorisation de sécurité que vous souhaitez ajouter. Le tableau suivant récapitule les options disponibles :

Autorisation de sécurité Description
Clé API Ajoute une validation de clé API simple au proxy d'API que vous définissez. En réponse, la plate-forme d'API ajoute une règle VerifyAPIKey et une règle AssignMessage à votre proxy d'API. La règle VerifyAPIKey valide les clés API présentées par les applications demandeuses. La règle AssignMessage supprime la clé API, fournie dans l'appel d'API en tant que paramètre de requête, de la requête transmise au serveur backend.
OAuth 2.0 Ajoute l'authentification basée sur OAuth 2.0 à votre proxy d'API. Apigee ajoute automatiquement les règles suivantes à votre proxy d'API : une règle pour vérifier un jeton d'accès et une autre pour supprimer le jeton d'accès du message avant qu'il ne soit transféré à votre service de backend. Pour savoir comment obtenir un jeton d'accès, consultez la page OAuth.
Directe (sans autorisation) Aucune autorisation requise. Les requêtes sont transmises au backend sans contrôle de sécurité sur Apigee.

Assurer la compatibilité avec CORS

Le partage de ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) est un mécanisme standard qui permet à un navigateur Web d'envoyer des requêtes directes à un autre domaine. Cette norme définit un ensemble d'en-têtes HTTP que les navigateurs Web et les serveurs utilisent pour mettre en œuvre la communication entre domaines.

Vous pouvez ajouter la compatibilité avec le CORS en effectuant l'une des actions suivantes :

  • Ajouter la règle CORS au PreFlow de requête du ProxyEndpoint
  • Sélectionner Ajouter des en-têtes CORS sur la page Règles communes de l'assistant Créer un proxy.

Pour plus d'informations sur la compatibilité CORS, y compris l'ajout de la compatibilité CORS préliminaire à un proxy, consultez la page Ajouter la compatibilité CORS à un proxy d'API.

Ajouter des quotas

Les quotas protègent votre service de backend contre le trafic élevé sous Quota. Consultez la section Quotas. (Non disponible si l'autorisation directe est sélectionnée).

Utiliser des spécifications OpenAPI pour générer des proxys

Cette section traite de l'option Utiliser le protocole OpenAPI qui est permet de générer des types de serveurs proxy d'API "inversés" ou "no target" à partir d'une spécification OpenAPI.

Qu'est-ce qu'une spécification OpenAPI ?

Logo Open API Initiative   L'OpenAPI Initiative (OAI) se concentre sur la création, l'évolution et la promotion d'un format de description d'API neutre du point de vue du fournisseur, basé sur la spécification Swagger." Pour en savoir plus, consultez la page OpenAPI Initiative.

Une spécification OpenAPI utilise un format standard pour décrire une API RESTful. Développées au format JSON ou YAML, les spécifications OpenAPI sont lisibles par une machine, mais sont également faciles à lire et à comprendre. La spécification décrit les éléments d'une API, tels que son chemin de base, ses chemins et verbes, en-têtes, paramètres de requête, opérations, types de contenu, descriptions de réponse, etc. En outre, une spécification OpenAPI est couramment utilisée pour générer la documentation de l'API.

Le fragment suivant d'une spécification OpenAPI décrit le service cible fictif d'Apigee, http://mocktarget.apigee.net. Pour en savoir plus, consultez la page Spécification OpenAPI pour l'exemple helloworld.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Avec l'assistant de création de proxy, vous pouvez importer une spécification OpenAPI et l'utiliser pour générer un proxy d'API. Une fois le proxy généré, vous pouvez utiliser l'interface utilisateur d'Apigee pour le développer davantage en ajoutant des règles, en mettant en œuvre du code personnalisé, et plus encore, comme vous pourriez le faire sur n'importe quel proxy Apigee.

Créer un proxy d'API à partir d'une spécification OpenAPI

Créez vos proxys d'API à partir d'une spécification OpenAPI. En quelques clics, vous obtenez un proxy d'API avec les chemins, paramètres, flux conditionnels et points de terminaison cibles générés automatiquement. Vous pouvez ensuite ajouter des fonctionnalités telles que la sécurité OAuth, la limitation du débit et la mise en cache.

Dans l'assistant de création de proxy, cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) et suivez l'assistant pour créer un proxy inverse ou sans cible à partir d'une spécification OpenAPI. Pour plus d'informations, consultez la page Créer un proxy d'API à partir d'une spécification OpenAPI.

Créer une révision d'un proxy d'API

Créez une révision d'un proxy d'API, comme décrit ci-dessous.

Pour créer une révision d'un proxy d'API, procédez comme suit :

  1. Connectez-vous à l'UI Apigee.
  2. Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
  3. Dans la liste, cliquez sur le proxy d'API que vous souhaitez copier.

  4. Cliquez sur l'onglet Développer :

  5. Cliquez sur le bouton Enregistrer, puis sur Enregistrer en tant que nouvelle révision.

Sauvegarder un proxy d'API

Vous pouvez sauvegarder un proxy d'API existant sous la forme d'un ensemble de fichiers XML dans un groupe de proxys d'API. Une fois le proxy d'API exporté vers un groupe, vous pouvez l'importer dans un nouveau proxy, comme décrit dans la section Importer un proxy d'API à partir d'un groupe de proxys d'API plus haut sur cette page. Pour plus d'informations, consultez la page Télécharger des proxys d'API.

Créer un proxy d'API à l'aide de l'API

Pour créer un proxy d'API à l'aide de l'API, consultez la page Créer un proxy d'API.