This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The ExtractVariables policy extracts content from a request or response and sets the value of a variable to that content. You can extract any part of the message, including headers, URI paths, JSON/XML payloads, form parameters, and query parameters. The policy works by applying a text pattern to the message content and, upon finding a match, sets a variable with the specified message content.

You can also use this policy to extract information from other sources, such as entities created by theAccessEntity policy, XML objects, or JSON objects.

After extracting the specified message content, you can reference the variable in other policies as part of processing a request and response. For example, you could add theRaiseFault policy to return an error if the extracted value is invalid.

When defining the ExtractVariables policy, you can choose:

• Names of the variables to be set
• Source of the variables
• How many variables to extract and set

When executed, the policy applies a text pattern to the content and, upon finding a match, sets the value of the designated variable with the content. Other policies and code can then consume those variables to enable dynamic behavior or to send business data to Apigee API Analytics.

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Samples

These policy code samples illustrate how to extract variables from the following types of artifacts:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Variable Scope

Variables set with the ExtractVariables policy haveglobal scope. That is, after the ExtractVariables policy defines a new variable, you can access that variable from any policy or code in any stage of the flow that executesafter the ExtractVariables policy. This includes:

• PreFlow: ProxyEndpoint and TargetEndpoint (Request and Response)
• PostFlow: ProxyEndpoint and TargetEndpoint (Request and Response)
• PostClientFlow: ProxyEndpoint (Response only, using theMessageLogging policy>)
• Error Flows

Matching and variable creation

The ExtractVariables policy extracts information from a request or response and writes that information to a variable. For each type of information that you can extract, such as URI path or XML data, you specify the pattern to match and the name of the variable used to hold the extracted information.

However, the way pattern matching works depends on the source of the extraction. The following sections describe the two basic categories of information that you can extract.

Matching URI paths, query parameters, headers, form parameters, and variables

When extracting information from a URI path, query parameters, headers, form parameters, and variables you use the<Pattern> tag to specify one or more patterns to match. For example, the following policy example shows a single matching pattern for the URI path:

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

In this example, theurirequest.pathSeg variable is set to whatever appears in the proxy.pathsuffix after/a/. For example, suppose the base path for your API Proxy is/basepath/v1 . With an inbound request tohttp://myCo.com/basepath/v1/a/b the variable is set tob.

Specifying multiple patterns

You can specify multiple patters to match, corresponding to<Pattern> tags, where:

• All patterns are tested for match.
• If none of the patterns match, the policy does nothing and the variable(s) is not created.
• If more than one pattern matches, the pattern with longest path segments is used for extraction.
• If two matched patterns has same longest path segments, then the pattern specified first in the policy is used for extraction.

In the next example, you create a policy that contains three matching patterns for the URI path:

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

Suppose, for an API Proxy with a basepath of/basepath/v1 , the inbound request URL to the API proxy is of this form:

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

In this example, the first pattern matches the URI and theurirequest.pathSeg variable is set tob.

If the request URL is:

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

...then the third pattern matches and theurirequest.pathSeg variable is set tod.

Specifying patterns with multiple variables

You can specify multiple variables in the matching pattern. For example, you specify a matching pattern with two 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>

Again supposing an API Proxy with a base path of/basepath/v1 , for the inbound request URL:

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

...theurirequest.pathSeg1 variable is set tob and theurirequest.pathSeg2 variable is set tod.

Matching multiple instances in the pattern

You can also match patterns when there are multiple instances of an item with the same name. For example, you can make a request that contains multiple query parameters or multiple headers with the same name. The following request contains two query parameters named "w":

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

To reference these query parameters in the ExtractVariables policy, you use indexes, where the first instance of the query parameter has no index, the second is at index 2, the third at index 3, etc. For example, the following policy extracts the value of the second query parameter named "w" in the request:

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

Theurirequest.secondW variable is set to "2". If the second query parameter is omitted from the request, then theurirequest.secondW variable is empty. Use indexing any time there are multiple items with the same name in the request.

Using special characters in the pattern

When matching URI paths, you can use the "*" and "**" wildcard characters in the pattern, where:

• "*" matches any one segments of the path
• "**" matches multiple segments of the path

For example, you specify patterns to the<URIPath> element as shown below:

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

The first pattern matches requests with pathsuffixes (the portion of the URI path following the basepath) such as "/a/b/c", "/a/foo/bar", etc. The second pattern matches any number of path segments after "/a/", such as "/a/foo/bar/baz/c", as well as "/a/b/c" and "/a/foo/bar".

When specifying patterns to query parameters, headers, and form parameters, the "*"character specifies to match any number of characters. For example, when matching a header, specify the pattern as:

*;charset={encoding}

This pattern matches the values "text/xml;charset=UTF-16" and "application/xml;charset=ASCII".

If the value passed to the ExtractVariables policy contains a special character, such as "{", use the "%" character to escape it. The following example escapes the "{" and "}" characters in the pattern because they are used as literal characters in the value of the query parameter:

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

In this example, the pattern matches the value "{user} Steve" but not the value "user Steve".

Matching JSON and XML

When extracting data from JSON and XML, you specify one or more<Variable> tags in the policy. The<Variable> tag specifies the name of the destination variable where the extracted information is stored, and the JsonPath (JSON) or XPATH (XML) to the extracted information.

All<Variable> tags in the policy are evaluated, so that you can populate multiple variables from a single policy. If the<Variable> tag does not evaluate to a valid field in the JSON or XML, then the corresponding variable is not created.

The following example shows an ExtractVariables policy that populates two variables from the JSON body of a response:

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

Writing to the same variable in multiple places

Take care when choosing the names of variables to set. The policy executes sequentially from the first extraction pattern to the last. If the policy writes a value to the same variable from multiple places, the last write in the policy determines the value of the variable. (This may be what you want.)

For example, you want to extract a token value that can be passed either in a query parameter or in a header, as shown below:

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

Controlling what happens when no match occurs

If the pattern does not match, then the corresponding variable is not created. Therefore, if another policy references the variable, it can cause an error.

One option is to set<IgnoreUnresolvedVariables> to true in a policy that references the variable to configure the policy to treat any unresolvable variable as an empty string (null):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Element reference

The element reference describes the elements and attributes of the ExtractVariables policy.

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

<ExtractVariables> attributes

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

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to thename attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<Source> element

(Optional) Specifies the variable to be parsed. The value of<Source> defaults tomessage. Themessage value is context-sensitive. In a request flow,message resolves to the request message. In a response flow,message resolves to the response message.

While you often use this policy to extract information from a request or response message, you can use it to extract information from any variable. For example, you can use it to extract information from an entity created by theAccessEntity policy, from data returned by theServiceCallout policy, or extract information from an XML or JSON object.

If<Source> cannot be resolved, or resolves to a non-message type, the policy will fail to respond.

<SourceclearPayload="true|false">request</Source>

Attributes

<VariablePrefix> element

(Optional) The complete variable name is created by joining the<VariablePrefix>, a dot, and the name you define in {curly braces} in the<Pattern> element or<Variable> element. For example:myprefix.id,myprefix.dbncode, ormyprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

For example, suppose the value of name is "user".

• If<VariablePrefix> is not specified, the extracted values are assigned to a variable nameduser.
• If<VariablePrefix> is specified as myprefix, the extracted values are assigned to a variable namedmyprefix.user.

<IgnoreUnresolvedVariables> element

(Optional) Set totrue to treat any unresolvable variable as an empty string (null). Set tofalse if you want the policy to throw an error when any referenced variable is unresolvable.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

<URIPath> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the proxy.pathsuffix of arequest source message. The path applied to the pattern is the proxy.pathsuffix, which does not include the basepath for the API Proxy. If the source message resolves to a message type ofresponse, then this element does nothing.

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

It is possible to use multiple<Pattern> elements:

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

Attributes

<QueryParam> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified query parameter of arequest source message. If the source message resolves to a message type ofresponse, then this element does nothing.

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

If multiple query parameters have the same name, use indexes to reference the parameters:

<QueryParam name="w.2">   <Pattern ignoreCase="true">{secondW}</Pattern></QueryParam>

Attributes

<Header> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified HTTP header of the specifiedrequest orresponse message. If multiple headers have the same name, their values are stored in an array.

<!--Thenameistheactualheadername.--><Headername="Authorization"><!--Provideanameforyournewcustomvariablehere.--><PatternignoreCase="false">Bearer{oauthtoken}</Pattern></Header>

If multiple headers have the same name, use indexes to reference individual headers in the array:

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

Or the following to list all the headers in the array:

<Header name="myHeader.values">   <Pattern ignoreCase="true">{myHeaders}</Pattern></Header>

Attributes

<FormParam> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified form parameter of the specifiedrequest orresponse message. Form parameters can be extracted only when theContent-Type header of the specified message isapplication/x-www-form-urlencoded.

<FormParam name="greeting">    <Pattern>hello {user}</Pattern></FormParam>

Attributes

<Variable> element

(Optional, but see the Presence row in the table below for more information.) Specifies the name of a variable from which to extract a value.

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

To extract two values from the variable:

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

Attributes

<JSONPayload> element

(Optional, but see the Presence row in the table below for more information.) Specifies the JSON-formatted message from which the value of the variable will be extracted. JSON extraction is performed only when message'sContent-Type header isapplication/json.

<JSONPayload><Variablename="name"type="string"><JSONPath>{example}</JSONPath></Variable></JSONPayload>

<JSONPayload>/<Variable> element

(Required within the JSONPayload element.) Specifies the variable where the extracted value is assigned. You can include multiple<Variable> tags in the<JSONPayload> element to populate multiple variables.

<Variablename="name"type="string"><JSONPath>{example}</JSONPath></Variable>

Attributes

<JSONPayload>/<Variable>/<JSONPath> element

(Required within the JSONPayload:Variable element.) Specifies the JSON path used to extract a value from a JSON-formatted message.

<Variable name="name">  <JSONPath>$.rss.channel.title</JSONPath></Variable>

<XMLPayload> element

(Optional, but see the Presence row in the table below for more information.) Specifies the XML-formatted message from which the value of the variable will be extracted. XML payloads are extracted only when theContent-Type header of the message istext/xml,application/xml, orapplication/*+xml.

<XMLPayloadstopPayloadProcessing="false"><Namespaces><Namespaceprefix="apigee">http://www.apigee.com</Namespace><Namespaceprefix="gmail">http://mail.google.com</Namespace></Namespaces><Variablename="name"type="boolean"><XPath>/apigee:test/apigee:example</XPath></Variable></XMLPayload>

Attributes

<XMLPayload>/<Namespaces> element

(Optional) Specifies the namespace to be used in the XPath evaluation. If you're using namespaces in your XPath expressions, you must declare the namespaces here, as shown in the following example.

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

If you are not using namespaces in your XPath expressions, you can omit or comment out the<Namespaces> element, as the following example shows:

<XMLPayloadstopPayloadProcessing="false"><!--<Namespaces/>--><Variablename="legName"type="string"><XPath>/Directions/route/leg/name</XPath></Variable></XMLPayload>

Attributes

<XMLPayload>/<Variable> element

(Optional) Specifies variable to which the extracted value will be assigned.

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

Attributes

<XMLPayload>/<Variable>/<XPath> element

(Required within the XMLPayload:Variable element.) Specifies the XPath defined for the variable. Only XPath 1.0 expressions are supported.

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

Example with a namespace. If you use namespaces in your XPath expressions, you must declare the namespaces in the<XMLPayload><Namespaces> section of the policy.

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

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

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Clickbuildin the Fix column for detailed troubleshooting information.

Deployment errors

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

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

Example error response

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

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

Related topics

Flow variables reference