Utiliser des variables de flux

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

Consultez la documentation d'Apigee Edge.

Les variables de flux sont des objets auxquels vous pouvez accéder à partir de vos stratégies ou utilitaires (comme l'outil Debug). Elles vous permettent de maintenir l'état associé à une transaction d'API traitée par Apigee.

Guide de démarrage rapide  : pour obtenir la liste complète de toutes les variables de flux et leurs propriétés, consultez la Documentation de référence sur les variables de flux.

Vidéo

Remarque : La vidéo suivante montre l'éditeur de proxy classique dans l'interface utilisateur d'Apigee. Apigee intègre une nouvelle version de l'éditeur de proxys, dont la conception est différente de celle de la version classique présentée dans la vidéo.

La vidéo suivante présente les variables de flux :

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 Apigee 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, Apigee 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 à Apigee 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, ou en JavaScript 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 Apigee, de manière semblable au 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.

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 Apigee 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 vous aider à comprendre à quel moment les variables sont créées et à quel moment elles sont disponibles, consultez la section Visualiser le flux d'un proxy d'API.

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 consistant à lire et à définir des variables à l'aide de JavaScript est semblable au travail que vous pouvez effectuer avec la règle AssignMessage (comme indiqué précédemment). Il s'agit simplement d'une autre manière d'accomplir les mêmes objectifs sur Apigee. 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 trouvant dans le champ d'application au sein du flux 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.

Documentation complémentaire Si vous souhaitez en savoir plus sur la structure de flux de proxy, consultez la page Configurer des flux.

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.

Remarque : Une fois qu'une variable de flux a été renseignée dans le champ d'application donné, elle reste disponible tout au long du reste du cycle de vie du flux de proxy. Si vous essayez d'accéder à une variable qui n'est pas encore incluse dans le champ d'application, vous recevrez une erreur ou une valeur NULL.

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 Apigee 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.

Remarque : Les champs d'application de toutes les variables Apigee intégrées sont répertoriés dans la documentation de référence sur les variables de flux.

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.

Remarque : Il est possible de configurer certaines règles pour générer une erreur ou renvoyer NULL lors de l'accès à une variable non définie. Reportez-vous aux pages de référence sur les règles individuelles pour plus de détails.

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, 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.

Bonne pratique : Google vous recommande d'utiliser la convention de dénomination par points lorsque vous créez des variables de flux personnalisées. Il peut être utile d'utiliser les points pour organiser une hiérarchie de vos variables personnalisées.

Par exemple, approval.code et approval.status peuvent faire référence à une fonctionnalité d'approbation au sein du flux.

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 :

• Utiliser des variables de flux dans le code JavaScript
• Règle JavaScript

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.

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, par exemple, utiliser l'outil Debug pour voir quelles variables ont été définies sur une instance particulière dans un flux de 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, la règle ExtractVariables analyse un message de réponse et stocke les 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 Apigee dispose d'un accès direct aux variables de flux de proxy.

Remarque : Vous pouvez appeler JavaScript à partir d'un proxy à l'aide de la règle JavaScript.

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).

Remarque : La documentation de référence sur les variables de flux indique quelles variables sont accessibles en écriture et en lecture seule. Pour en savoir plus, consultez la section Modèle d'objet JavaScript.

Vous pouvez également obtenir ou définir des variables de flux de proxy dans le code Java que vous exécutez à l'aide de la règle JavaCallout.

À retenir

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

• Certaines variables out-of-the-box 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.
• 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.

Conseil : Vous trouverez un certain nombre d'exemples utilisant des variables d'une manière ou d'une autre. Recherchez celles qui utilisent la règle ExtractVariables, qui est couramment utilisée pour traiter les variables dans un flux de proxy.

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.