Extract message content using ExtractVariables

The ExtractVariables policy type enables you to work with the content of messages as part of policy processing, extracting content from a request or response message, and in turn making that content available as variables to the message flow. By setting variables specific to message content, you can, for example, specify custom, conditional flow behavior based on message content. You can also use such custom variables to populate custom analytics reports. For instructions, see Analyze API message content using custom analytics.

To extract message content, you specify patterns for the API Platform to evaluate at runtime. Patterns can be defined to evaluate:

• URI path
• Query parameter
• Header
• Form parameter

Within the pattern, a variable definition is enclosed in curly braces and follows the basic format:

<Pattern>{variable}</Pattern>

Patterns can be combined and repeated in any order within a single policy.

Two configuration options are provided:

• ignoreCase: Enables case-sensitivity to be toggled on and off
• IgnoreUnresolvedVariables: If set to false, policy execution stops and the transaction enters an error state.

Samples

Extract variable from a URI path

<ExtractVariables name="ExtractURIVariable">
    <DisplayName>Extract Variables Policy for URI extraction</DisplayName>
    <URIPath>
        <Pattern ignoreCase="true">/weather/{uri}</Pattern>
    </URIPath>
    <VariablePrefix>path</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Example:

http://{myorg}-test.apigee.net/weather/forecastrss?w=12797282

Result:

path.uri set to forecastrss

Extract variable from a query parameter

<ExtractVariables name="ExtractQueryParamVariable">
    <DisplayName>Extract Query Parameters</DisplayName>
    <QueryParam name="w">
        <Pattern ignoreCase="true">{location_id}</Pattern>
    </QueryParam>
    <VariablePrefix>queryparam</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Example:

http://{myorg}-test.apigee.net/weather/forecastrss?w=12797282

Result:

queryparam.location_id set to 12797282

A common usage of the Extract Variables policy is parsing message content to populate custom variables. Those custom variables can in turn be used to collect custom analytics, for example.

To parse JSON, use JSONPath:

<ExtractVariables name="ParseGeocodingResponse"> 
<!-- Read response from geocoding service and parse using JSONPath --> 
  <Source>GeocodingResponse</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>

To parse XML, use XPath:

<ExtractVariables name="ParseWeatherReport">
  <Source>WeatherResponse</Source> 
  <VariablePrefix>weather</VariablePrefix>
  <XMLPayload>
    <Namespaces>
      <Namespace prefix="yweather">http://xml.weather.yahoo.com/ns/rss/1.0</Namespace>
    </Namespaces>
    <Variable name="location" type="string">
      	<XPath>/rss/channel/yweather:location/@city</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>

Configuring the Extract Variables policy

You can configure an Extract Variables policy in one of two ways:

• Using the policy editor: Drag and drop the Extract Variable policy onto the message flow in the policy editor and then configure the elements of the policy using the Map view in the policy editor. For more information, see Edit your API proxy. You can also configure the elements using the Code view in the policy editor that allows you to edit the XML fields directly instead of editing them offline. For more information on Code view, see You do not have access to view this node.

• Using your favorite editor or IDE: Export your API proxy. Unzip and open/edit the API proxy configuration files offline in your favorite text editor or IDE. For more information, see Edit API revisions offline.

Configure the Extract Variable policy using the following elements.

Policy schema

Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

Example - Extract Variable policy

<ExtractVariables name="mypolicy">
    <Source>sc.response</Source>
    <VariablePrefix>apigee</VariablePrefix>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>  
    <URIPath>
        <Pattern>/**/hello/{user}</Pattern>
        <Pattern>/**/hi/{user}</Pattern>
    </URIPath>
    <QueryParam name="greeting">
        <Pattern>hello {user}</Pattern>
        <Pattern>hi {user}</Pattern>
    </QueryParam>
    <Header name="greeting">
        <Pattern>hello {user}</Pattern>
        <Pattern>hi {user}</Pattern>
    </Header>
    <FormParam name="greeting">
        <Pattern>hello {user}</Pattern>
        <Pattern>hi {user}</Pattern>
    </FormParam>
    <Variable name="request.content">
        <Pattern>hello {user}</Pattern>
        <Pattern>hi {user}</Pattern>
    </Variable>
    <XMLPayload stopPayloadProcessing="true">
        <Namespaces>
            <Namespace prefix="apigee">http://www.apigee.com</Namespace>
        </Namespaces>
        <Variable name="user" type="string">
            <XPath>/apigee:Greeting/apigee:User</XPath>
        </Variable>
    </XMLPayload>
    <JSONPayload>
        <Variable name="customer" type="string">
            <JSONPath>$.store.book[*].author</JSONPath>
            <JSONPath>$.store.book[?(@.category = 'reference')]</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>