Règle Extract Variables

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

Quoi

La règle ExtractVariables extrait le contenu d'une requête ou d'une réponse, et définit la valeur d'une variable sur ce contenu. Vous pouvez extraire n'importe quelle partie du message, y compris les en-têtes, les chemins d'URI, les charges utiles JSON/XML, les paramètres de formulaire et les paramètres de requête. Lorsqu'elle est exécutée, la règle applique un modèle de texte au contenu du message et, lors de la recherche d'une correspondance, définit une variable avec le contenu du message spécifié.

Cette règle sert souvent à extraire des informations d'une requête ou d'un message de réponse, mais vous pouvez également l'utiliser pour extraire des informations d'autres sources, y compris des entités créées par la règle AccessEntity, des objets XML ou des objets JSON.

Après avoir extrait le contenu du message spécifié, vous pouvez référencer la variable dans d'autres règles lors du traitement d'une requête et d'une réponse.

Vidéos

Regardez les vidéos suivantes pour en savoir plus sur la règle ExtractVariables.

Vidéo Description
Extraire des variables de la charge utile XML Extrayez des variables d'une charge utile XML à l'aide de la règle Extract Variables.
Extraire des variables de la charge utile JSON Extraire les variables d'une charge utile JSON à l'aide de la règle Extract Variables.
Extraire des variables de paramètres Extraire des variables de paramètres, tels que les paramètres de requête, d'en-tête, de formulaire ou d'URI.
Extraire des variables de paramètres à valeurs multiples Extraire des variables de paramètres à valeurs multiples.
Extraire des variables du paramètre de requête (Classic Edge) Extrayez des variables d'un paramètre de requête à l'aide de l'interface utilisateur Classic Edge.
Extraire les variables de la charge utile XML ou JSON (Classic Edge) Extraire des variables d'une charge utile XML ou JSON à l'aide de l'interface utilisateur Classic Edge.

Samples

Ces exemples de code de règles montrent comment extraire des variables des types d'artefacts suivants :

GitHub

Ces liens pointent vers des exemples de proxys d'API fonctionnels que vous pouvez déployer et exécuter sur Edge. Elles utilisent ExtractVariables et se trouvent dans le dépôt api-platform-samples d'Apigee sur GitHub. Les fichiers README expliquent comment ExtractVariables est utilisé dans chaque cas, et comment déployer et exécuter chaque exemple.

URI

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Prenons l'exemple de code de règle ci-dessus. L'élément <URIPath> indique à la règle ExtractVariables d'extraire des informations du chemin d'URI. L'élément <Pattern> spécifie le modèle à appliquer au chemin d'URI. Le modèle est traité comme un format simple, les accolades représentant la partie variable du chemin d'URI.

Le nom de la variable à définir est déterminé par la valeur spécifiée dans l'élément <VariablePrefix>, ainsi que la valeur placée entre accolades {} dans l'élément <Pattern>. Les deux valeurs sont jointes par un point intermédiaire, ce qui donne un nom de variable tel que urirequest.id. Si aucun élément <VariablePrefix> n'est présent, le nom de la variable correspond simplement à la valeur indiquée entre accolades.

Prenons l'exemple de code de règle ci-dessus, qui fonctionne avec la requête entrante suivante :

GET http://org1-test.apigee.net/svc1/accounts/12797282

Supposons que le chemin de base du proxy d'API soit /svc1. Lorsque Apigee Edge applique le code de stratégie ExtractVariables ci-dessus à cette requête entrante, il définit la variable urirequest.id sur 12797282. Une fois qu'Apigee Edge a exécuté la stratégie, les stratégies ou le code ultérieurs dans le flux de traitement peuvent faire référence à la variable nommée urirequest.id pour obtenir la valeur de chaîne 12797282.

Par exemple, la règle Assign Message suivante intègre la valeur de cette variable dans la charge utile d'un nouveau message de requête :

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
 <DisplayName>AssignPayload</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

Paramètres de requête

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Prenons l'exemple de code de règle ci-dessus, qui fonctionne avec la requête entrante suivante :

GET http://org1-test.apigee.net/accounts/12797282?code=DBN88271

Lorsque Apigee Edge applique le code de règle ExtractVariables ci-dessus à cette requête entrante, il définit la variable queryinfo.dbncode sur 88271. Une fois qu'Apigee Edge a exécuté la stratégie, les stratégies ou le code ultérieurs dans le flux de traitement peuvent faire référence à la variable nommée queryinfo.dbncode pour obtenir la valeur de chaîne 88271.

Vous pouvez maintenant accéder à la variable queryinfo.dbncode dans votre proxy. Par exemple, la règle "AssignMessage" suivante copie le message dans la charge utile de la requête:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Paramètres multiples

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="w">
      <Pattern ignoreCase="true">{firstWeather}</Pattern>
   </QueryParam>
   <QueryParam name="w.2">
     <Pattern ignoreCase="true">{secondWeather}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supposons que la conception de votre API vous permette de spécifier plusieurs paramètres de requête portant le même nom. Vous pouvez utiliser cette règle pour extraire la valeur de plusieurs instances du paramètre de requête "w". Pour référencer ces paramètres de requête dans la règle ExtractVariables, vous utilisez des index. La première instance du paramètre de requête n'a pas d'index, la deuxième à l'index 2, la troisième à l'index 3, etc.

Prenons l'exemple de code de règle ci-dessus, qui fonctionne avec la requête entrante suivante :

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

Lorsque Apigee Edge applique le code de règle ExtractVariables ci-dessus à cette requête entrante, il définit la variable queryinfo.firstWeather sur Boston et la variable queryInfo.secondWeather sur Chicago.

Vous pouvez maintenant accéder à la variable queryinfo.firstWeather et à queryinfo.secondWeather dans votre proxy. Par exemple, la règle AssignMessage suivante la copie dans la charge utile de la requête :

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
    <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

En-têtes

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supposons que votre API utilise des jetons de support OAuth v2.0. Prenons l'exemple de code de règle ci-dessus lorsque vous travaillez avec une requête exécutant un jeton OAuth v2.0 qui comprend un en-tête comme celui-ci : Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

En tant que concepteur de l'API, supposons que vous souhaitiez utiliser la valeur du jeton (mais pas l'en-tête complet) comme clé de recherche dans le cache. Vous pouvez extraire le jeton à l'aide du code de la règle ExtractVariables ci-dessus.

Lorsque Apigee Edge applique le code de règle ExtractVariables ci-dessus à cet en-tête, il définira la variable clientrequest.oauthtoken sur TU08xptfFfeM7aS0xHqlxTgEAdAM.

Vous pouvez maintenant accéder à la variable clientrequest.oauthtoken dans votre proxy. Par exemple, la règle AssignMessage suivante la copie dans la charge utile de la requête :

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetHeader</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

JSON

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

Examinons la charge utile de la réponse JSON suivante :

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

Lorsque Apigee Edge applique le code de règle ExtractVariables ci-dessus à ce message JSON, il définit deux variables: geocoderesponse.latitude et geocoderesponse.longitude. Les deux variables utilisent le même préfixe de variable geocoderesponse. Le suffixe de ces variables est spécifié explicitement par l'attribut name de l'élément <Variable>.

La variable geocoderesponse.latitude obtient la valeur de 37.42291810. La variable geocoderesponse.longitude obtient la valeur de -122.08542120.

Vous pouvez maintenant accéder à la variable geocoderesponse.latitude dans votre proxy. Par exemple, la règle AssignMessage suivante la copie dans un en-tête nommé "latitude" dans la réponse :

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add> 
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

XML

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>
<XMLPayload>

Examinons la charge utile de la réponse XML suivante :

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

Lorsque Apigee Edge applique le code de règle ExtractVariables ci-dessus à ce message XML, il définit trois variables: directionsresponse.travelmode, directionsresponse.duration et directionsresponse.timeunit. Toutes les variables utilisent le même préfixe de variable directionsresponse. Le suffixe de ces variables est spécifié explicitement par l'attribut name de l'élément <Variable>.

La variable directionsresponse.travelmode obtient la valeur de DRIVING. La variable directionsresponse.duration obtient la valeur de 19. La variable directionsresponse.timeunit obtient la valeur de minutes.

Vous pouvez maintenant accéder à la variable directionresponse.travelmode dans votre proxy. Par exemple, la stratégie "AssignMessage" suivante la copie dans un en-tête nommé "tmode" dans la réponse:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

À propos de la règle ExtractVariables

Les développeurs d'API créent des proxys d'API qui se comportent différemment en fonction du contenu des messages, y compris les en-têtes, les chemins d'URI, les charges utiles et les paramètres de requête. Souvent, le proxy extrait une partie de ce contenu pour l'utiliser dans une instruction de condition. Pour ce faire, utilisez la règle ExtractVariables.

Lors de la définition de la règle ExtractVariables, vous pouvez choisir :

  • Noms des variables à définir
  • Source des variables
  • Nombre de variables à extraire et à définir

Lorsqu'elle est exécutée, la règle applique un modèle de texte au contenu et, lors de la recherche d'une correspondance, définit la valeur de la variable désignée avec le contenu. D'autres règles et codes peuvent ensuite utiliser ces variables pour activer un comportement dynamique ou envoyer des données d'entreprise à Edge API Analytics.

Pour savoir comment utiliser ExtractVariables pour créer des rapports Analytics axés sur le contenu, consultez Analyser le contenu des messages de l'API à l'aide d'analyses personnalisées.

Définition du champ d'application

Les variables définies avec la règle ExtractVariables ont un champ d'application global. En d'autres termes, une fois que la règle ExtractVariables a défini une nouvelle variable, vous pouvez y accéder depuis n'importe quelle règle ou code et à n'importe quelle étape du flux (qui s'exécute après la règle ExtractVariables). Par exemple :

  • PreFlow : ProxyEndpoint et TargetEndpoint (requête et réponse)
  • PostFlow : ProxyEndpoint et TargetEndpoint (requête et réponse)
  • PostClientFlow : ProxyEndpoint (réponse uniquement, au moyen de l'aide de la règle Message Logging)
  • Flux d'erreurs

À propos de la correspondance et de la création de variables

La règle ExtractVariables extrait les informations d'une requête ou d'une réponse et les écrit dans une variable. Pour chaque type d'information que vous pouvez extraire, par exemple le chemin d'URI ou les données XML, spécifiez le modèle à mettre en correspondance, ainsi que le nom de la variable utilisée pour stocker les informations extraites.

Cependant, le fonctionnement de la correspondance de modèles dépend de la source de l'extraction. Les sections suivantes décrivent les deux catégories d'informations de base que vous pouvez extraire.

Mise en correspondance de chemins d'URI, de paramètres de requête, d'en-têtes, de paramètres de formulaire et de variables

Lorsque vous extrayez des informations à partir d'un chemin d'URI, de paramètres de requête, d'en-têtes, de paramètres de formulaire et de variables, vous utilisez le tag <Pattern> pour spécifier un ou plusieurs modèles à mettre en correspondance. L'exemple de règle suivant affiche un seul modèle de correspondance pour le chemin d'URI :

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Dans cet exemple, la variable urirequest.pathSeg est définie sur tout ce qui apparaît dans proxy.pathsuffix après "/a/". Par exemple, supposons que le chemin de base de votre proxy d'API est /basepath/v1 . Avec une requête entrante vers http://myCo.com/basepath/v1/a/b, la variable est définie sur "b".

Spécifier plusieurs modèles

Vous pouvez spécifier plusieurs modèles à mettre en correspondance, correspondant aux tags <Pattern>, où :

  • Tous les modèles sont testés pour vérifier leur correspondance.
  • Si aucun des formats ne correspond, la règle ne fait rien et la ou les variables ne sont pas créées.
  • Si plusieurs modèles correspondent, celui qui possède aux segments de chemin d'accès les plus longs est utilisé pour l'extraction.
  • Si deux  modèles correspondant aux mêmes segments de chemin sont les plus longs, le modèle spécifié en premier dans la règle est utilisé pour l'extraction.

Dans l'exemple suivant, vous allez créer une règle contenant trois formats correspondants au chemin de l'URI :

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supposons, pour un proxy d'API et un chemin de base /basepath/v1, que l'URL de requête entrante adressée au proxy d'API se présente comme suit :

http://myCo.com/basepath/v1/a/b

Dans cet exemple, le premier modèle correspond à l'URI et la variable urirequest.pathSeg est définie sur "b".

Si l'URL de la requête est :

http://myCo.com/basepath/v1/a/b/c/d

…le troisième modèle correspond et la variable urirequest.pathSeg est définie sur "d".

Spécifier des modèles avec plusieurs variables

Vous pouvez spécifier plusieurs variables dans le modèle correspondant. Par exemple, vous pouvez spécifier un modèle correspondant avec deux variables :

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

À nouveau, supposons un proxy d'API et un chemin de base /basepath/v1. Pour l'URL de requête entrante :

http://myCo.com/basepath/v1/a/b/c/d

…la variable urirequest.pathSeg1 est définie sur "b" et la variable urirequest.pathSeg2 est définie sur "d".

Mise en correspondance de plusieurs instances dans le modèle

Vous pouvez également faire correspondre des modèles lorsque plusieurs instances d'un élément portent le même nom. Par exemple, vous pouvez envoyer une requête contenant plusieurs paramètres de requête ou plusieurs en-têtes portant le même nom. La requête suivante contient deux paramètres de requête nommés "w" :

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

Pour référencer ces paramètres de requête dans la règle ExtractVariables, vous utilisez des index, où la première instance du paramètre de requête ne comporte pas d'index, la seconde se situe à l'index 2, la troisième à l'index 3, etc. Par exemple, la règle suivante extrait la valeur du deuxième paramètre de requête nommé "w" dans la requête :

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <QueryParam name="w.2">
      <Pattern ignoreCase="true">{secondW}</Pattern>
   </QueryParam>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

La variable urirequest.secondW est définie sur "2". Si le deuxième paramètre est omis de la requête, la variable urirequest.secondW est vide. Utilisez l'indexation chaque fois que plusieurs éléments portent le même nom dans la requête.

Utiliser des caractères spéciaux dans le modèle

Lors de la mise en correspondance des chemins d'URI, vous pouvez utiliser les caractères génériques "*" et "**" dans le modèle, où :

  • "*" correspond à n'importe quel segment du chemin
  • "**" correspond à plusieurs segments du chemin

Par exemple, vous spécifiez des modèles pour l'élément <URIPath> comme indiqué ci-dessous :

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

Le premier modèle correspond aux requêtes comportant des suffixes de chemin (partie du chemin d'URI qui suit le chemin de base) tels que "/a/b/c", "/a/foo/bar", etc. Le second modèle correspond à n'importe quel nombre de segments de chemin d'accès après "/a/", par exemple "/a/foo/bar/baz/c", ainsi que "/a/b/c" et "/a/foo/bar".

Lorsque vous spécifiez des modèles de requêtes de paramètres, d'en-têtes et de paramètres de formulaire, le caractère "*" correspond à n'importe quel nombre de caractères. Par exemple, pour établir une correspondance avec un en-tête, spécifiez le modèle comme suit :

*; charset={encoding}

Ce modèle correspond aux valeurs "text/xml;charset=UTF-16" et "application/xml;charset=ASCII".

Si la valeur transmise à la règle ExtractVariables contient un caractère spécial, tel que "{", utilisez le caractère "%" pour l'échapper. L'exemple suivant échappe les caractères "{" et"}" dans le modèle, car ils sont utilisés en tant que caractères littéraux dans la valeur du paramètre de requête :

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

Dans cet exemple, le modèle correspond à la valeur "{user} Steve", mais pas à la valeur "user Steve".

Mise en correspondance de JSON et XML

Lorsque vous extrayez des données JSON et XML, vous spécifiez un ou plusieurs tags <Variable> dans la règle. Le tag <Variable> spécifie le nom de la variable de destination où les informations extraites sont stockées, et les éléments JsonPath (JSON) ou XPATH (XML), les informations extraites.

Tous les tags <Variable> de la règle sont évalués, ce qui vous permet d'insérer plusieurs variables à partir d'une seule règle. Si le tag <Variable> ne renvoie pas un champ valide dans le fichier JSON ou XML, la variable correspondante n'est pas créée.

L'exemple suivant illustre une règle ExtractVariables qui insère deux variables à partir du corps JSON d'une réponse :

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

Écrire dans la même variable à plusieurs emplacements

Soyez prudent lorsque vous choisissez les noms des variables à définir. La règle s'exécute de manière séquentielle du premier modèle d'extraction vers le dernier. Si la règle écrit une valeur dans la même variable à partir de plusieurs emplacements, la dernière écriture dans la règle détermine la valeur de la variable. (Il peut s'agir d'un choix volontaire.)

Par exemple, vous souhaitez extraire une valeur de jeton pouvant être transmise dans un paramètre de requête ou dans un en-tête, comme indiqué ci-dessous :

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

Contrôler les étapes suivantes lorsqu'aucune correspondance n'est trouvée

Si le modèle ne correspond pas, la variable correspondante n'est pas créée. Par conséquent, si une autre règle fait référence à la variable, elle peut générer une erreur.

Une option consiste à définir <IgnoreUnresolvedVariables> sur "true" dans une règle qui fait référence à la variable afin de configurer la règle pour qu'elle traite une variable non résolue comme une chaîne vide (null) :

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Documentation de référence des éléments

La référence d'élément décrit les éléments et les attributs de la règle ExtractVariables.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName>Extract Variables 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

Attributs <ExtractVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut Description Par défaut Présence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

N/A Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle.

false Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

true Facultatif
async

Cet attribut est obsolète.

false Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Présence Facultatif
Type Chaîne

Élément <Source>

(Facultatif) Indique la variable à analyser. La valeur <Source> est définie sur message par défaut. La valeur message est sensible au contexte. Dans un flux de requête, message renvoie le message de requête. Dans un flux de réponse, message renvoie le message de réponse.

Cette règle sert souvent à extraire des informations d'un message de requête ou de réponse, mais vous pouvez l'utiliser pour extraire des informations de n'importe quelle variable. Par exemple, elle vous permet d'extraire des informations d'une entité créée par la règle AccessEntity à partir de données renvoyées par la règle d'appel de service, ou d'extraire des informations d'un objet XML ou JSON.

Si <Source> ne peut être résolu ou est associé à un type qui n'est pas un message, la règle ne produira aucune réponse.

<Source clearPayload="true|false">request</Source>
Valeur par défaut : Message
Présence : Facultatif
Type : Chaîne

Attributs

Attribut Description Par défaut Présence Type
clearPayload

Définissez la valeur sur true si vous souhaitez effacer la charge utile spécifiée par <Source> après en avoir extrait les données.

N'utilisez l'option <clearPayload> que si le message source n'est pas requis après l'exécution d'ExtractVariables. La définir sur true libère la mémoire utilisée par le message.

false

Facultatif Booléen

Élément <VariablePrefix>

(Facultatif) Le nom complet de la variable est créé en associant <VariablePrefix>, un point et le nom que vous définissez entre {accolades} dans l'élément <Pattern> ou <Variable>. Par exemple, myprefix.id, myprefix.dbncode ou myprefix.oauthtoken..

<VariablePrefix>myprefix</VariablePrefix>

Par exemple, supposons que la valeur du nom soit "user".

  • Si <VariablePrefix> n'est pas spécifié, les valeurs extraites sont attribuées à une variable nommée user.
  • Si <VariablePrefix> est spécifié sous la forme "myprefix", les valeurs extraites sont attribuées à une variable nommée myprefix.user.
Valeur par défaut : N/A
Présence : Facultatif
Type : Chaîne

Élément <IgnoreUnresolvedVariables>

(Facultatif) Définissez la valeur sur true pour traiter toute variable non résolue comme une chaîne vide (null). Définissez la valeur sur false si vous souhaitez que la règle génère une erreur lorsqu'une variable référencée ne peut être résolue.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Valeur par défaut : Faux
Présence : Facultatif
Type : Booléen

Si une référence XPath n'est pas résolue dans une <XMLPayload>, la stratégie génère l'erreur suivante:

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

Élément <URIPath>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Extrait une valeur du paramètre proxy.pathsuffix d'un message source de requête. Le chemin appliqué au modèle est proxy.pathsuffix, qui n'inclut pas le chemin de base du proxy API. Si le message source renvoie à un type de message response, cet élément n'a aucun effet.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

Il est possible d'utiliser plusieurs éléments <Pattern> :

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
ignoreCase Spécifie si la casse doit être ignorée lors de la mise en correspondance du modèle.

false

Facultatif Booléen

Élément <QueryParam>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Extrait une valeur à partir du paramètre de requête spécifié d'un message source de requête. Si le message source correspond à un type de message de réponse, cet élément n'effectue aucune action.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

Si plusieurs paramètres de requête portent le même nom, utilisez des index pour les référencer :

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
nom Spécifie le nom du paramètre de requête. Si plusieurs paramètres de requête portent le même nom, utilisez le référencement indexé où la première instance du paramètre de requête n'a pas d'index, la deuxième correspond à l'index 2, la troisième à l'index 3, etc.

N/A

Obligatoire Chaîne

Élément <Header>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Extrait une valeur de l'en-tête HTTP spécifié du message request ou response spécifié. Si plusieurs en-têtes portent le même nom, leurs valeurs sont stockées dans un tableau.

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

Si plusieurs en-têtes portent le même nom, utilisez des index pour référencer des en-têtes spécifiques du tableau :

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

La commande suivante permet d'obtenir la liste tous les en-têtes du tableau :

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
name Spécifie le nom de l'en-tête à partir duquel extraire la valeur. Si plusieurs en-têtes portent le même nom, utilisez le référencement indexé où la première instance de l'en-tête n'a pas d'index, la deuxième correspond à l'index 2, la troisième à l'index 3, etc. Utilisez .values pour obtenir tous les en-têtes du tableau.

N/A

Obligatoire Chaîne

Élément <FormParam>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Extrait une valeur du paramètre de formulaire spécifié du message request ou response spécifié. Les paramètres de formulaire ne peuvent être extraits que lorsque l'en-tête Content-Type du message spécifié est application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
nom Nom du paramètre de formulaire à partir duquel extraire la valeur.

N/A

Obligatoire Chaîne

Élément <Variable>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Spécifie le nom d'une variable à partir de laquelle extraire une valeur.

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

Pour extraire deux valeurs de la variable, procédez comme suit :

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
nom Nom de la variable à partir de laquelle extraire la valeur.

N/A

Obligatoire Chaîne

Élément <JSONPayload>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Spécifie le message au format JSON dont la valeur de la variable sera extraite. L'extraction JSON n'est effectuée que lorsque l'en-tête Content-Type du message correspond à application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Élément <JSONPayload>/<Variable>

(Obligatoire dans l'élément JSONPayload). Spécifie la variable à laquelle la valeur extraite est attribuée. Vous pouvez inclure plusieurs balises <Variable> dans l'élément <JSONPayload> pour renseigner plusieurs variables.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>
Valeur par défaut : N/A
Présence : Obligatoire dans l'élément JSONPayload.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
nom

Spécifie le nom de la variable à laquelle la valeur extraite sera attribuée.

nom

Valeur Chaîne
type Spécifie le type de données de la valeur de la variable. N/A Facultatif

Chaîne. Sélectionnez parmi :

  • chaîne
  • boolean
  • entier
  • long
  • float
  • double
  • nodeset (renvoie un fragment JSON)

Élément <JSONPayload>/<Variable>/<JSONPath>

(Obligatoire dans l'élément JSONPayload:Variable). Spécifie le chemin JSON utilisé pour extraire une valeur d'un message au format JSON.

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
Valeur par défaut : N/A
Présence : Obligatoire
Type : Chaîne

Élément <XMLPayload>

(Facultatif ; consultez toutefois la ligne "Présence" du tableau ci-dessous pour en savoir plus.) Spécifie le message au format XML dont la valeur de la variable sera extraite. Les charges utiles XML ne sont extraites que lorsque l'en-tête Content-Type du message est text/xml, application/xml ou application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Valeur par défaut : N/A
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
stopPayloadProcessing

Définissez la valeur sur true pour arrêter l'évaluation XPath après l'insertion d'une variable. Cela signifie que la règle n'insère qu'une seule variable.

false

Facultatif Booléen

Élément <XMLPayload>/<Namespaces>

(Facultatif) Spécifie l'espace de noms à utiliser pour l'évaluation XPath. Si vous utilisez des espaces de noms dans vos expressions XPath, vous devez les déclarer ici, comme illustré dans l'exemple suivant.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

Si vous n'utilisez pas d'espaces de noms dans vos expressions XPath, vous pouvez omettre ou commenter l'élément <Namespaces>, comme illustré par l'exemple suivant :

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>
Valeur par défaut : N/A
Présence : Facultatif
Type : Chaîne

Attributs

Attribut Description Par défaut Présence Type
prefix

Préfixe d'espace de noms.

N/A

Obligatoire Chaîne

Élément <XMLPayload>/<Variable>

(Facultatif) Spécifie une variable à laquelle la valeur extraite sera attribuée.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>
Valeur par défaut : N/A
Présence : Facultatif
Type : N/A

Attributs

Attribut Description Par défaut Présence Type
nom

Spécifie le nom de la variable à laquelle la valeur extraite sera attribuée.

nom

Valeur Chaîne
type Spécifie le type de données de la valeur de la variable. Booléen Facultatif

Chaîne. Sélectionnez parmi :

  • chaîne
  • boolean
  • entier
  • long
  • float
  • double
  • nodeset (renvoie un fragment XML)

Élément <XMLPayload>/<Variable>/<XPath>

(Obligatoire dans l'élément XMLPayload:Variable). Spécifie le chemin XPath défini pour la variable. Seules les expressions XPath 1.0 sont acceptées.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

Exemple avec un espace de noms. Si vous utilisez des espaces de noms dans vos expressions XPath, vous devez les déclarer dans la section <XMLPayload><Namespaces> de la stratégie.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>
Valeur par défaut : N/A
Présence : Obligatoire
Type : Chaîne

Informations de référence sur les erreurs

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.extractvariables.ExecutionFailed 500

This error occurs when:

  • The input payload (JSON, XML) is empty.
  • The input (JSON, XML, etc) passed to the policy is invalid or malformed.
steps.extractvariables.ImmutableVariable 500 A variable used in the policy is immutable. The policy was unable to set this variable.
steps.extractvariables.InvalidJSONPath 500 This error occurs if an invalid JSON path is used in the JSONPath element of the policy. For example, if a JSON payload does not have the object Name, but you specify Name as the path in the policy, then this error occurs.
steps.extractvariables.JsonPathParsingFailure 500 This error occurs when the policy is unable to parse a JSON path and extract data from the flow variable specified in Source element. Typically this happens if the flow variable specified in the Source element does not exist in the current flow.
steps.extractvariables.SetVariableFailed 500 This error occurs if the policy could not set the value to a variable. The error generally happens if you try to assign values to multiple variables whose names start with the same words in a nested dot-separated format.
steps.extractvariables.SourceMessageNotAvailable 500 This error occurs if the message variable specified in the Source element of the policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)
steps.extractvariables.UnableToCast 500 This error occurs if the policy was unable to cast the extracted value to a variable. Typically this happens if you attempt to set the value of one data type to a variable of another data type.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
NothingToExtract If the policy does not have any of the elements URIPath, QueryParam, Header, FormParam, XMLPayload, or JSONPayload, the deployment of the API Proxy fails, because there's nothing to extract.
NONEmptyPrefixMappedToEmptyURI This error occurs if the policy has a prefix defined in the Namespace element under the XMLPayload element, but no URI is defined.
DuplicatePrefix This error occurs if the policy has the same prefix defined more than once in the Namespace element under the XMLPayload element.
NoXPathsToEvaluate If the policy does not have the XPath element within the XMLPayload element, then the deployment of the API proxy fails with this error.
EmptyXPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
NoJSONPathsToEvaluate If the policy does not have the JSONPath element within the JSONPayload element, then the deployment of the API proxy fails with this error.
EmptyJSONPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
MissingName If the policy does not have the name attribute in any of the policy elements like QueryParam, Header, FormParam or Variable, where it is required, then the deployment of the API proxy fails.
PatternWithoutVariable If the policy does not have a variable specified within the Pattern element, then the deployment of the API proxy fails. The Pattern element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset If the policy has an XPath expression where the Variable type is defined as nodeset, but the expression cannot be converted to nodeset, then the deployment of the API proxy fails.
JSONPathCompilationFailed The policy could not compile a specified JSON Path.
InstantiationFailed The policy could not be instantiated.
XPathCompilationFailed If the prefix or the value used in the XPath element is not part of any of the declared namespaces in the policy, then the deployment of the API proxy fails.
InvalidPattern If the Pattern element definition is invalid in any of the elements like URIPath, QueryParam, Header, FormParam, XMLPayload or JSONPayload within the policy, then the deployment of the API proxy fails.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. extractvariables.EV-ParseJsonResponse.failed = true

Example error response

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

Example fault rule

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

Schémas

Articles associés

Analyser le contenu du message de l'API à l'aide de données analytiques personnalisées

Documentation de référence sur les variables