Variables de requête et de réponse

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Lorsque vous envoyez une requête à un proxy d'API, vous pouvez transmettre tout ou partie des informations suivantes, selon la configuration du proxy d'API :

  • En-têtes de requête
  • Paramètres de requête
  • Données de formulaire
  • Charges utiles XML ou JSON
  • URI de ressource

Par défaut, toutes les données d'une requête sont transmises de ProxyEndpoint à TargetEndpoint. Par conséquent, lorsque TargetEndpoint envoie la requête au serveur backend, toutes les informations de la requête d'origine sont transmises au service de backend.

Il en va de même pour la réponse reçue par Edge du service de backend. Par défaut, toutes les données reçues dans la réponse sont transmises sans modification à l'application à l'origine de la requête.

Comment les données de requête sont-elles transmises au serveur backend ?

L'image suivante illustre une définition de proxy d'API :

Requête d'un client HTTP passant par un point de terminaison de proxy au point de terminaison cible sur le backend pour atteindre le service HTTP. Des exemples de points de terminaison de proxy et de point de terminaison cible sont fournis.

Pour ce proxy d'API :

  • Hôte virtuel de proxy d'API : "default"
  • Domaine défini par l'hôte virtuel : "http://myOrg-prod.apigee.net"
  • Chemin d'accès de base du proxy : "/v1/weather"
  • TargetEndpoint spécifié par la règle de routage: "default"
  • URL cible : "http://weather.yahooapis.com"

Une application cliente envoie une requête GET au proxy d'API à l'aide de la commande curl suivante :

curl -X GET http://myOrg-prod.apigee.net/v1/weather/forecastrss?w=12797282

Notez que cette requête contient la ressource "forecastrss" et un paramètre de requête, w. Edge analyse la requête comme indiqué ci-dessous et attribue des parties de la requête aux variables de flux:

{request.verb} {proxy.basepath}/{proxy.pathsuffix}?{request.querystring}

Les variables de flux sont définies avec les valeurs suivantes :

  • request.verb : "GET"
  • proxy.basepath : "/v1/weather"
  • proxy.pathsuffix : "forecastrss"
  • request.querystring : "w=12797282"

Le TargetEndpoint envoie ensuite une requête au service de backend en utilisant les informations de la requête :

{request.verb} {target.basepath}/{proxy.pathsuffix}?{request.querystring}

Remarquez la façon dont les paramètres de ressource et de requête spécifiés dans la requête sont automatiquement inclus dans la requête adressée au serveur backend. À partir de la définition de TargetEndpoint, la requête se présente alors sous la forme :

curl -X GET http://weather.yahooapis.com/forecastrss?w=12797282

Tout comme les paramètres de requête, les en-têtes ou les paramètres de formulaire que vous incluez dans la requête au proxy d'API sont transmis au serveur backend. Par exemple, vous exécutez la requête ci-dessous qui inclut un en-tête :

curl -X GET -H 'Content-type:application/xml' http://myOrg-prod.apigee.net/v1/weather/forecastrss?w=12797282

Ou vous exécutez une requête ci-dessous pour inclure un en-tête et des données de formulaire :

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "janetutorialxml@example.com",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://myOrg-prod.apigee.net/v1/register/user

Dans les deux exemples, les en-têtes et les données de formulaire sont transmis au service de backend sans modification. Les en-têtes sont représentés par des variables de flux telles que request.headers.count et request.headers.names. Les données de formulaire sont représentées par des variables de flux telles que request.formparam.count et request.formparam.names.

Comment les données de réponse sont-elles renvoyées ?

Par défaut, toutes les données reçues par Edge du service de backend dans la réponse sont transmises telles quelles à l'application à l'origine de la requête. Comme décrit ci-dessus pour la requête, les données renvoyées dans la réponse sont accessibles via des variables de flux sur Edge. Pour en savoir plus, consultez la Documentation de référence sur les variables de flux.

Accéder aux données de requête et de réponse dans un proxy d'API

Il peut arriver que vous souhaitiez modifier des données de requête avant de les envoyer au serveur backend. Exemple :

  • Pour supprimer les informations de sécurité utilisées par Edge pour valider les requêtes. Ces informations ne sont pas requises par le service de backend.
  • Pour ajouter des données envoyées au service de backend, par exemple pour suivre les utilisateurs ou pour collecter des données analytiques.
  • Pour traiter de manière conditionnelle la requête en fonction des données de la requête. Par exemple, un proxy d'API peut avoir plusieurs TargetEndpoints. Le TargetEndpoint utilisé par la requête est déterminé par les données de la requête. Vous supprimez ensuite ces données de la requête avant de les envoyer au service de backend.

Il en va de même pour les données de réponse. Dans le cadre du traitement de la réponse, le proxy d'API peut souhaiter modifier les données avant de les renvoyer à l'application à l'origine de la requête.

Accéder aux messages de requête

Vous pouvez utiliser des stratégies pour accéder à des parties d'un message de requête et les modifier. Ces parties incluent :

  • En-têtes
  • Paramètres de requête
  • Paramètres de formulaire
  • Adresse IP source
  • Corps du message HTTP

Dans un flux normal, une fois la requête traitée, le proxy envoie la requête transformée à la cible.

Les stratégies peuvent examiner les variables de requête, puis transformer ou rejeter la requête en fonction du contenu de ces variables. Les stratégies transforment la requête en définissant les variables appropriées, par exemple les variables correspondant aux en-têtes de requête.

Accéder aux messages de réponse

À l'aide des variables qui s'appliquent au message de réponse, les stratégies peuvent accéder aux composants de messages, y compris l'en-tête, les paramètres de requête et les paramètres de formulaire, l'adresse IP source, le corps du message HTTP, etc.

Le proxy reçoit un message de réponse, puis l'applique à une série de stratégies, en fonction des conditions évaluées sur la réponse, qui peuvent modifier ou transformer la réponse.

Les stratégies peuvent examiner les variables de réponse, puis transformer ou rejeter la requête en fonction du contenu de ces variables. Les stratégies transforment la réponse en définissant les variables appropriées, par exemple les variables correspondant aux en-têtes de réponse.

Stratégies courantes pour l'accès aux variables de flux

Edge définit plusieurs stratégies que vous pouvez utiliser pour traiter les données de demande et de réponse. Ces stratégies incluent :

  • Stratégie AssignMessage : Crée ou modifie les messages de requête ou de réponse HTTP lors d'un flux de proxy d'API. Crée et renseigne également de nouvelles variables de flux.
  • Stratégie ExtractVariables : Extrait du contenu des messages, y compris les en-têtes, les chemins d'URI, les charges utiles et les paramètres de requête, pour l'utiliser dans une instruction de condition. La stratégie applique ensuite un modèle de texte au contenu du message et définit une variable désignée lors de la recherche d'une correspondance.
  • Stratégie JSONtoXML et XMLtoJSON : Convertit les messages de JavaScript Object Notation (JSON) au format XML (langage de balisage extensible), ou inversement.
  • Stratégie JavaCallout, stratégie JavaScript, stratégie PythonScript, stratégie RegularExpressionProtection : Ces stratégies vous permettent d'écrire un script pour accéder aux variables de flux contenant des données de requête et de réponse.