Was this helpful?

As an API developer, you often need access to the content of messages flowing through your API proxies. Apps and APIs exchange messages in JSON or XML, and it is often necessary to parse those payloads for business-specific information. Transport-level information, such as HTTP headers and query parameters, is also often needed to implement custom behavior.

The ExtractVariables policy type enables API proxies to work with the content of both request and response messages. The ExtractVariables policy parses request or response messages and makes message content available as variables. 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.)

For working sample of the ExtractVariables policy, see the variables sample proxy in the API Platform samples on GitHub.

To extract message content, you specify patterns for Apigee Edge to evaluate at runtime. Patterns can be defined to evaluate:

  • URI paths
  • Query parameters
  • HTTP Headers
  • Form parameters

You define evaluation patterns using the Pattern element. The basic format of a Pattern is:

<Pattern>{variable}</Pattern>

You can give variables any name you want, but the variable name must always be enclosed in curly braces, {}, in the Pattern definition. The complete variable name is created by combing the VariablePrefix with the name you define in curly braces in the Pattern element.

Apigee Edge defines a set of predefined variables. You only need to to use the ExtractVariables policy for message content that is not automatically populated by Apigee Edge. These predefined variables have reserved names. See Variables reference.

Two configuration options are provided for the ExtractVariables policy:

  • ignoreCase: Enables case-sensitivity to be toggled on and off
  • IgnoreUnresolvedVariables: This setting provides control over the behavior of a policy when a variable cannot be resolved. If set to false, the execution of the policy results in an error if the variable specified cannot be resolved. Set this to true when resolution of variables is not critical to transaction success, for example, when using custom variables to feed Analytics reports.

Samples

As an example, imagine that you need to implement some custom functionality based on the URI associated with a request message. You might need to peform a call out or route a request dynamically based on the URI path associted with the request message. You can do this by using the ExtractVariables policy to look for patterns in request elements.

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

For the following request path, a variable named path.uri is populated with the value forecastrss.

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

The VariablePrefix element is important; it defines the base name of the variable that is populated. In the example above, the variable prefix is path. Note the Pattern element, which indicates which value should be extracted from the request property, and it also provides a name for the variable. By combining this name with the VariablePrefix, the complete path of the variable is defined. In this case, the variable is path.uri. Now other policies or code in the processing Flow can look up this value as the path.uri variable. The variable's value will be set for each request that is received by your API.

The following example extracts a 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:

The variable queryparam.location_id is populated with the value 12797282

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

ExtractVariables is often used to parse JSON responses. To parse JSON, use JSONPath as follows:

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

ExtractVariables is also often used to parse XML responses. To parse XML, use XPath as follows:

<ExtractVariables name="ParseWeatherReport">
  <Source>response</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 ExtractVariables policy

Configure the Extract Variable policy using the following elements.

Field Name Description
Source (Optional)

Specifies the message to be parsed. The value of source defaults to message. The message value is context-sensitive.

In a request Flow, message resolves to the request message. In a response Flow, message resolves to the response message.

  • For example, <Source>message</Source>
  • If the source variable cannot be resolved, or resolves to a non-message type, the policy fails to respond.
  • In advanced configurations, source can resolve to a variable containing a message generated by another policy.
VariablePrefix (Optional) Prefix assigned to the variable that will be created to hold the value of the variable extracted from the message. Prefixes enable you to create naming conventions for custom variables.
IgnoreUnresolvedVariables (Optional)

If IgnoreUnresolvedVariables is set to false, and any variable is unresolvable, the policy throws an error.

If IgnoreUnresolvedVariables is set to true, and any variable is unresolvable, it is treated as empty string (null).

Valid values: true/false
Default value: false
pattern locations (Optional) URIPath Extracts the value of a variable from the specified URI path of the specified message.
QueryParam Extracts the value of a variable from the specified query parameter of the specified message.
Header Extracts the value of a variable from the specified HTTP header of the specified message.
FormParam Extracts the value of a variable from the specified form parameter. Note that FormParams can be extracted only when the contentType of the specified message is application/x-www-form-urlencoded.
Variable Extracts the value of a variable from another specified variable.
XMLPayload (Optional) Namespaces Specifies the namespace to be used in the XPath evaluation. Note that the XML payloads are extracted only when the contentType of message is text/xml, application/xml or application/*+xml.
Variable name
Specifies the name of the variable to which the extracted value will be assigned. (This value will be appended to any VariablePrefix that you specify to create a prefix.name scheme.)
In the example below:
  • if <VariablePrefix> is not specified, the extracted values are assigned to user.
  • If <VariablePrefix> is specified as MyVariable, the extracted values are assigned to MyVariable.user.
type

Specifies the data type of the variable value, default is string.

Supported data types:

  • string
  • boolean
  • integer
  • long
  • float
  • double
  • nodeset (returns an XML fragment)
XPath Specifies the XPath defined for the variable. Only XPath 1.0 expressions are supported.
stopPayloadProcessing
When true, stops XPath evaluation.
Valid values: true/false
Default value: false
JSONPayload (Optional) Variable JSONPath Specifies the JSONPath used to extract the value of a variable from a JSON-formatted message. Note that the JSON payloads are extracted only when the contentType of message is application/json.
name
Specifies the name of the variable where the extracted value will be assigned.
In the example below:
  • If <VariablePrefix> is not specified, the extracted values are assigned to customer.
  • If <VariablePrefix> is specified as MyVariable, the extracted values are assigned to MyVariable.customer.

Policy-specific error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The ExtractVariables Policy type defines the following error codes:

Error Code Message
NothingToExtract ExtractVariables {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
NONEmptyPrefixMappedToEmptyURI ExtractVariables {0}: Non-empty prefix {1} cannot be mapped to empty uri
DuplicatePrefix ExtractVariables {0}: Duplicate prefix {1}
NoXPathsToEvaluate ExtractVariables {0}: no xpaths to evaluate in variable {1}
EmptyXPathExpression ExtractVariables {0}: XPath expression is empty in variable {1}
NoJSONPathsToEvaluate ExtractVariables {0}: no jsonpaths to evaluate in variable {1}
EmptyJSONPathExpression ExtractVariables {0}: JSONPath expression is empty in variable {1}
MissingName ExtractVariables {0}: Required attribute name is missing in {1}
InstantiationFailed Failed to instantiate the ExtractVariables stepDefinition {0}
ExecutionFailed Failed to execute the ExtractVariables: {0}
SetVariableFailed Failed to set variable {0} value {1} from ExtractVariables: {2}
ImmutableVariable Variable {0} is immutable from ExtractVariables: {1}
InvalidPattern Pattern {0} is invalid in ExtractVariables stepDefinition {1}
PatternWithoutVariable Pattern {0} should have atleast one variable in ExtractVariables stepDefinition {1}
NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable {0} message is not available for ExtractVariable: {1}
VariableResolutionFailed Failed to resolve variable {0}
CannotBeConvertedToNodeset ExtractVariables {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
XPathCompilationFailed ExtractVariables {0}: Failed to compile xpath {1}. Context {2}
JSONPathCompilationFailed ExtractVariables {0}: Failed to compile jsonpath {1}. Context {2}
UnsupportedOperation ExtractVariables {0}: Unsupported operation for flow variables {1}
JsonPathParsingFailure ExtractVariables {0}: Json path parsing failed for for flow variables {1}
InvalidJSONPath Invalid JSON path {0} in policy {1}.
UnableToCast Unable to cast value {0} as {1}.

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

コメント

I tried the extract query params example exactly as given and got nothing. No extraction of the query param 'w' from the request.

Hi, can you post your question to the support site: http://community.apigee.com/content/apigee-customer-support.
Thanks

When I tried to extract QueryParam giving value in VariablePrefix element as "queryparam", the variable was not displayed in variable set. And then I removed the variableprefix and it displayed the variable w with its value.

Hi Nisarg - Please post your question to http://community.apigee.com/content/apigee-customer-support. Thanks.

Is extract variable for parsing of JSON only applicable to responses or can it be applied to request bodies as well?

Sorry for the delay! ExtractVariable can be used to extract content from request and response payloads. The policy works the same each way.

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.