Utiliser des variables de flux

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Conceptuellement, les variables de flux sont des objets auxquels vous pouvez accéder depuis vos règles ou vos utilitaires (comme l'outil Trace). Elles vous permettent de maintenir l'état associé à une transaction d'API traitée par Apigee Edge.

Que sont les variables de flux ?

Les variables de flux existent dans le contexte d'un flux de proxy d'API et suivent l'état dans une transaction d'API de la manière que les variables nommées suivent l'état dans un programme logiciel. Les variables de flux stockent des informations telles que :

  • L'adresse IP, les en-têtes, le chemin de l'URL et la charge utile envoyés à partir de l'application à l'origine de la requête.
  • Des informations système telles que la date et l'heure auxquelles Edge reçoit une requête.
  • Des données dérivées lors de l'exécution d'une règle. Par exemple, après l'exécution d'une règle qui valide un jeton OAuth, Edge crée des variables de flux qui contiennent des informations telles que le nom de l'application à l'origine de la requête.
  • Des informations sur la réponse du système cible

Certaines variables sont "intégrées" à Edge et sont automatiquement renseignées à la réception d'une requête API. Elles sont disponibles tout au long d'une transaction d'API. Vous pouvez également créer vos propres variables personnalisées à l'aide de règles telles que AssignMessage policy ou en code JavaScript, Node.js et Java.

Comme vous pourrez le voir, les variables ont un champ d'application et leur emplacement dépend en partie de leur date de création dans le flux de proxy d'API. En général, lorsqu'une variable est créée, elle est disponible pour toutes les règles et tout le code qui s'exécutent ultérieurement dans le flux de transaction d'API.

Comment les variables de flux sont-elles utilisées ?

Les variables de flux sont utilisées dans les règles et dans les flux conditionnels :

  • Les règles peuvent récupérer l'état des variables de flux et les utiliser pour effectuer leur travail.

    Par exemple, une règle VerifyJWT peut récupérer le jeton à valider à partir d'une variable de flux, puis effectuer la validation. Autre exemple : une règle JavaScript peut récupérer des variables de flux et encoder les données contenues dans ces variables.

  • Les flux conditionnels peuvent référencer des variables de flux pour diriger le flux d'une API via Edge, un peu comme le fonctionnement d'une instruction "switch" dans la programmation.

    Par exemple, une règle qui renvoie une erreur ne peut s'exécuter que lorsqu'une variable de flux particulière est définie. Enfin, vous pouvez obtenir et définir des variables de flux dans une application cible Node.js.

Examinons des exemples d'utilisation de variables dans chacun de ces contextes.

Variables de flux dans les règles

Certaines règles acceptent les variables de flux en entrée.

Par exemple, la règle AssignMessage suivante prend la valeur de la variable de flux client.ip et la place dans un en-tête de requête nommé My-Client-IP. Si elle est ajoutée au flux de requête, cette règle définit un en-tête qui est transmis à la cible du backend. S'il est défini dans le flux de réponse, l'en-tête est renvoyé à l'application cliente.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Autre exemple : lorsqu'une règle de quota s'exécute, plusieurs variables de flux sont renseignées avec des valeurs liées à cette règle. L'une de ces variables est appelée ratelimit.my-quota-policy.used.count (où my-quota-policy est le nom de la règle de quota qui vous intéresse).

Vous pouvez ensuite exécuter un flux conditionnel indiquant "si le nombre de quotas actuel est inférieur à 50 % du maximum et que l'heure est comprise entre 9 h et 17 h, appliquez un autre quota". Cette condition peut dépendre de la valeur du nombre de quotas actuel et d'une variable de flux appelée system.time, qui est l'une des variables Edge intégrées.

Variables de flux dans les flux conditionnels

Les flux conditionnels évaluent les variables de flux et permettent aux proxys de se comporter de manière dynamique. Les conditions sont généralement utilisées pour modifier le comportement des flux, des étapes et des règles de routage.

Voici un flux conditionnel qui évalue la valeur de la variable request.verb dans une étape de flux de proxy. Dans ce cas, si le verbe de la requête est "POST", la règle VerifyAPIKey est exécutée. Il s'agit d'un modèle couramment utilisé dans les configurations de proxy d'API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Vous vous demandez peut-être d'où proviennent des variables telles que request.verb, client.ip et system.time ? Quand sont-elles instanciées et quand leur valeur est-elle renseignée ? Pour comprendre quand les variables sont créées et quand elles vous sont disponibles, consultez la section Comprendre le champ d'application des variables de flux.

Variables de flux dans du code JavaScript appelées avec la règle JavaScript

Avec la règle JavaScript, vous pouvez exécuter du code JavaScript dans le contexte d'un flux de proxy d'API. Le code JavaScript exécuté par cette règle utilise le modèle d'objet JavaScript Apigee, qui fournit un code personnalisé permettant d'accéder aux requêtes, aux réponses et aux objets contextuels associés au flux du proxy d'API dans lequel votre code est exécuté. Par exemple, ce code définit un en-tête de réponse avec la valeur obtenue à partir de la variable de flux "target.name".

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Cette technique consiste à utiliser JavaScript pour lire et définir des variables, un peu comme avec la règle AssignMessage (voir ci-dessus). Il s'agit simplement d'une autre manière d'accomplir les mêmes objectifs sur Edge. L'essentiel à retenir est le fait que le JavaScript exécuté par la règle JavaScript a accès à toutes les variables de flux existantes et se trouve dans le champ d'application au sein du flux de proxy d'API.

Variables de flux dans le code Node.js

En exigeant le module apigee-access, vous pouvez définir et accéder aux variables de flux à partir du code Node.js déployé sur Edge.

Voici un exemple simple où une variable appelée custom.foo est définie sur la valeur Bar. Une fois définie, cette nouvelle variable devient disponible pour toutes les règles ou tout autre code qui se produit dans le flux de proxy après l'exécution du code Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Pour en savoir plus sur l'utilisation de apigee-access avec des variables, consultez la section Accéder aux variables de flux dans Node.js.

Comprendre le champ d'application des variables de flux

Le champ d'application des variables est lié au flux ou au "cycle de vie" global d'un appel de proxy d'API.

Visualiser le flux d'un proxy d'API

Pour comprendre le champ d'application des variables de flux, il est important de comprendre ou de visualiser la manière dont les messages transitent par un proxy d'API. Un proxy d'API consiste en une série d'étapes de traitement des messages organisées en tant que flux. À chaque étape d'un flux de proxy, le proxy évalue les informations disponibles et décide de la marche à suivre. En parallèle, il peut exécuter un code de règle ou effectuer des branches conditionnelles.

La figure suivante illustre cette séquence de flux. Notez que les flux sont composés de quatre segments principaux : requête ProxyEndpoint, requête TargetEndpoint, réponse TargetEndpoint et réponse ProxyEndpoint.

Gardez à l'esprit cette structure de flux lorsque nous commencerons à explorer les variables de flux dans la suite de cette rubrique.

Lien entre le champ d'application de la variable et le flux du proxy

Dès lors que vous arrivez à visualiser le flux des messages dans un proxy, comme décrit précédemment, vous pouvez commencer à comprendre le champ d'application des variables. Par champ d'application, on entend le moment de la première instanciation d'une variable dans le cycle de vie du flux de proxy.

Par exemple, si une règle est associée au segment de requête ProxyEndpoint, cette règle ne peut pas accéder aux variables comprises dans le segment de requête TargetEndpoint. En effet, le segment de requête TargetEndpoint du flux n'a pas encore été exécuté. Par conséquent, le proxy d'API n'a pas eu la possibilité de renseigner des variables dans ce champ d'application.

Le tableau suivant répertorie l'ensemble complet des champs d'application des variables et indique le moment où ils sont disponibles dans le flux de proxy.

Champ d'application de la variable Moment où ces variables sont renseignées
Requête de proxy Segment de requête ProxyEndpoint
Requête cible Segment de requête TargetEndpoint
Réponse cible Segment de réponse TargetEndpoint
Réponse de proxy Segment de réponse ProxyEndpoint
Toujours disponible Dès que le proxy reçoit une requête. Ces variables sont disponibles tout au long du cycle de vie du flux de proxy.

Par exemple, il existe une variable Edge intégrée nommée client.ip. Cette variable a le champ d'application "requête de proxy". Elle est automatiquement renseignée avec l'adresse IP du client qui a appelé le proxy. Elle est renseigné lorsqu'une requête atteint d'abord le ProxyEndpoint et reste disponible tout au long du cycle de vie du flux de proxy.

Il existe une autre variable intégrée appelée target.url. Le champ d'application de cette variable est "requête cible". Il est renseigné dans le segment de requête TargetEndpoint avec l'URL de requête envoyée à la cible de backend. Si vous essayez d'accéder à target.url dans le segment de requête ProxyEndpoint, vous recevrez une valeur NULL. Si vous essayez de définir cette variable avant qu'elle ne soit soumise à ce champ d'application, le proxy ne fait rien : il ne génère pas d'erreur et ne définit pas de variable.

Voici un exemple simple qui montre comment réfléchir au champ d'application des variables. Supposons que vous souhaitiez copier l'intégralité du contenu d'un objet de requête (en-têtes, paramètres, corps) et l'attribuer à la charge utile de réponse à renvoyer à l'application à l'origine de la requête. Vous pouvez utiliser la règle AssignMessage pour cette tâche. Le code de la règle se présente comme suit :

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Cette règle copie simplement l'objet request et l'attribue à l'objet response. Mais où cette règle doit-elle être placée dans le flux de proxy ? Elle doit être placée dans la réponse TargetEndpoint, car le champ d'application de la variable de réponse est "réponse cible".

Référencer des variables de flux

Dans Apigee Edge, toutes les variables intégrées suivent une convention de dénomination par points. Cette convention permet de déterminer plus facilement l'objectif de la variable. Par exemple, system.time.hour et request.content.

Apigee réserve plusieurs préfixes pour organiser les variables pertinentes de manière appropriée. Ces préfixes incluent :

  • request
  • response
  • system
  • target

Pour référencer une variable dans une règle, placez-la entre accolades. Par exemple, la règle AssignMessage suivante prend la valeur de la variable client.ip et la place dans un en-tête de requête appelé Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Dans les flux conditionnels, les accolades ne sont pas nécessaires. L'exemple de condition suivant évalue la variable request.header.accept :

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Vous pouvez également référencer des variables de flux en JavaScript et Java. Pour en savoir plus, consultez les pages suivantes :

Type de données des variables de flux

Chaque propriété d'une variable de flux possède un type de données bien défini, tel que "String", "Long", "Integer", "Boolean" ou "Collection". Ces types de données sont répertoriés dans la documentation de référence sur les variables de flux. Pour les variables créées par une règle, reportez-vous à la rubrique de référence de la règle concernée pour obtenir des informations sur les types de données.

Les variables que vous créez manuellement adoptent le type indiqué lors de leur création et dépendent des types de valeurs autorisés. Par exemple, les variables créées dans le code Node.js sont limitées à Number, String, Boolean, null ou undefined.

Utiliser des variables de flux dans les règles

De nombreuses règles créent des variables de flux dans le cadre de leur exécution normale. La documentation de référence sur les règles décrit toutes ces variables spécifiques aux règles.

Lorsque vous travaillez avec des proxys et des règles, veillez à consulter la documentation de référence pour connaître les variables qui sont créées ainsi que leur utilisation. Par exemple, la règle de quotas crée un ensemble de variables contenant des informations sur le nombre et les limites de quotas, la date d'expiration, etc.

Certaines variables de règles sont utiles pour le débogage. Vous pouvez utiliser l'outil Trace, par exemple, pour voir quelles variables ont été définies sur une instance particulière dans un flux proxy.

La règle ExtractVariables vous permet de renseigner des variables personnalisées avec des données extraites des messages. Vous pouvez extraire des paramètres de requête, des en-têtes et d'autres données. Par exemple, vous pouvez analyser les messages de requête et de réponse à l'aide de modèles afin d'en extraire des données spécifiques.

Dans l'exemple suivant, Extract Variables analyse un message de réponse et stocke des données spécifiques extraites de la réponse. La règle crée deux variables personnalisées, geocoderesponse.latitude et geocoderesponse.longitude, et leur attribue des valeurs.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Notez que de nombreuses règles créent automatiquement des variables. Vous pouvez accéder à ces variables dans le contexte du flux de proxy. Elles sont décrites dans la documentation de référence sur les règles, sous chaque sujet de règle.

Utiliser des variables de flux dans le code JavaScript

Vous pouvez accéder aux variables et les définir directement dans le code JavaScript qui s'exécute dans le contexte d'un proxy d'API. Grâce au modèle d'objet JavaScript Apigee, le code JavaScript exécuté sur Edge dispose d'un accès direct aux variables de flux de proxy.

Pour accéder aux variables dans le code JavaScript, appelez les méthodes getter/setter sur l'un de ces objets :

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Comme vous pouvez le constater, ces références d'objets sont mappées aux segments habituels du modèle de flux du proxy, comme expliqué précédemment dans la section Visualiser le flux d'un proxy d'API.

L'objet context correspond aux variables disponibles globalement, telles que les variables système. Par exemple, vous pouvez appeler getVariable() sur l'objet context pour obtenir l'année en cours :

var year = context.getVariable('system.time.year');

De même, vous pouvez appeler setVariable() pour définir la valeur d'une variable personnalisée ou pour toutes les variables prêtes à l'emploi et accessibles en écriture. Le code suivant crée une variable personnalisée appelée organization.name.myorg et lui attribue une valeur.

var org = context.setVariable('organization.name.myorg', value);

Cette variable étant créée avec l'objet context, elle est disponible pour tous les segments de flux (il s'agit essentiellement d'une création de variable globale).

Vous pouvez également obtenir/définir des variables de flux de proxy dans le code Java que vous exécutez avec la règle JavaCallout.

Accéder aux variables de flux dans les applications Node.js

Vous pouvez obtenir, définir et supprimer des variables de flux à partir du code Node.js déployé sur Edge. Il vous suffit de "exiger" le module apigee-access dans votre code. Pour en savoir plus, consultez Accéder aux variables de flux dans Node.js.

À retenir

Voici quelques points importants à retenir concernant les variables de flux :

  • Certaines variables prêtes à l'emploi sont instanciées et renseignées automatiquement par le proxy lui-même. Elles sont décrites dans la documentation de référence sur les variables de flux.
  • Vous pouvez créer des variables personnalisées qui peuvent être utilisées dans le flux de proxy. Il est possible de créer des variables à l'aide de règles telles que la règle AssignMessage et la règle JavaScript, et dans le code Node.js.
  • Les variables ont un champ d'application. Par exemple, certaines variables sont automatiquement renseignées lorsque le premier proxy reçoit une requête d'une application. Les autres variables sont renseignées dans le segment de flux de réponse du proxy. Ces variables de réponse restent indéfinies jusqu'à l'exécution du segment de réponse.
  • Lorsque les règles sont exécutées, elles peuvent créer et renseigner des variables spécifiques aux règles. La documentation concernant chaque règle répertorie toutes ces variables spécifiques aux règles.
  • Les flux conditionnels évaluent généralement une ou plusieurs variables. Vous devez comprendre les variables si vous souhaitez créer des flux conditionnels.
  • De nombreuses règles utilisent des variables comme entrée ou sortie. Une variable créée par une règle peut-être utilisée ultérieurement par une autre règle.
  • Vous pouvez obtenir et définir de nombreuses variables de flux à partir de Node.js à l'aide de code JavaScript droit (et de notre modèle d'objet JavaScript) ou de la règle JavaAccroche, qui exécute du code sur Edge.

Exemples de code associés

Les exemples de proxy d'API sont disponibles sur GitHub et sont faciles à télécharger et à utiliser. Reportez-vous à la page Utiliser les exemples de proxy d'API pour en savoir plus sur le téléchargement et l'utilisation des exemples. Consultez la page Liste d'exemples pour obtenir une description des exemples de proxy d'API et de leur utilisation.

Voici des exemples de proxys qui utilisent et traitent des variables :

  • variables : montre comment extraire et définir les variables en fonction du contenu des messages JSON et XML et du transport.
  • policy-mashup-cookbook : application complète utilisant la composition des règles pour appeler deux API publiques, combiner des résultats et générer une réponse enrichie pour l'application cliente. Pour en savoir plus sur cet exemple, consultez la page Utiliser la composition de règle.
  • conditional-policy : met en œuvre une simple règle conditionnelle basée sur des valeurs de variable.

Articles associés

  • Toutes les variables qui sont automatiquement renseignées dans un proxy d'API sont répertoriées dans la documentation de référence sur les variables de flux. Cette documentation indique également le type et le champ d'application de chaque variable.
  • Si vous souhaitez savoir quelles variables sont renseignées par une règle spécifique, reportez-vous au sujet de référence de cette règle. Par exemple, reportez-vous à la section Variables de flux dans la documentation de référence sur les règles de quotas.