This page applies to Apigeeand Apigee hybrid.
View Apigee Edge
documentation.
What
The AssignMessage policy can change an existing request or response message, or create a new request or response message during the API proxy Flow. The policy lets you perform the following actions on those messages:
- Add new form parameters, headers, or query parameters to a message
- Copy existing properties from one message to another
- Remove headers, query parameters, form parameters, and message payloads from a message
- Set the value of properties in a message
AssignMessage also allows you to set arbitrary context variables, independent of any of the above operations that might apply to a message.
With AssignMessage, you can add, change, or remove properties of either the request or response. You can alternatively use AssignMessage to create a custom request or response message and pass it to an alternative target, as described in Create custom request messages .
This policy is an Extensible 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, see Policy types .
The AssignMessage policy can create or change flow variables with the following child elements:
The order in which you organize the <Add>
, <Copy>
, <Set>
,
and <Remove>
elements is important. The policy executes those actions in the order
in which they appear in the policy configuration. If you need to remove all headers, then set a
specific header, you should include the <Remove>
element before the <Set>
element.
<AssignMessage>
element
Defines an AssignMessage policy.
Default Value | See Default Policytab, below |
Required? | Required |
Type | Complex object |
Parent Element | N/A |
Child Elements | <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>
|
The <AssignMessage>
element uses the following syntax:
Syntax
The <AssignMessage>
element uses the following syntax:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- All AssignMessage child elements are optional --> <Add> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams> </Add> <AssignTo createNew="[true|false]" transport="http" type="[request|response]"> DESTINATION_VARIABLE_NAME </AssignTo> <AssignVariable> <Name> VARIABLE_NAME </Name> <PropertySetRef> SOURCE_VARIABLE </PropertySetRef> <Ref> SOURCE_VARIABLE </Ref> <ResourceURL> RESOURCE_URL_OR_TEMPLATE </ResourceURL> <Template> MESSAGE_TEMPLATE </Template> or <Template ref=' TEMPLATE_VARIABLE '></Template> <Value> VARIABLE_VALUE </Value> </AssignVariable> <Copy source=" VARIABLE_NAME "> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams> <!-- Copy all headers --> <Headers/> <!-- or, copy specific headers by name --> <Headers> <Header name=" HEADER_NAME "/> <!-- or --> <Header name=" HEADER_NAME ">[false|true]</Header> ... </Headers> <Path>[false|true]</Path> <Payload>[false|true]</Payload> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams> <StatusCode>[false|true]</StatusCode> <Verb>[false|true]</Verb> <Version>[false|true]</Version> </Copy> <DisplayName> POLICY_DISPLAY_NAME </DisplayName> <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables> <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <!-- Remove all form parameters --> <FormParams/> <!-- or, remove specific form parameters by name --> <FormParams> <FormParam name=" FORMPARAM_NAME "/> <!-- or --> <FormParam name=" FORMPARAM_NAME ">[false|true]</FormParam> ... </FormParams> <!-- Remove all headers --> <Headers/> <!-- or, remove specific headers by name --> <Headers> <Header name=" HEADER_NAME "/> <!-- or --> <Header name=" HEADER_NAME ">[false|true]</Header> ... </Headers> <Payload>[false|true]</Payload> <!-- Remove all query parameters --> <QueryParams/> <!-- or, remove specific query parameters by name --> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "/> <!-- or --> <QueryParam name=" QUERYPARAM_NAME ">[false|true]</QueryParam> ... </QueryParams> </Remove> <Set> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers> <Path> PATH </Path> <Payload contentType=" CONTENT_TYPE " variablePrefix=" PREFIX " variableSuffix=" SUFFIX "> NEW_PAYLOAD </Payload> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams> <StatusCode> HTTP_STATUS_CODE or {variable}</StatusCode> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb> <Version>[1.0|1.1|{variable}]</Verb> </Set> </AssignMessage>
Default Policy
The following example shows the default settings when you add an AssignMessage policy to your flow in the Apigee UI:
<AssignMessage continueOnError="false" enabled="true" name="assign-message-default"> <DisplayName>Assign Message-1</DisplayName> <Properties/> <Copy source="request"> <Headers/> <QueryParams/> <FormParams/> <Payload/> <Verb/> <StatusCode/> <Path/> </Copy> <Remove> <Headers> <Header name="h1"/> </Headers> <QueryParams> <QueryParam name="q1"/> </QueryParams> <FormParams> <FormParam name="f1"/> </FormParams> <Payload/> </Remove> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <!-- <Verb>GET</Verb> --> <Path/> </Set> <AssignVariable> <Name>name</Name> <Value/> <Ref/> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
When you insert a new AssignMessage policy in the Apigee UI, the template contains stubs for all
possible operations. Typically, you select which operations you want to perform with this policy
and remove the rest of the child elements. For example, if you want to perform a copy operation, use the <Copy>
element and remove <Add>
, <Remove>
, and other child elements from the
policy to make it more readable.
This element has the following attributes that are common to all policies:
name
The internal name of the policy. The value of the name
attribute can
contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot
exceed 255 characters.
Optionally, use the <DisplayName>
element to label the policy in
the management UI proxy editor with a different, natural-language name.
continueOnError
false
to return an error when a policy fails. This is expected behavior for
most policies. Set to true
to have flow execution continue even after a policy
fails. See also:
enabled
true
to enforce the policy. Set to false
to turn off
the
policy. The policy will not be enforced even if it remains attached to a flow.async
The following table provides a high-level description of the child elements of <AssignMessage>
:
<AssignTo>
element. <Add>
adds headers or parameters to the message that don't exist in the original
message. Note that <Set>
also provides this functionality.
To overwrite existing headers or parameters, use the <Set>
element.
source
attribute to
the message object specified by the <AssignTo>
element.<AssignTo>
element. <Set>
overwrites headers or parameters that already exist
in the original
message or adds new if they don't.
<AssignVariable>
creates it.Each of these child elements is described in the sections that follow.
Examples
The following examples show some of the ways in which you can use the AssignMessage policy:
1: Add header
The following example adds a header to the request with the <Add>
element:
<AssignMessage name="AM-add-headers-1"> <Add> <Headers> <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header> </Headers> </Add> <AssignTo>request</AssignTo> </AssignMessage>
2: Remove payload
The following example deletes the payload from the response with the <Remove>
element:
<AssignMessage name="AM-remove-1"> <DisplayName>remove-1</DisplayName> <Remove> <Payload>true</Payload> </Remove> <AssignTo>response</AssignTo> </AssignMessage>
3: Modify response
The following example modifies an existing response object by adding a header to it:
<AssignMessage name="AM-modify-response"> <Set> <Headers> <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo>response</AssignTo> </AssignMessage>
This example does not create a new message. Instead, it modifies an existing response message by adding an HTTP header.
Because this example specifies response
as the variable name in the <AssignTo>
element, this policy modifies the response object that was originally
set with data returned by the target server.
The HTTP header added to the response message by this policy is derived from a variable populated by the LookupCache policy . Therefore the response message modified by this Assign Message policy contains an HTTP header that indicates whether the results have been pulled from the cache or not. Setting headers in the response can be handy for debugging and troubleshooting.
4: Set dynamic content
You can use AssignMessage to embed dynamic content in the payload of response and request messages.
To embed flow variables in an XML payload, wrap the designated variable in curly
braces, like this: {prefix.name}
.
The following example embeds the value of the user-agent
HTTP header flow variable
in an XML element called User-agent
:
<AssignMessage name="AM-set-dynamic-content"> <AssignTo>response</AssignTo> <Set> <Payload contentType="text/xml"> <User-agent>{request.header.user-agent}</User-agent> </Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
For JSON payloads, you can insert variables using the variablePrefix
and variableSuffix
attributes with delimiter characters as shown in the following
example:
<AssignMessage name="set-payload"> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> { "user-agent": "@request.header.user-agent#" } </Payload> </AssignMessage>
For a complete list of flow variables, see Flow variables reference .
You can also use curly braces to insert variables.
5: Remove query param
The following example removes the apikey
query parameter from the request:
<AssignMessage name="AM-remove-query-param"> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
It's a best practice to strip the apikey
query parameter from the request
message when you use the VerifyAPIKey policy
for user authentication. You do this to prevent
sensitive key information from being passed to the backend target.
6: Set/get variables
The following example uses three AssignMessage policies:
- Creates three flow variables in the request, with static values
- Gets the flow variables dynamically in a second policy in the request flow
- Sets them in the payload of the response
<!-- Policy #1: Set variables in the request --> <AssignMessage name="AM-set-variables"> <!-- Create a variable named myAppSecret --> <AssignVariable> <Name>myAppSecret</Name> <Value>42</Value> </AssignVariable> <!-- Create a variable named config.environment --> <AssignVariable> <Name>config.environment</Name> <Value>test</Value> </AssignVariable> <!-- Create a variable named config.protocol --> <AssignVariable> <Name>config.protocol</Name> <Value>gopher</Value> </AssignVariable> </AssignMessage>
In the first policy, the <AssignVariable>
element creates and sets three
variables in the request. Each <Name>
element specifies
a variable name, and <Value>
specifies the value.
The second policy uses the <AssignVariable>
element to read in the values and creates three
new variables:
<!-- Policy #2: Get variables from the request --> <AssignMessage continueOnError="false" enabled="true" name="get-variables"> <AssignTo createNew="false" transport="http" type="request"/> <!-- Get the value of myAppSecret and create a new variable, secret --> <AssignVariable> <Name>secret</Name> <Ref>myAppSecret</Ref> <Value>0</Value> </AssignVariable> <!-- Get the value of config.environment and create a new variable, environment --> <AssignVariable> <Name>environment</Name> <Ref>config.environment</Ref> <Value>default</Value> </AssignVariable> <!-- Get the value of config.protocol and create a new variable, protocol --> <AssignVariable> <Name>protocol</Name> <Ref>config.protocol</Ref> <Value>default</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
In the second policy, the <Ref>
element references the source variable,
and <Name>
elements specify the names of the new variables. If the variable
referenced by the <Ref>
element is not accessible, you can use the value
specified by the <Value>
element.
To try out this set of policies:
- Add policies #1 and #2 to the request flow. Be sure to put policy #1 before policy #2.
- Add the third policy in the response flow.
- The third policy uses the
<Set>
element to add the variables to the response. The following example constructs an XML payload in the response that Edge returns to the client:<!-- Policy #3: Add variables to the response --> <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload"> <DisplayName>put-em-in-the-payload</DisplayName> <Set> <Payload contentType="application/xml"> <wrapper> <secret>{secret}</secret> <config> <environment>{environment}</environment> <protocol>{protocol}</protocol> </config> </wrapper> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Note that the syntax to access flow variables in
<Set>
is to wrap them in curly braces.Be sure to set the
<Payload>
element'scontentType
attribute toapplication/xml
. - Send a request to your API proxy; for example:
curl -vL https://ahamilton-eval-test.apigee.net/myproxy
Optionally, you can pipe the results through a utility such as
xmllint
so that the XML is displayed in a nicely formatted structure:curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -
The body of the response should look like the following:
<wrapper> <secret>42</secret> <config> <environment>test</environment> <protocol>gopher</protocol> </config> </wrapper>
7: Get ServiceCallout response headers
In the following example, let's say that a ServiceCallout policy
is in the API proxy request,
and the callout response contains multiple headers of the same name
( Set-Cookie
). Assuming the Service Callout's response variable is the default calloutResponse
, the following policy gets the second Set-Cookie
header value.
<AssignMessage name="AM-Payload-from-SC-header"> <Set> <Payload contentType="application/json"> {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"} </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo>response</AssignTo> </AssignMessage>
To list all header values, use the following variable instead:
{calloutResponse.header.Set-Cookie. values}
8: Store and remove form params, headers, query params
If you want to use <Remove>
to delete your headers, query parameters, or form parameters, but
retain access to their values later in the policy flow, you can store their values using <AssignVariable>
.
<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove"> <DisplayName>AM-StoreAndRemove</DisplayName> <AssignVariable> <Name>var_grant_type</Name> <Ref>request.formparam.grant_type</Ref> </AssignVariable> <Remove> <Headers/> <FormParams/> <Payload/> </Remove> <Set> <Headers> <Header name="Content-Type">application/x-www-form-urlencoded</Header> <Header name="Accept">application/json</Header> <Header name="Grant-Type">{var_grant_type}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Each child element in this reference has additional examples. For even more examples, see AssignMessage example on GitHub.
Child element reference
This section describes the child elements of <AssignMessage>
.
<Add>
Adds information to the request or response, which is specified by the <AssignTo>
element.
The <Add>
element adds new properties on the message that don't exist in the original
message. Note that <Set>
also provides this functionality. To change the values of existing
properties, use the <Set>
element.
Default Value | N/A |
Required? | Optional |
Type | Complex type |
Parent Element | <AssignMessage>
|
Child Elements | <FormParams>
<Headers>
<QueryParams>
|
The <Add>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Add> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams> </Add> </AssignMessage>
Example 1
The following example uses the <FormParams>
element to get the values of
three query string parameters from the initial request and set them as form parameters on the
target endpoint request:
<AssignMessage name="AM-add-formparams-3"> <Add> <FormParams> <FormParam name="username">{request.queryparam.name}</FormParam> <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam> <FormParam name="default_language">{request.queryparam.lang}</FormParam> </FormParams> </Add> <Remove> <QueryParams/> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example uses the <Headers>
element to add a partner-id
header to the request that will be sent to the target endpoint:
<AssignMessage name="AM-add-headers-1"> <Add> <Headers> <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header> </Headers> </Add> <AssignTo>request</AssignTo> </AssignMessage>
Example 3
The following example uses the <QueryParams>
element to add a single query
parameter with a static value to the request:
<AssignMessage name="AM-add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
This example uses <Add>
in the request preflow. If you look at the results in a tool
such as the Debug overview
, the request to https://example-target.com/get
becomes https://example-target.com/get?myParam=42
.
The child elements of <Add>
support dynamic string substitution, known as message templating
.
<FormParams>
(child of <Add>
)
Adds new form parameters to the request message. This element has no effect on a response message.
Default Value | N/A |
Required? | Optional |
Type | Array of <FormParam>
elements |
Parent Element | <Add>
|
Child Elements | <FormParam>
|
The <FormParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Add> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams><AssignTo createNew="[true|false]" transport="http" type="[request|response]"> DESTINATION_VARIABLE_NAME </AssignTo> </Add> </AssignMessage>
Example 1
The following example adds a single form parameter ( answer
) and a static value ( 42
) to
the request:
<AssignMessage name="AM-add-formparams-1"> <Add> <FormParams> <FormParam name="answer">42</FormParam> </FormParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example gets the value of the name
query parameter and
adds it to the request as a form parameter, and then removes the query parameter:
<AssignMessage name="AM-Swap-QueryParam-to-FormParams"> <Add> <FormParam name="name">{request.queryparam.name}</FormParam> </Add> <Remove> <QueryParam name="name"/> </Remove> </AssignMessage>
Note that this example does not specify a target with <AssignTo>
. This policy adds the
parameter to the request only.
Example 3
The following example adds multiple form parameters to the request:
<AssignMessage name="AM-add-formparams-3"> <Add> <FormParams> <FormParam name="username">{request.queryparam.name}</FormParam> <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam> <FormParam name="default_language">{request.queryparam.lang}</FormParam> </FormParams> </Add> <Remove> <QueryParams/> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
This example gets the query string parameters from the originating request and adds them as form parameters with different names. Then it removes the original query parameters. Apigee will send the modified request to the target endpoint.
You can use the Debug overview to look at the flow. You'll see that the body of the request contains the URL-encoded form data, which was originally passed in as query string parameters:
username=nick&zip_code=90210&default_language=en
You can use <FormParams>
only when the following criteria are met:
- HTTP verb: POST
- Message type: Request
- One (or both) of the following:
- Form data: Set to some value, or "" (the empty string). For example, with
curl
, add-d ""
to your request. -
Content-Length
header: Set to 0 (if no data is in the original request; otherwise, the current length, in bytes). For example, withcurl
add-H "Content-Length: 0"
to your request.
- Form data: Set to some value, or "" (the empty string). For example, with
For example:
curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded" https://ahamilton-eval-test.apigee.net/am-test
When you add <FormParams>
, Apigee sets the request's Content-Type
header to application/x-www-form-urlencoded
before sending the message to the target service.
<Headers>
(child of <Add>
)
Adds new headers to the specified request or response, which is specified by the <AssignTo>
element.
Default Value | N/A |
Required? | Optional |
Type | Array of <Header>
elements |
Parent Element | <Add>
|
Child Elements | <Header>
|
The <Headers>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Add> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers></Add> </AssignMessage>
Example 1
The following example adds a partner-id
header to the request message, and
assigns the value of the verifyapikey.VAK-1.developer.app.partner-id
flow variable to that header.
<AssignMessage name="AM-add-headers-1"> <Add> <Headers> <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header> </Headers> </Add> <AssignTo>request</AssignTo> </AssignMessage>
<QueryParams>
(child of <Add>
)
Adds new query parameters to the request. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | Array of <QueryParam>
elements |
Parent Element | <Add>
|
Child Elements | <QueryParam>
|
The <QueryParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Add> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams></Add> </AssignMessage>
Example 1
The following example adds the query parameter myParam
to the request and assigns the value 42
to it:
<AssignMessage name="AM-add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
You can use <QueryParams>
only when the following criteria are met:
- HTTP verbs:
GET
,POST
,PATCH
,DELETE
- Message type: Request
In addition, you can only set query parameters when the <AssignTo>
element's type
attribute is a request message. Setting them on the response has no effect.
If you define an empty array of query parameters in your policy
( <Add><QueryParams/></Add>
), the policy does not add any query
parameters. This is the same as omitting <QueryParams>
.
<AssignTo>
Determines which object the AssignMessage policy operates on. The options are:
- Request message:
The
request
received by the API proxy - Response message:
The
response
returned from the target server - Custom message: A custom request or response object
Note that in some cases, you cannot change the object on which the AssignMessage policy acts.
For example, you cannot use <Add>
or <Set>
to add or change query parameters
( <QueryParams>
) or form parameters ( <FormParams>
) on the response. You can only
manipulate query parameters and form parameters on the request.
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignMessage>
|
Child Elements | None |
If you do not specify <AssignTo>
, or if you specify the <AssignTo>
element, but do
not specify a text value for the element, the policy acts on the default request or response,
which is based on where the policy executes. If the policy executes in the request flow, it
affects the request message. If it executes in the response flow, the policy affects the response
by default.
The <AssignTo>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignTo createNew="[true|false]" transport="http" type="[request|response]"> DESTINATION_VARIABLE_NAME </AssignTo></AssignMessage>
Example 1
The following example specifies no message in the text of the <AssignTo>
. That implies
that the policy will act on either the request
or response
message,
depending on where the policy executes.
<AssignMessage name="assignto-1"> <AssignTo createNew="false" transport="http" type="request"/> <!-- no-op --> ... </AssignMessage>
If you specify createNew="false"
, and do not explicitly provide a message name,
the other attributes of <AssignTo>
are irrelevant. In this case, you might
wish to omit the <AssignTo>
element completely.
Example 2
The following example creates a new request object, over-writing the existing object:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request"/> ... </AssignMessage>
When you create a new request or response object, the other elements of the AssignMessage
policy (such as <Add>
, <Set>
, and <Copy>
) act on that new
request object.
You can access the new request object in other policies later in the flow, or send the new request object to an external service with a ServiceCallout policy .
Example 3
The following example creates a new request object named MyRequestObject
:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo> ... </AssignMessage>
When you create a new request or response object, the other elements of the AssignMessage
policy (such as <Add>
, <Set>
, and <Copy>
) act on that new
request object.
You can access the new request object by name in other policies later in the flow, or send the new request object to an external service with a ServiceCallout policy .
The following table describes the attributes of <AssignTo>
:
createNew
Determines whether this policy creates a new message when assigning values.
If true
, then the policy creates a new variable of the type
specified by type
(either request
or response
). If you
do not specify the name of the new variable, then the policy creates a new request or
response object, based on the value of type
.
If false
, then the policy responds in one of two ways:
- If
<AssignTo>
can resolve the variable name to a request or response, then it continues processing. For example, if the policy is in a request flow, the variable is the request object. If the policy is in a response, the variable is the response object. - If
<AssignTo>
cannot be resolved, or resolves to a non-message type, then the policy throws an error.
If createNew
is not specified, the policy responds in one of two ways:
- If
<AssignTo>
resolves to a message, then processing advances to the next step. - If
<AssignTo>
cannot be resolved, or resolves to a non-message type, a new variable of type specified intype
is created.
transport
Specifies the transport type for the request or response message type.
The default value is http
(the only supported value).
type
createNew
is true
. Valid
values are request
or response
. The default value is request
. If you omit this attribute, then Apigee creates either
a request or a response, depending on where in the flow this policy executes.
<AssignVariable>
Assigns a value to a destination flow variable (such as a variable whose value is set by the
AssignMessage policy). If the flow variable does not exist, then <AssignVariable>
creates
it. You can use multiple AssignVariable elements within the AssignMessage policy. They are
executed in order of appearance in the policy configuration.
Default Value | N/A |
Required? | Optional |
Type | Complex type |
Parent Element | <AssignMessage>
|
Child Elements | <Name>
(required)<PropertySetRef>
<Ref>
<ResourceURL>
<Template>
<Value>
|
The value that you assign to the destination flow variable can be one of the following:
- Literal string: Use the
<Value>
child element to specify a literal string value for the destination flow variable. - Flow variable: Use the
<Ref>
child element to specify the value of an existing flow variable for the destination flow variable. For a complete list of flow variables that can be used as a source, see Flow variables reference . - Property set: Use the
<PropertySetRef>
child element to retrieve the value from a property set name/key pair and store it in a flow variable. Lets you access property sets dynamically. - Resource URL: Use the
<ResourceURL>
child element to specify a URL for a text resource, of type XSL, XSD, WSDL, JavaScript, or OpenAPI Spec. This assigns the contents of the resource into the named flow variable. - Message template: Use the
<Template>
child element to specify a message template for the destination flow variable.
The order of precedence for these child elements is: ResourceURL, Template, Ref, Value, PropertySetRef.
The <AssignVariable>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Name> VARIABLE_NAME </Name> <PropertySetRef> SOURCE_VARIABLE </PropertySetRef> <Ref> SOURCE_VARIABLE </Ref> <ResourceURL> RESOURCE_URL_OR_TEMPLATE </ResourceURL> <Template> MESSAGE_TEMPLATE </Template> or <Template ref=' TEMPLATE_VARIABLE '></Template> <Value> VARIABLE_VALUE </Value> </AssignVariable></AssignMessage>
Use the <Ref>
element to specify the source variable. If the
variable referenced by <Ref>
is not accessible, Apigee uses the value
specified by the <Value>
element. If you define <Template>
, it takes precedence over the <Ref>
and <Value>
sibling elements.
Example 1
The following example sets the value of a new variable, myvar
, to the literal
value 42
:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
Example 2
The following example assigns the value of the flow variable request.header.user-agent
to the destination flow variable myvar
and the value of the query parameter country
to the destination flow variable Country
:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
If either assignment fails, Apigee instead assigns the value ErrorOnCopy
to
the destination flow variable.
If the myvar
or Country
flow variables do not exist, <AssignVariable>
creates them.
Example 3
The following example uses the <Template>
child element to concatenate two context variables
with a literal string (a hyphen) between them:
<AssignMessage name='AV-via-template-1'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
Example 4
The following example uses <AssignVariable>
to disable the default behavior of
propagating the path suffix from the proxy request to the target request:
<AssignMessage name='AM-PathSuffixFalse'> <AssignVariable> <Name>target.copy.pathsuffix</Name> <Value>false</Value> </AssignVariable> </AssignMessage>
A common use for <AssignVariable>
is to set a default value for a query parameter, header, or
other value that can be passed in with the request. You do this with a combination of both the <Ref>
and <Value>
child elements. For more
information, see the examples for <Ref>
.
<Name>
(child of <AssignVariable>
)
Specifies the name of the destination flow variable - the variable whose value is set by
the AssignMessage policy. If the variable named in <Name>
does not exist, the
policy creates one with that name.
Default Value | N/A |
Required? | Required |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
The <Name>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Name> VARIABLE_NAME </Name></AssignVariable> </AssignMessage>
Example 1
The following example specifies the destination variable as myvar
, and sets it
to the literal value 42
:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
If myvar
does not exist, <AssignVariable>
creates it.
<PropertySetRef>
(child of <AssignVariable>
)
This element allows you to retrieve the value of a property set name/key pair dynamically. To learn about property sets, see Using property sets .
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
A property set consists of a name/key pair.
For example: propset1.id=12345
,
where propset1
is the name of the property set, id
is a key, and 12345
is the key's value.
The PropertySetRef
child element lets you select property set names and/or keys dynamically. Assume
you have 200 routing rules in a property set file. You can access the property set rules
as follows, where routingrules
is the property set name and rule1
, rule2
, rule n
are keys:
propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rule n
To access these properties in an API proxy flow, you must know which rule you want to select at design time. However, assume the rule name comes in the request header or payload. One way to select the rule is to use a JavaScript policy with code such as the following:
context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.
On the other hand, the AssignMessage PropertySetRef
feature lets you select a property key dynamically without
introducing JavaScript.
You can use a mix of flow variables and literal string values in the <PropertySetRef>
element. See the examples for more details.
The <PropertySetRef>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <PropertySetRef> SOURCE_VARIABLE </PropertySetRef></AssignVariable> </AssignMessage>
Example 1
This example assigns the value from a property set key to a flow variable. In this case,
the property set name is obtained from the header propset_name
, the key is provided
in the header propset_key
, and the value assigned to the key is stored in the variable flow_variable
.
<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage"> <DisplayName>Assign Message-1</DisplayName> <Properties/> <AssignVariable> <Name>flow_variable</Name> <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef> </AssignVariable> </AssignMessage>
You can use any combination of flow variables and literal strings in the <PropertySetRef>
element.
Example 2
This example assigns the value from a property set key to a flow variable using a fixed
key name (literal string). In this case, the property set name is obtained from the
header propset_name
, the key is the literal string key1
, and the value assigned to
the key is stored in the variable flow_variable
.
<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage"> <DisplayName>Assign Message-1</DisplayName> <Properties/> <AssignVariable> <Name>flow_variable</Name> <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef> </AssignVariable> </AssignMessage>
You can use any combination of flow variables and literal strings in the <PropertySetRef>
element.
<Ref>
(child of <AssignVariable>
)
Specifies the source of the assignment as a flow variable. The flow variable can be one of the pre-defined flow variables (as listed in the Flow variables reference ), or a custom flow variable that you created.
The value of <Ref>
is always interpreted as a flow variable; you cannot
specify a literal string as the
value. To assign a literal string value, use the <Value>
element
instead.
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
When you specify a flow variable with <Ref>
, omit the
enclosing brackets {}
that you would normally use to reference a flow variable. For example,
to set the value of your new variable to the value of the client.host
flow
variable:
DO specify the variable name without brackets: <Ref>client.host</Ref> DO NOT use brackets: <Ref>{client.host}</Ref>
To define a default value for the destination flow variable, use <Value>
in combination with <Ref>
. If the flow variable specified by <Ref>
does not exist, cannot be read, or is null, then Apigee assigns the value
of <Value>
to the destination flow variable instead.
The <Ref>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Name> VARIABLE_NAME </Name> <Ref> SOURCE_VARIABLE </Ref></AssignVariable> </AssignMessage>
Example 1
The following example assigns the value of the flow variable request.header.user-agent
to the destination flow variable myvar
and
the value of the query parameter country
to the Country
variable:
<AssignMessage name="assignvariable-4"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> </AssignVariable> </AssignMessage>
In this example, Apigee does not have a default (or fallback value) specified for either assignment.
Example 2
The following example assigns the value of the flow variable request.header.user-agent
to the destination flow variable myvar
and the value
of the query parameter country
to the Country
variable:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
In this example, if the values of the request.header.user-agent
flow variable
or the Country
query parameter are null, unreadable, or malformed, Apigee assigns
the value ErrorOnCopy
to the new variables.
Example 3
A common use case for <AssignVariable>
is to set the default value of a query
parameter, header, or other value that can be passed in with the request. For example, you create
a weather API proxy where the request takes a single query parameter named w
. This
parameter contains the ID of the city for which you want the weather. The request URL has
the form:
http://myCO.com/v1/weather/forecastrss?w= CITY_ID
To define a default value for w
, create an AssignMessage policy like the
following:
<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3"> <AssignTo createNew="false" transport="http" type="request"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignVariable> <Name>request.queryparam.w</Name> <Ref>request.queryparam.w</Ref> <Value>12797282</Value> </AssignVariable> </AssignMessage>
In this example, <AssignVariable>
gets the value of request.queryparam.w
and assigns it to itself. If the flow variable is null, meaning the w
query parameter was
omitted from the request, then this example uses the default value from the <Value>
element. Therefore, you can make a request to this API
proxy that omits the w
query parameter:
http://myCO.com/v1/weather/forecastrss
...and still have the API proxy return a valid result.
The value of <Ref>
must be a
flow variable, such as a property of a request
, response
, or target
object, or the name of a custom flow variable.
If you specify a flow variable that does not exist for the value of <Ref>
,
and the value of <IgnoreUnresolvedVariables>
is false
, Apigee throws an error.
<ResourceURL>
(child of <AssignVariable>
)
Specifies the URL of a text resource
as the source of the variable assignment. Apigee loads the flow variable specified in <Name>
with the contents of the referenced resource. The resource can be of
type XSD, XSL, WSDL, JavaScript, Property Set, or OpenAPI Spec.
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
If the resource specified by <ResourceURL>
does not exist, then: if the value of <IgnoreUnresolvedVariables>
is true
, Apigee
assigns the value null
to the destination flow variable, whereas if the value of <IgnoreUnresolvedVariables>
is false
, Apigee throws an error.
The <ResourceURL>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Name> VARIABLE_NAME </Name> <ResourceURL> RESOURCE_URL_OR_TEMPLATE </ResourceURL></AssignVariable> </AssignMessage>
The text value takes a string value, and is interpreted as a message template . Any of these are valid:
<ResourceURL>jsc://my-js-file.js</ResourceURL> <ResourceURL>wsdl://{variable-goes-here}</ResourceURL> <ResourceURL>{variable-goes-here}</ResourceURL>
Example 1
The following example assigns the value of a JSON resource, loaded into the proxy in the jsc
folder, into the flow variable assigned-variable
:
<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'> <AssignVariable> <Name>assigned-variable</Name> <ResourceURL>jsc://settings.json</ResourceURL> </AssignVariable> </AssignMessage>
Example 2
The following example assigns the value of an OpenAPI Spec resource, loaded into the proxy
in the oas
folder, into the flow variable assigned-variable
, and then sets
that value as the Payload
in the response body:
<AssignMessage name='AM-Response'> <AssignVariable> <Name>assigned-variable</Name> <ResourceURL>oas://Fulfillment.yaml</ResourceURL> </AssignVariable> <Set> <Payload contentType='application/yaml'>{assigned-variable}</Payload> </Set> </AssignMessage>
<Template>
(child of <AssignVariable>
)
Specifies a message template . A message template allows you to perform variable string substitution when the policy executes, and can combine literal strings with variable names wrapped in curly braces. In addition, message templates support functions such as escaping and case conversion.
Use the ref
attribute to specify a flow variable where the value of the variable
is a message template. For example, you could store a message template as a custom attribute
on a developer app
. When Apigee identifies the developer app after it verifies the API key
or security token (through an additional policy), the <AssignVariable>
element could use the message template from the app's custom attribute, which is available
as a flow variable from the security policy. The following example assumes the message
template is available in a custom attribute called message_template
on the
developer app making the API call, where the VerifyAPIKey policy
was used to verify
the app's API key:
<Template ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
The <Template>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Template> MESSAGE_TEMPLATE </Template> or <Template ref=' TEMPLATE_VARIABLE '></Template></AssignVariable> </AssignMessage>
Example 1
The following example uses message templating syntax to concatenate two context variables with a literal string (a hyphen) between them:
<AssignMessage name='AV-via-template-1'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
Example 2
The following example specifies a flow variable, where the value of the variable is a pre-defined message template. Use this option if you want to inject a pre-defined template at runtime without having to modify the policy:
<AssignMessage name='AV-via-template-indirectly'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template ref='my_template_variable'/> </AssignVariable> </AssignMessage>
Example 3
The following example specifies a flow variable and a text value. In this case, if
the referenced variable is non-null, that value is used as the template. If the referenced
value is null, then the text value (in this case, {system.uuid}-{messageid}
)
is used as the template. This pattern is useful to provide an override
value, where
in some cases you want to override the default template (the text part) with values
that are set dynamically. For example, a conditional statement might grab a value
from a key-value map and set the referenced variable to that value:
<AssignMessage name='AV-template-with-fallback'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Template ref='my_variable'>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
<Value>
(child of <AssignVariable>
)
Defines the value of the destination flow variable set with <AssignVariable>
. The
value is always interpreted as a literal string; you cannot use a flow variable as the value, even
if you wrap the value in brackets ( {}
). To use a flow variable, use <Ref>
instead.
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignVariable>
|
Child Elements | None |
When used in combination with the <Ref>
element, <Value>
acts as the default (or fallback) value. If <Ref>
is not specified, is
unresolvable, or is null, the value of <Value>
is used.
The <Value>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <AssignVariable> <Name> VARIABLE_NAME </Name> <Value> VARIABLE_VALUE </Value></AssignVariable> </AssignMessage>
Example 1
The following example sets the value of the destination flow variable, myvar
,
to the literal value 42
:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
Example 2
The following example assigns the value of the flow variable request.header.user-agent
to the flow variable myvar
and the value
of the query parameter country
to the Country
variable:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
If either assignment fails, <AssignVariable>
instead assigns the value ErrorOnCopy
to
the destination flow variable.
<Copy>
Copies values from
the message specified by the source
attribute to
the message specified by the <AssignTo>
element. If you do not specify
a target with <AssignTo>
, then this policy copies the values to the request or the response,
depending on where in the flow this policy executes.
Default Value | N/A |
Required? | Optional |
Type | String |
Parent Element | <AssignMessage>
|
Child Elements | <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<StatusCode>
<Verb>
<Version>
|
If you specify no child elements beneath the <Copy>
element, then it will copy all parts
of the designated source message.
The <Copy>
element uses the following syntax:
Syntax
<AssignMessage
continueOnError="[false|true]"
enabled="[true|false]"
name=" POLICY_NAME
" > <Copy source=" VARIABLE_NAME
">
<!-- Can also be an empty array (<FormParams/>) -->
<FormParams>
<FormParam name=" FORMPARAM_NAME
"> FORMPARAM_VALUE
</FormParam>
...
</FormParams>
<!-- Copy all headers -->
<Headers/>
<!-- or, copy specific headers by name -->
<Headers>
<Header name=" HEADER_NAME
"/>
<!-- or -->
<Header name=" HEADER_NAME
">[false|true]</Header>
...
</Headers>
<Path>[false|true]</Path>
<Payload>[false|true]</Payload>
<!-- Can also be an empty array (<QueryParams/>) -->
<QueryParams>
<QueryParam name=" QUERYPARAM_NAME
"> QUERYPARAM_VALUE
</QueryParam>
...
</QueryParams>
<StatusCode>[false|true]</StatusCode>
<Verb>[false|true]</Verb>
<Version>[false|true]</Version>
</Copy><!-- Used as the destination for the <Copy>
values -->
<AssignTo createNew="[true|false]" transport="http"
type="[request|response]"> DESTINATION_VARIABLE_NAME
</AssignTo>
</AssignMessage>
Example 1
The following example copies a header, three form parameters, the path, and all query
parameters from the request
message to a new, custom request named newRequest
:
<AssignMessage name="AM-copy-1"> <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo> <Copy source="request"><Headers> <Header name="Header_Name_1"/> </Headers> <FormParams> <FormParam name="Form_Param_Name_1"/> <FormParam name="Form_Param_Name_2"/> <FormParam name="Form_Param_Name_3"/> </FormParams> <Path>true</Path> <QueryParams/> </Copy> </AssignMessage>
Because elements like <Payload>
and <Verb>
are not present, the
policy does not copy those parts of the message.
Example 2
The following example first removes everything in the existing response
message, then
copies all the values from a different message called secondResponse
into the response
message:
<AssignMessage name='AM-Copy-Response'> <AssignTo createNew="false" transport="http" type="response">response</AssignTo><!-- first remove any existing values --> <Remove/> <!-- then copy everything from the designated message --> <Copy source="secondResponse"/></AssignMessage>
The <Copy>
element has a single attribute:
Specifies the source object of the copy.
- If
source
is not specified, it defaults tomessage
, which takes a different value depending on the flow in which the policy executes. If the policy executes within the request flow, then themessage
variable refers to therequest
object. If the policy executes within the response flow, then themessage
variable refers to theresponse
object. - If the variable specified in the
source
attribute cannot be resolved, or resolves to a non-message type,<Copy>
will have no effect. - Ensure that the value you specify for
source
is different than the destination message, whether it is the default destination message or a destination explicitly specified with<AssignTo>
. If thesource
is the same as the destination message,<Copy>
will have no effect.
<FormParams>
(child of <Copy>
)
Copies form parameters from the request specified by the <Copy>
element's source
attribute to
the request
specified by the <AssignTo>
element. This element has no effect on a
response.
Default Value | N/A |
Required? | Optional |
Type | Array of <FormParam>
elements or an empty array |
Parent Element | <Copy>
|
Child Elements | <FormParam>
|
The <FormParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams></Copy> </AssignMessage>
Example 1
The following example copies a single form parameter from the request to the
custom request MyCustomRequest
:
<AssignMessage name="copy-formparams-1"> <Copy source="request"> <FormParams> <FormParam name="paramName">Form param value 1</FormParam> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 2
The following example copies all form parameters to the custom request MyCustomRequest
:
<AssignMessage name="copy-formparams-2"> <Copy source="request"> <FormParams/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 3
The following example copies three form parameters to the custom request MyCustomRequest
:
<AssignMessage name="copy-formparams-3"> <Copy source="request"> <FormParams> <FormParam name="paramName1"/> <FormParam name="paramName2"/> <FormParam name="paramName3"/> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 4
If there are multiple form params with the same name, use the following syntax:
<AssignMessage name="copy-formparams-4"> <Copy source="request"> <FormParams> <FormParam name="f1"/> <FormParam name="f2"/> <FormParam name="f3.2"/> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
This example copies f1
, f2
, and the second value of f3
. If f3
has only one
value, then it is not copied.
You can use <FormParams>
only when the following criteria are met:
- HTTP verb:
POST
- Message type: Response
- One (or both) of the following:
- Form data: Set to some value, or "" (the empty string). For example, with
curl
, add-d ""
to your request. -
Content-Length
header: Set to 0 (if no data is in the original request; otherwise, the current length. For example, withcurl
add-H "Content-Length: 0"
to your request.
- Form data: Set to some value, or "" (the empty string). For example, with
When you copy <FormParams>
, <Copy>
sets the message's Content-Type
to application/x-www-form-urlencoded
before sending the message to the target service.
<Headers>
(child of <Copy>
)
Copies HTTP headers from
the request or response message specified by
the <Copy>
element's source
attribute to
the request
or response message specified by the <AssignTo>
element.
Default Value | N/A |
Required? | Optional |
Type | An array of <Header>
elements or an empty array |
Parent Element | <Copy>
|
Child Elements | <Header>
|
The <Headers>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <!-- Copy all headers --> <Headers/> <!-- or, copy specific headers by name --> <Headers> <Header name=" HEADER_NAME "/> <!-- or --> <Header name=" HEADER_NAME ">[false|true]</Header> ... </Headers></Copy> </AssignMessage>
Example 1
The following example copies the user-agent
header from the request to the
new, custom request object:
<AssignMessage name="AM-copy-headers-1"> <Copy source="request"> <Headers> <Header name="user-agent"/> </Headers> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 2
To copy all headers, use an empty <Headers>
element, as the following example
shows:
<AssignMessage name="copy-headers-2"> <Copy source="request"> <Headers/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 3
If there are multiple headers with the same name, use the following syntax:
<AssignMessage name="copy-headers-3"> <Copy source="request"> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
This example copies h1
, h2
, and the second value of h3
. If h3
has only one
value, then it is not copied.
<Path>
(child of <Copy>
)
Determines whether the path should be copied from the source request to the destination request. This element has no effect on a response.
If true
, this policy copies the path from
the request message specified by the <Copy>
element's source
attribute to
the request
message specified by the <AssignTo>
element.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Copy>
|
Child Elements | None |
The <Path>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <Path>[false|true]</Path></Copy> </AssignMessage>
Example 1
The following example indicates that AssignMessage should copy the path from the source request to the new, custom request object:
<AssignMessage name="copy-path-1"> <Copy source="request"> <Path>true</Path> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
You can use <Path>
only when the following criteria are met:
- Message type: Request
<Payload>
(child of <Copy>
)
Determines whether the payload should be copied from the source to the destination. The source and destination can be requests or responses.
If true
, this policy copies the payload from
the message specified by the <Copy>
element's source
attribute to
the message
specified by the <AssignTo>
element.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Copy>
|
Child Elements | None |
The <Payload>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <Payload>[false|true]</Payload></Copy> </AssignMessage>
Example 1
The following example sets <Payload>
to true
so that the request payload is
copied from the request to the response:
<AssignMessage name="AM-copy-payload-1"> <Copy source="request"> <Payload>true</Payload> </Copy> <AssignTo>response</AssignTo> </AssignMessage>
<QueryParams>
(child of <Copy>
)
Copies query string parameters from
the request specified by the <Copy>
element's source
attribute to
the request specified
by the <AssignTo>
element. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | An array of <QueryParam>
elements or an empty array |
Parent Element | <QueryParam>
|
Child Elements | None |
The <QueryParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams></Copy> </AssignMessage>
Example 1
The following example copies the my_param
query parameter from the request into a new,
custom request object:
<AssignMessage name="copy-queryparams-1"> <Copy source="request"> <QueryParams> <QueryParam name="my_param"/> </QueryParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 2
The following example copies all query parameters from the request into a new, custom request object:
<AssignMessage name="copy-queryparams-2"> <Copy source="request"> <QueryParams/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
Example 3
If there are multiple query params with the same name, use the following syntax:
<AssignMessage name="copy-queryparams-3"> <Copy source="request"> <QueryParams> <QueryParam name="qp1"/> <QueryParam name="qp2"/> <QueryParam name="qp3.2"/> </QueryParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
This example copies qp1
, qp2
, and the second value of qp3
. If qp3
has only
one value, then it is not copied.
You can use <QueryParams>
only when the following criteria are met:
- HTTP verbs:
GET
,POST
,PATCH
,DELETE
- Message type: Request
<StatusCode>
(child of <Copy>
)
Determines whether the status code is copied from the source response to the destination response. This element has no effect on a request.
If true
, this policy copies the status code from
the response message specified by
the <Copy>
element's source
attribute to
the response
message specified by the <AssignTo>
element.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Copy>
|
Child Elements | None |
The <StatusCode>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <StatusCode>[false|true]</StatusCode></Copy> </AssignMessage>
Example 1
The following example sets <StatusCode>
to true
, which copies the status code
from the default response object to a new, custom response object:
<AssignMessage name="copy-statuscode-1"> <Copy source="response"> <StatusCode>true</StatusCode> </Copy> <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo> </AssignMessage>
You can use <StatusCode>
only when the source and destination messages are of type Response.
A common use of <StatusCode>
is to set that the proxy response status code to
a different value than that received from the target.
<Verb>
(child of <Copy>
)
Determines whether the HTTP verb is copied from the source request to the destination request. This element has no effect on a response.
If true
, copies the verb found in the <Copy>
element's source
attribute
to the request specified in the <AssignTo>
element.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Copy>
|
Child Elements | None |
The <Verb>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <Verb>[false|true]</Verb></Copy> </AssignMessage>
Example 1
The following example sets <Verb>
to true
, which copies the verb from the
default request to a new, custom request:
<AssignMessage name="copy-verb-1"> <Copy source="request"> <Verb>true</Verb> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
You can use <Verb>
only when the following criteria are met:
- Message type: Request
<Version>
(child of <Copy>
)
Determines whether the HTTP version is copied from the source request to the destination request. This element has no effect on a response.
If true
, copies the HTTP version found in the <Copy>
element's source
attribute
to the object specified by the <AssignTo>
element.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Copy>
|
Child Elements | None |
The <Version>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Copy source=" VARIABLE_NAME "> <Version>[false|true]</Version></Copy> </AssignMessage>
Example 1
The following example sets <Version>
to true
on the request, which copies the
version from the default request object to a new, custom request object:
<AssignMessage name="copy-version-1"> <Copy source="request"> <Version>true</Version> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
You can use <Version>
only when the following criteria are met:
- Message type: Request
<DisplayName>
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, more natural-sounding name.
The <DisplayName>
element is common to all policies.
Default Value | N/A |
Required? | Optional. If you omit <DisplayName>
, the value of the
policy's name
attribute is used. |
Type | String |
Parent Element | < PolicyElement > |
Child Elements | None |
The <DisplayName>
element uses the following syntax:
Syntax
< PolicyElement > <DisplayName> POLICY_DISPLAY_NAME </DisplayName>... </ PolicyElement >
Example
< PolicyElement > <DisplayName>My Validation Policy</DisplayName></ PolicyElement >
The <DisplayName>
element has no attributes or child elements.
<IgnoreUnresolvedVariables>
Determines whether processing stops when an unresolved variable is encountered.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <AssignMessage>
|
Child Elements | None |
Set to true
to ignore unresolved variables and continue processing; otherwise false
. The
default value is false
.
Setting <IgnoreUnresolvedVariables>
to true
is different from setting the <AssignMessage>
's continueOnError
to true
in that it is specific to setting and getting values of
variables. If you set continueOnError
to true
, then Apigee ignores all errors, not
just errors encountered when using variables.
The <IgnoreUnresolvedVariables>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables></AssignMessage>
Example 1
The following example sets <IgnoreUnresolvedVariables>
to true
:
<AssignMessage name="AM-Set-Headers"> <Set> <Headers> <Header name='new-header'>{possibly-defined-variable}<Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables></AssignMessage>
Because <IgnoreUnresolvedVariables>
is set to true
, if
the possibly-defined-variable
variable is not defined, this policy will
not throw a fault.
<Remove>
Removes headers, query parameters, form parameters, and/or the message payload from
a message. An empty <Remove>
tag removes everything from the message.
The affected message can be a request or a response. You specify which message <Remove>
acts on by using the <AssignTo>
element.
Default Value | N/A |
Required? | Optional |
Type | Complex type |
Parent Element | <AssignMessage>
|
Child Elements | <FormParams>
<Headers>
<Payload>
<QueryParams>
|
A common use case for <Remove>
is to delete a query parameter or header that contains sensitive
information from the incoming request object, to avoid passing it to the backend server.
The <Remove>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <!-- Remove all form parameters --> <FormParams/> <!-- or, remove specific form parameters by name --> <FormParams> <FormParam name=" FORMPARAM_NAME "/> <!-- or --> <FormParam name=" FORMPARAM_NAME ">[false|true]</FormParam> ... </FormParams> <!-- Remove all headers --> <Headers/> <!-- or, remove specific headers by name --> <Headers> <Header name=" HEADER_NAME "/> <!-- or --> <Header name=" HEADER_NAME ">[false|true]</Header> ... </Headers> <Payload>[false|true]</Payload> <!-- Remove all query parameters --> <QueryParams/> <!-- or, remove specific query parameters by name --> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "/> <!-- or --> <QueryParam name=" QUERYPARAM_NAME ">[false|true]</QueryParam> ... </QueryParams> </Remove></AssignMessage>
Example 1
The following example removes the message's body from the response:
<AssignMessage name="AM-remove-1"> <DisplayName>remove-1</DisplayName> <Remove> <Payload>true</Payload> </Remove> <AssignTo>response</AssignTo> </AssignMessage>
In the response flow, this policy removes the body of the response, returning only HTTP headers to the client.
Example 2
The following example removes all form parameters and a query parameter from
the request
object:
<AssignMessage name="AM-remove-2"> <Remove> <!-- Empty (<FormParams/>) removes all form parameters --> <FormParams/> <QueryParams> <QueryParam name="qp1"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 3
The following example removes everything from a message object:
<AssignMessage name="AM-remove-3"> <Remove/> <AssignTo>request</AssignTo> </AssignMessage>
Typically you would do this only if you were going to use the <Set>
element or
the <Copy>
element to set some replacement values into the message.
<FormParams>
(child of <Remove>
)
Removes the specified form parameters from the request. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | Array of <FormParam>
elements or an empty array |
Parent Element | <Remove>
|
Child Elements | <FormParam>
|
The <FormParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <!-- Remove all form parameters --> <FormParams/> <!-- or, remove specific form parameters by name --> <FormParams> <FormParam name=" FORMPARAM_NAME "/> <!-- or --> <FormParam name=" FORMPARAM_NAME ">[false|true]</FormParam> ... </FormParams></Remove> </AssignMessage>
Example 1
The following example removes three form parameters from the request:
<AssignMessage name="AM-remove-formparams-1"> <Remove> <FormParams> <FormParam name="form_param_1"/> <FormParam name="form_param_2"/> <FormParam name="form_param_3"/> </FormParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example removes all form parameters from the request:
<AssignMessage name="AM-remove-formparams-2"> <Remove> <FormParams/> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 3
If there are multiple form params with the same name, use the following syntax:
<AssignMessage name="AM-remove-formparams-3"> <Remove> <FormParams> <FormParam name="f1"/> <FormParam name="f2"/> <FormParam name="f3.2"/> </FormParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
This example removes f1
, f2
, and the second value of f3
. If f3
has only one
value, then it is not removed.
You can use <FormParams>
only when the following criteria are met:
- Message type: Request
-
Content-Type
:application/x-www-form-urlencoded
<Headers>
(child of <Remove>
)
Removes the specified HTTP headers from the request or response, which is specified by the <AssignTo>
element.
Default Value | N/A |
Required? | Optional |
Type | Array of <Header>
elements or an empty array |
Parent Element | <Remove>
|
Child Elements | <Header>
|
The <Headers>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <!-- Remove all headers --> <Headers/> <!-- or, remove specific headers by name --> <Headers> <Header name=" HEADER_NAME "/> <!-- or --> <Header name=" HEADER_NAME ">[false|true]</Header> ... </Headers></Remove> </AssignMessage>
Example 1
The following example removes the user-agent
header from the request:
<AssignMessage name="AM-remove-one-header"> <Remove> <Headers> <Header name="user-agent"/> </Headers> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example removes all headers from the request:
<AssignMessage name="AM-remove-all-headers"> <Remove> <Headers/> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 3
If there are multiple headers with the same name, use the following syntax:
<AssignMessage name="AM-remove-headers-3"> <Remove> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
This example removes h1
, h2
, and the second value of h3
from the request. If h3
has only one value, then it is not removed.
<Payload>
(child of <Remove>
)
Determines whether <Remove>
deletes the payload in the request or response, which is
specified by the <AssignTo>
element. Set to true
to
clear the payload; otherwise false
. The default value is false
.
Default Value | False |
Required? | Optional |
Type | Boolean |
Parent Element | <Remove>
|
Child Elements | None |
The <Payload>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <Payload>[false|true]</Payload></Remove> </AssignMessage>
Example 1
The following example sets <Payload>
to true
so that the request payload is
cleared:
<AssignMessage name="AM-remove-payload-1"> <Remove> <Payload>true</Payload> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
<QueryParams>
(child of <Remove>
)
Removes the specified query parameters from the request. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | Array of <QueryParam>
elements or an empty array |
Parent Element | <Remove>
|
Child Elements | <QueryParam>
|
The <QueryParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <!-- Can also be empty to remove everything from the message (<Remove/>) --> <Remove> <!-- Remove all query parameters --> <QueryParams/> <!-- or, remove specific query parameters by name --> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "/> <!-- or --> <QueryParam name=" QUERYPARAM_NAME ">[false|true]</QueryParam> ... </QueryParams></Remove> </AssignMessage>
Example 1
The following example removes a single query parameter from the request:
<AssignMessage name="AM-remove-queryparams-1"> <Remove> <QueryParams> <QueryParam name="qp1"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example removes all query parameters from the request:
<AssignMessage name="AM-remove-queryparams-2"> <Remove> <QueryParams/> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
Example 3
If there are multiple query params with the same name, use the following syntax:
<AssignMessage name="AM-remove-queryparams-3"> <Remove> <QueryParams> <QueryParam name="qp1"/> <QueryParam name="qp2"/> <QueryParam name="qp3.2"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
This example removes qp1
, qp2
, and the second value of qp3
from the request. If qp3
has only one value, then it is not removed.
Example 4
The following example removes the apikey
query parameter from the request:
<AssignMessage name="AM-remove-query-param"> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
You can use <QueryParams>
only when the following criteria are met:
- HTTP verbs:
GET
,POST
,PATCH
,DELETE
- Message type: Request
<Set>
Sets information in the request or response message, which is specified by the <AssignTo>
element. <Set>
overwrites headers or
query or form parameters that already exist in the original message or adds new if they don't.
Headers and query and form parameters
in an HTTP message might hold multiple values. To add additional values for a header or parameter, use
the <Add>
element instead.
Default Value | N/A |
Required? | Optional |
Type | Complex type |
Parent Element | <AssignMessage>
|
Child Elements | <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<StatusCode>
<Verb>
<Version>
|
The <Set>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers> <Path> PATH </Path> <Payload contentType=" CONTENT_TYPE " variablePrefix=" PREFIX " variableSuffix=" SUFFIX "> NEW_PAYLOAD </Payload> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams> <StatusCode> HTTP_STATUS_CODE or {variable}</StatusCode> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb> <Version>[1.0|1.1|{variable}]</Verb> </Set></AssignMessage>
Example 1
The following example sets a specific header. When this policy is attached in the Request flow, it will allow the upstream system to receive an additional header that was not included in the original inbound request.
<AssignMessage name="AM-Set-Header"> <Set> <Headers> <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header> </Headers> </Set> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The following example overwrites the payload for a response, as well as the Content-Type
header.
<AssignMessage name="AM-Overwrite-Payload"> <Set> <Payload contentType="application/json">{ "status" : 42 }</Payload> </Set> <AssignTo>response</AssignTo> </AssignMessage>
<FormParams>
(child of <Set>
)
Overwrites existing form parameters on a request and replaces them with the new values that you specify with this element. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | Array of <FormParam>
elements |
Parent Element | <Set>
|
Child Elements | <FormParam>
|
The <FormParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <FormParams> <FormParam name=" FORMPARAM_NAME "> FORMPARAM_VALUE </FormParam> ... </FormParams></Set> </AssignMessage>
Example 1
The following example sets a form parameter called myparam
to the value of the request.header.myparam
variable in a new, custom request:
<AssignMessage name="AM-set-formparams-1"> <Set> <FormParams> <FormParam name="myparam">{request.header.myparam}</FormParam> </FormParams> </Set> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
You can use <FormParams>
only when the following criteria are met:
- HTTP verb:
POST
- Message type: Request
If you define empty form parameters in your policy
( <Add><FormParams/></Add>
), the policy does not add any form
parameters. This is the same as omitting the <FormParams>
.
<Set>
changes the Content-Type
of the message to application/x-www-form-urlencoded
before sending it to the target endpoint.
<Headers>
(child of <Set>
)
Overwrites existing HTTP headers in the request or response, which is specified by the <AssignTo>
element.
Default Value | N/A |
Required? | Optional |
Type | Array of <Header>
elements |
Parent Element | <Set>
|
Child Elements | <Header>
|
The <Headers>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <Headers> <Header name=" HEADER_NAME "> HEADER_VALUE </Header> ... </Headers></Set> </AssignMessage>
Example 1
The following example sets the x-ratelimit-remaining
header to the value of the ratelimit.Quota-1.available.count
variable:
<AssignMessage name="AM-Set-RateLimit-Header"> <Set> <Headers> <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header> </Headers> </Set> <AssignTo>response</AssignTo> </AssignMessage>
If you define empty headers in your policy
( <Set><Headers/></Set>
), the policy does not set any headers. This
will have the same effect as omitting <Headers>
.
<Path>
(child of <Set>
)
<Payload>
(child of <Set>
)
Defines the message body for a request or response, which is specified by the <AssignTo>
element. The payload can be any valid content type, such as plain
text, JSON, or XML.
Default Value | empty string |
Required? | Optional |
Type | String |
Parent Element | <Set>
|
Child Elements | None |
The <Payload>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <Payload contentType=" CONTENT_TYPE " variablePrefix=" PREFIX " variableSuffix=" SUFFIX "> NEW_PAYLOAD </Payload></Set> </AssignMessage>
Example 1
The following example sets a plain text payload:
<AssignMessage name="set-payload-1"> <Set> <Payload contentType="text/plain">42</Payload> </Set> </AssignMessage>
Example 2
The following example sets a JSON payload:
<AssignMessage name="set-payload-2"> <Set> <Payload contentType="application/json"> {"name":"foo", "type":"bar"} </Payload> </Set> </AssignMessage>
Example 3
The following example inserts variable values into the payload by wrapping variable names in curly braces:
<AssignMessage name="set-payload-3"> <Set> <Payload contentType="application/json"> {"name":"foo", "type":"{variable_name}"} </Payload> </Set> </AssignMessage>
In older versions of Apigee—for example, prior to cloud release 16.08.17—you could
not use curly braces to denote variable references within JSON payloads. In those releases, you
needed to use the variablePrefix
and variableSuffix
attributes to
specify delimiter characters, and use those to wrap variable names, like so:
<AssignMessage name="set-payload-3b"> <Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set> </AssignMessage>
This older syntax still works.
Example 4
The content of <Payload>
is treated as a message template. This means that the
AssignMessage policy replaces variables wrapped in curly braces with the value of the
referenced variables at runtime.
The following example uses the curly braces syntax to set part of the payload to a variable value:
<AssignMessage name="set-payload-4"> <Set> <Payload contentType="text/xml"> <root> <e1>sunday</e1> <e2>funday</e2> <e3>{var1}</e3> </root> </Payload> </Set> </AssignMessage>
The following table describes the attributes of <Payload>
:
Attribute | Description | Presence | Type |
---|---|---|---|
contentType
|
If specified, the value of |
Optional | String |
variablePrefix
|
Optionally specifies the leading delimiter on a flow variable. Defaults to "{". For more information, see Flow variables reference . | Optional | Char |
variableSuffix
|
Optionally specifies the trailing delimiter on a flow variable. Defaults to "}". For more information, see Flow variables reference . | Optional | Char |
<QueryParams>
(child of <Set>
)
Overwrites existing query parameters in the request with new values. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | Array of <QueryParam>
elements |
Parent Element | <Set>
|
Child Elements | <QueryParam>
|
The <QueryParams>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <QueryParams> <QueryParam name=" QUERYPARAM_NAME "> QUERYPARAM_VALUE </QueryParam> ... </QueryParams></Set> </AssignMessage>
Example 1
The following example sets the address
query parameter to the value of the request.header.address
variable:
<AssignMessage name="AM-set-queryparams-1"> <Set> <QueryParams> <QueryParam name="address">{request.header.address}</QueryParam> </QueryParams> </Set> </AssignMessage>
You can use <QueryParams>
only when the following criteria are met:
- HTTP verbs:
GET
,POST
,PATCH
,DELETE
- Message type: Request
If you define empty query parameters in your policy
( <Set><QueryParams/></Set>
), the policy does not set any query
parameters. This is the same as omitting <QueryParams>
.
<StatusCode>
(child of <Set>
)
Sets the status code on the response. This element has no effect on a request.
Default Value | '200' (when <AssignTo>
's createNew
attribute
is set to 'true') |
Required? | Optional |
Type | String or VARIABLE |
Parent Element | <Set>
|
Child Elements | None |
The <StatusCode>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <StatusCode> HTTP_STATUS_CODE or {variable}</StatusCode></Set> </AssignMessage>
Example 1
The following example sets a simple status code:
<AssignMessage name="AM-set-statuscode-404"> <Set> <StatusCode>404</StatusCode> </Set> <AssignTo>response</AssignTo> </AssignMessage>
Example 2
The content of <StatusCode>
is treated as a message template. This means a
variable name wrapped in curly braces will be replaced at runtime with the value of the
referenced variable, as the following example shows:
<AssignMessage name="set-statuscode-2"> <Set> <StatusCode>{calloutresponse.status.code}</StatusCode> </Set> <AssignTo>response</AssignTo> </AssignMessage>
You can use <StatusCode>
only when the following criteria are met:
- Message type: Response
<Verb>
(child of <Set>
)
Sets the HTTP verb on the request. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | String or VARIABLE |
Parent Element | <Set>
|
Child Elements | None |
The <Verb>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb></Set> </AssignMessage>
Example 1
The following example sets a simple verb on the request:
<AssignMessage name="AM-set-verb-1"> <Set> <Verb>POST</Verb> </Set> <AssignTo>request</AssignTo> </AssignMessage>
Example 2
The content of <Verb>
is treated as a message template. This means a variable name
wrapped in curly braces will be replaced at runtime with the value of the referenced
variable.
The following example uses a variable to populate a verb:
<AssignMessage name="AM-set-verb-to-dynamic-value"> <Set> <Verb>{my_variable}</Verb> </Set> <AssignTo>request</AssignTo> </AssignMessage>
You can use <Verb>
only when the following criteria are met:
- Message type: Request
<Version>
(child of <Set>
)
Sets the HTTP version on a request. This element has no effect on a response.
Default Value | N/A |
Required? | Optional |
Type | String or VARIABLE |
Parent Element | <Set>
|
Child Elements | None |
The <Version>
element uses the following syntax:
Syntax
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name=" POLICY_NAME " > <Set> <Version>[1.0|1.1|{variable}]</Verb></Set> </AssignMessage>
Example 1
The following example sets the version number to 1.1
:
<AssignMessage name="AM-set-version-1"> <Set> <Version>1.1</Version> </Set> </AssignMessage>
Example 2
The following uses a variable in curly braces to set the version number:
<AssignMessage name="AM-set-version-2"> <Set> <Version>{my_version}</Version> </Set> <AssignTo>request</AssignTo> </AssignMessage>
The content of <Version>
is treated as a message template. This means a
variable name wrapped in curly braces will be replaced at runtime with the value of the referenced
variable.
You can use <Version>
only when the following criteria are met:
- Message type: Request
Create custom request messages
You can use AssignMessage to create a custom request message. After you create a custom request, you can use it in the following ways:
- Access its variables in other policies
- Pass it to an external service
To create a custom request message, use the <AssignTo>
element in your AssignMessage
policy. Set createNew
to true
and specify the name of the new message in the body
of the element, as the following example shows:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo>... </AssignMessage>
By default, Apigee does nothing with the custom request message. After creating it, Apigee will continue through the flow with the original request. To use the custom request, add a policy such as the ServiceCallout policy to your proxy, and explicitly reference the newly created request message in the configuration for that policy. This would allow you to pass the custom request to an external service endpoint.
The following examples create custom request messages:
Example 1
The following example creates a custom request object with AssignMessage:
<AssignMessage name="AssignMessage-3"> <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo> <Copy> <Headers> <Header name="user-agent"/> </Headers> </Copy> <Set> <QueryParams> <QueryParam name="address">{request.queryparam.addy}</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
This example:
- Creates a new request message object called
MyCustomRequest
. - On MyCustomRequest, this policy:
- Copies the value of the
user-agent
HTTP header from the incoming request to the new message. Because<Copy>
does not specify thesource
attribute, Apigee will use therequest
message as the source to copy from . - Sets the
address
query parameter on the custom message to the value of the incoming request'saddy
query parameter. - Sets the HTTP verb to
GET
.
- Copies the value of the
- Sets
<IgnoreUnresolvedVariables>
tofalse
. When<IgnoreUnresolvedVariables>
isfalse
, if one of the variables referenced in the policy configuration does not exist, Apigee will enter fault state in the API flow.
Example 2
Here's another example demonstrating how to create a custom request object with AssignMessage:
<AssignMessage name="AssignMessage-2"> <AssignTo createNew="true" type="request">partner.request</AssignTo> <Set> <Verb>POST</Verb> <Payload contentType="text/xml"> <request><operation>105</operation></request> </Payload> </Set> </AssignMessage>
This example creates a new custom request called partner.request
. It then sets the <Verb>
and <Payload>
on the new request.
You can access the various properties of a custom message in another AssignMessage policy that occurs later in the flow. The following example gets the value of a header from a named custom response, and places it into a new header in the request message:
<AssignMessage name="AM-Copy-Custom-Header"> <AssignTo>request</AssignTo> <Set> <Headers> <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header> </Headers> </Set> </AssignMessage>
Error codes
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, see What you need to know about policy errors and Handling faults .
Runtime errors
These errors can occur when the policy executes.
steps.assignmessage.SetVariableFailed
500
steps.assignmessage.VariableOfNonMsgType
500
This error occurs if the source
attribute in the <Copy>
element is set to a variable
which is not of type message
.
Message type variables represent entire HTTP requests and responses. The built-in Apigee
flow variables request
, response
, and message
are of type message. To learn more
about message variables, see the Variables reference
.
steps.assignmessage.UnresolvedVariable
500
This error occurs if a variable specified in the AssignMessage policy is either:
- Out of scope (not available in the specific flow where the policy is being executed) or
- Can't be resolved (is not defined)
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
InvalidIndex
|
If the index specified in the <Copy>
and/or <Remove>
elements of the AssignMessage
policy is 0
or a negative number, then deployment of the API Proxy fails. |
build |
InvalidVariableName
|
If the child element <Name>
is empty or not specified in the <AssignVariable>
element,
then the deployment of the API proxy fails because there is no valid variable name to
which to assign a value. A valid variable name is required. |
build |
InvalidPayload
|
A payload specified in the policy is invalid. |
Fault variables
These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors .
Variables | Where | Example |
---|---|---|
fault.name=" FAULT_NAME
"
|
FAULT_NAME is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "UnresolvedVariable"
|
assignmessage. POLICY_NAME
.failed
|
POLICY_NAME is the user-specified name of the policy that threw the fault. | assignmessage.AM-SetResponse.failed = true
|
Example error response
{ "fault":{ "detail":{ "errorcode":"steps.assignmessage.VariableOfNonMsgType" }, "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message" } }
Example fault rule
<FaultRule name="Assign Message Faults"> <Step> <Name>AM-CustomNonMessageTypeErrorResponse</Name> <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition> </Step> <Step> <Name>AM-CustomSetVariableErrorResponse</Name> <Condition>(fault.name = "SetVariableFailed")</Condition> </Step> <Condition>(assignmessage.failed = true) </Condition> </FaultRule>
Schemas
Each policy type is defined by an XML schema ( .xsd
). For reference, policy schemas
are available on GitHub.
Related topics
Working samples of the AssignMessage policy are available in the API Platform samples .
For a more advanced example of how to override the target.url
from the ProxyEndpoint
, see this Apigee Community article
.
To see a set path
in action in a ServiceCallout policy
, check out this Learn by doing example
in the Apigee GitHub samples. Just clone the repository and
follow the instructions in that topic. The example uses AssignMessage to set a request path,
then uses a ServiceCallout
policy to make the request to an external service.