Was this helpful?

Overview of the ExtractVariables policy

API Developers build policies that behave differently based on the content of messages, including headers, URI paths, payloads, and query parameters.

Often, API Developers will want to extract some portion of a message, or of a header, so that they can use that extracted portion in a condition statement. The ExtractVariables policy does this. It applies a text pattern to some part of the message - the body or header or URL path or a query parameter - and on finding a match, sets a designated variable with the appropriate content.

Other policies and code can then consume those variables to enable dynamic behavior or to send business data to Analytics Services.

To see how ExtractVariables can be used to build content-driven Analytics reports, see Analyze API message content using custom analytics.

Apigee Edge sets numerous variables automatically during request processing. See Variables reference. Use the ExtractVariables policy to set additional variables, with values derived from message content.

Need policy XML details? See ExtractVariables policy.

Need policy error codes? See Error Codes for the ExtractVariables policy.

Examples

As a policy designer, you choose the names of the variables to be set by the ExtractVariables policy. You choose the source of the variable, and how many variables to extract and set.

To see how the policy works, let's look at some examples.

Extract a portion of the URL path into a variable

Consider this sample policy:

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

Now, with an incoming request like this:

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

...when Apigee Edge applies that policy, it sets the variable urirequest.id to the value 12797282.

The name of the variable to be set is determined by the value specified in the <VariablePrefix> element, as well as the name within curly braces in the pattern. The two are joined with an intervening dot, so that the resulting variable name is urirequest.id. If there is no <VariablePrefix> element, then the variable names are just those specified within the curly braces.

The <URIPath> element tells the ExtractVariables policy to extract information from the URI path. The <Pattern> element specifies the pattern to apply to the URI path. The pattern is treated as a simple template; curly braces denote the varying portion of the URI path, and the term within the curly braces indicates the variable suffix.

After Apigee Edge executes this ExtractVariables policy, subsequent policies or code in the processing flow can refer to the variable named urirequest.id to get the string value 12797282.

Extract a variable from a query parameter

Consider another example. Suppose that your API design stipulates that incoming requests must carry a query paramter named code which holds a term that looks like DBNXXXXX, where DBN is fixed, and the XXXXX denotes a varying string. You could use this policy to extract the varying string:

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

Assuming that policy, with an incoming request like this:

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

...Apigee Edge will set the variable queryinfo.dbncode to the value 88271.

After Apigee Edge executes this ExtractVariables policy, subsequent policies or code in the processing flow can refer to the variable named queryinfo.dbncode to get the string value 88271.

Extract a variable from a Header

Here's a common case. Suppose your API uses OAuth v2.0 Bearer tokens. A request carrying an OAuth v2.0 token includes a header like this:

Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM

Suppose you, the API designer, would like to use the token value, not the entire header, as a key in a cache lookup. You could use this policy to extract the token:

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

With that policy, and the token provided above, Apigee Edge will set the variable clientrequest.oauthtoken to the value TU08xptfFfeM7aS0xHqlxTgEAdAM.

Extract variables from a JSON payload

The ExtractVariables policy can also extract values from more complicated structures, like JSON messages. This example shows how to extract a variable from a portion of a JSON message payload. Consider this response payload:

{
  "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
        }
      }
    }
  }]
}

An element in the ExtractVariables policy tells it to extract from a JSON payload. Rather than using text patterns, as you would when extracting values from headers, URI paths or query parameters, with JSON specify the portion to extract via a JSON path expression in which the $ character refers to the root node of the JSON. Here's an example policy to illustrate:

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

With this policy applied to the above message, Apigee Edge will set two variables. The variable geocoderesponse.latitude gets the value 37.42291810. The variable geocoderesponse.longitude gets the value -122.08542120. Both use the same variable prefix of geocoderesponse. Notice that the suffix for these variables is specified explicitly, in the <Variable> element.

Extract variables from an XML message

Similarly, you can extract variables from an XML payload, using XPath and explicitly named variables. Consider this payload:

<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>
</DirectionsResponse>

With this policy:

<ExtractVariables name="ExtractVariables-4">
  <Source>response</Source>
  <VariablePrefix>directionsresponse</VariablePrefix>
  <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>
</ExtractVariables>

...Apigee Edge will set three variables in the message context. The variable directionsresponse.travelmode gets the value DRIVING. The variable directionsresponse.duration gets the value 19. The variable directionsresponse.timeunit gets the value minutes.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)