Règle Extract Variables

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Événement

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.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

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.

Exemples

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

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://example.com/svc1/accounts/12797282

Supposons que le chemin de base du proxy d'API soit /svc1. Lorsque Apigee applique le code de la règle ExtractVariables ci-dessus à cette requête entrante, il définit la variable urirequest.id sur 12797282. Une fois qu'Apigee a appliqué la règle, les règles ou le code ultérieurs au sein du 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 AssignMessage 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://example.com/accounts/12797282?code=DBN88271

Lorsque Apigee applique le code de la règle ExtractVariables ci-dessus à cette requête entrante, il définit la variable queryinfo.dbncode sur 88271. Une fois qu'Apigee a appliqué la règle, les règles ou le code ultérieurs au sein du 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 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">
    <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 une règle ExtractVariables pour extraire la valeur de plusieurs instances du paramètre de requête. Pour référencer des paramètres de requête portant le même nom dans la règle, utilisez des 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…

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

GET http://example.com/weather?w=Boston&w=Chicago

Lorsque Apigee applique le code de la 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 aux variables 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 applique le code de la règle ExtractVariables ci-dessus à cet en-tête, il définit 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>

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 applique le code de la règle Extract Variables 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>

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 applique le code de la règle ExtractVariables ci-dessus à ce message XML, il définit trois variables :

  • directionsresponse.travelmode : récupère la valeur DRIVING.
  • directionsresponse.duration : récupère la valeur 19.
  • directionsresponse.timeunit : récupère la valeur minutes.

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

Vous pouvez maintenant accéder à la variable directionresponse.travelmode dans votre proxy. Par exemple, la règle AssignMessage suivante la copie dans un en-tête nommé tmode de 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 le comportement dynamique ou pour envoyer des données d'entreprise à Apigee API Analytics.

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 MessageLogging)
  • 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 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 tous les éléments qui apparaissent dans le fichier proxy.pathsuffix après /a/. Par exemple, supposons que le chemin de base de votre proxy d'API soit /basepath/v1. Pour une requête entrante adressée à 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 modèle ne correspond, la règle n'a aucun effet et les variables ne sont pas créées.
  • Si plusieurs modèles correspondent, celui qui possède les segments de chemin 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 que, pour un proxy d'API avec un chemin de base de /basepath/v1, l'URL de requête entrante adressée au proxy d'API se présente sous la forme suivante :

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 que, pour un proxy d'API avec un chemin de base de /basepath/v1, l'URL de requête entrante se présente sous la forme suivante :

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 de requête 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 pouvez spécifier 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 à partir de 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ù sont stockées les informations extraites, ainsi que le fichier JsonPath (JSON) ou XPATH (XML) vers les informations extraites.

Tous les tags <Variable> de la règle sont évalués ; ainsi, vous pouvez renseigner 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> 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. Voir également :

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

vrai Facultatif
async

Cet attribut est obsolète.

faux 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, vous pouvez l'utiliser pour extraire des informations d'une entité créée par la règle AccessEntity, des données renvoyées par la règle ServiceCallout, ou 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 cet attribut sur true si vous souhaitez effacer la charge utile spécifiée dans <Source> après avoir extrait les données de celle-ci.

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

faux

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>

Supposons, par exemple, 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 : ND
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

É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 request. 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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

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.

faux

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 request. Si le message source correspond à un type de message de response, 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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

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.

ND

Requis 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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

Attributs

Attribut Description Par défaut Présence Type
nom 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.

ND

Requis 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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

Attributs

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

ND

Requis 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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

Attributs

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

ND

Requis 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 est application/json.

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

É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 tags <Variable> dans l'élément <JSONPayload> pour renseigner plusieurs variables.

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

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. ND Facultatif

Chaîne. Sélectionnez parmi :

  • chaîne
  • booléen
  • 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 : ND
Présence : Requis
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 : ND
Présence : Facultatif. Toutefois, vous devez inclure au moins l'un des éléments suivants : <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, ou <XMLPayload>.
Type : ND

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.

faux

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 : ND
Présence : Facultatif
Type : Chaîne

Attributs

Attribut Description Par défaut Présence Type
prefix

Préfixe d'espace de noms.

ND

Requis 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 : ND
Présence : Facultatif
Type : ND

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
  • booléen
  • 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 règle.

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

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause Corriger
steps.extractvariables.ExecutionFailed 500

Cette erreur se produit dans les cas suivants :

  • La charge utile d'entrée (JSON, XML) est vide.
  • L'entrée (JSON, XML, etc.) transmise à la règle est incorrecte ou non valide.
steps.extractvariables.ImmutableVariable 500 Une variable utilisée dans la règle est immuable. La règle n'a pas pu définir cette variable. N/A
steps.extractvariables.InvalidJSONPath 500 Cette erreur se produit si un chemin JSON non valide est utilisé dans l'élément JSONPath de la règle. Par exemple, si une charge utile JSON ne contient pas l'objet Name, mais vous spécifiez Name comme chemin d'accès dans la règle, cette erreur se produit.
steps.extractvariables.JsonPathParsingFailure 500 Cette erreur se produit lorsque la règle ne peut pas analyser un chemin JSON et extraire les données de la variable de flux spécifiée dans l'élément Source. Cela se produit généralement si la variable de flux spécifiée dans l'élément Source n'existe pas dans le flux actuel.
steps.extractvariables.SetVariableFailed 500 Cette erreur se produit si la règle n'a pas pu définir la valeur sur une variable. L'erreur se produit généralement si vous essayez d'attribuer des valeurs à plusieurs variables dont les noms commencent par les mêmes mots dans un format imbriqué, séparés par un point.
steps.extractvariables.SourceMessageNotAvailable 500 Cette erreur se produit si la variable message spécifiée dans l'élément Source de la règle est :
  • hors du champ d'application (non disponible dans le flux spécifique où la règle est exécutée) ou
  • impossible à résoudre (non définie).
steps.extractvariables.UnableToCast 500 Cette erreur se produit si la règle n'a pas pu convertir la valeur extraite en variable. Cela se produit généralement si vous tentez de définir la valeur d'un type de données sur une variable d'un autre type de données.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Cause Corriger
NothingToExtract Si la règle ne comporte aucun des éléments URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload, le déploiement du proxy d'API échoue, car il n'y a rien à extraire.
NONEmptyPrefixMappedToEmptyURI Cette erreur se produit si la règle comporte un préfixe défini dans l'élément Namespace sous l'élément XMLPayload, mais qu'aucun URI n'est défini.
DuplicatePrefix Cette erreur se produit si le même préfixe est défini plusieurs fois dans l'élément Namespace sous l'élément XMLPayload.
NoXPathsToEvaluate Si la règle ne contient pas l'élément XPath au sein de l'élément XMLPayload, le déploiement du proxy d'API échoue avec cette erreur.
EmptyXPathExpression Si la règle contient une expression XPath vide dans l'élément XMLPayload, le déploiement du proxy d'API échoue.
NoJSONPathsToEvaluate Si la règle ne contient pas l'élément JSONPath au sein de l'élément JSONPayload, le déploiement du proxy d'API échoue avec cette erreur.
EmptyJSONPathExpression Si la règle contient une expression XPath vide dans l'élément XMLPayload, le déploiement du proxy d'API échoue.
MissingName Si la règle ne comporte pas l'attribut name dans aucun des ses éléments, tels que QueryParam, Header, FormParam ou Variable, le cas échéant, le déploiement du proxy d'API échoue.
PatternWithoutVariable Si la règle ne comporte aucune variable spécifiée dans l'élément Pattern, le déploiement du proxy d'API échoue. L'élément Pattern requiert le nom de la variable dans laquelle les données extraites seront stockées.
CannotBeConvertedToNodeset Si la règle contient une expression XPath où le type Variable est défini sur nodeset, mais que l'expression ne peut pas être convertie en ensemble de nœuds, le déploiement du proxy d'API échoue.
JSONPathCompilationFailed La règle n'a pas pu compiler un chemin JSON spécifié. N/A
InstantiationFailed Impossible d'instancier la règle. N/A
XPathCompilationFailed Si le préfixe ou la valeur utilisée dans l'élément XPath ne fait partie d'aucun des espaces de noms déclarés dans la règle, le déploiement du proxy d'API échoue.
InvalidPattern Si la définition de l'élément Pattern est non valide dans les éléments tels que URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload contenus dans la règle, le déploiement du proxy d'API échoue.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. extractvariables.EV-ParseJsonResponse.failed = true

Exemple de réponse d'erreur

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

Exemple de règle de défaillance

<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

Documentation de référence sur les variables de flux