Was this helpful?

There are many situations in which a request or a response message must be modified during processing by Apigee Edge. For example, you might need to strip HTTP headers from a request message before the message is forwarded to the backend service. You might also need to add HTTP headers or insert JSON or XML message content before a response is sent to the consumer app. You can do both operations using the AssignMessage policy type.

In other situations, you need to generate complete request or response messages. For example, you might use a ServiceCallout policy to invoke a remote API from an API proxy. You can use the AssignMessage policy to generate the request message that will be submitted by the ServiceCallout policy.

The AssignMessage policy is used to generate or modify request or response messages during an API proxy Flow.

AssignMessage is so named because the policy requires a message to be 'assigned' as a variable. A variable is a property of a request/response transaction handled by an API proxy. Variables provide a rich context for API proxies, enabling information to be shared by policies and code. In this case, you use variables to obtain dynamic content to populate messages.

For example, you can assign a request message to a variable and then reference that variable in a ServiceCallout policy. The ServiceCallout policy, by referencing the variable that contains the message you assigned, can use the message as a request to send to a remote service or API.

To use AssignMessage, you select any variable and then assign a message to it. Usually, you define a custom variable by creating a variable with a name that you choose. In the following example, the request message generated by the AssignMessage policy is assigned to a variable called partner.request. (You could also call this variable foo.bar; it is only used as namespace for sharing messages.)

Samples

For example, the policy below would modify a request message:

<AssignMessage name="partnerRequest">
    <AssignTo createNew="false">partner.request</AssignTo>
</AssignMessage>

The examples above result in an empty message. To work with message content, AssignMessage defines a set of elements that enable you to populate or modify HTTP headers, query parameters, and XML or JSON payload content.

For example the policy below creates a new HTTP request message, and assigns that message to the variable called partner.request.

<AssignMessage name="partnerRequest">
  <AssignTo createNew="true" transport="http" type="request">request</AssignTo>
</AssignMessage>

In this simple policy, you indicate that the policy should create a new message. If this value is set to false, then the policy will modify, in place, the request or response message where the policy is attached.

For example, the following AssignMessage policy creates a new request message, populated with the user-agent HTTP header from the source message, along with one query parameter derived from the source message request. Since the message generated by this policy is a request, the HTTP verb must be set, in this example to GET.

In the configuration below, the IgnoreUnresolvedVariables element is set to false. When set to true, the API proxy Flow continues processing when a variable does not resolve to a value.

<AssignMessage name="GenerateRequest">
  <AssignTo createNew="true" type="request">Request</AssignTo>
  <Copy>
    <Headers>
     <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.address}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

The following AssignMessage policy does not create a new message. Instead, it modifies an existing response message by adding an HTTP header. 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 AssignMessage policy contains an HTTP header that indicates whether the results have been pulled from the Cache or not. (This usage is great for debugging and troubleshooting.)

<AssignMessage name="api-token-cache-hit-header">
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <Set>
    <Headers>
      <Header name="API-Token-Cache-Hit">{lookupcache.api-token-lookup-cache.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

You can also use AssignMessage to embed dynamic content in the payload of XML or JSON messages. The standard practice for embedding variables in XML is to wrap the designated variable in curly braces, that is {prefix.name}, in the element or attribute where the content should be embedded. For example, to embed the HTTP user-agent header in an XML element called user-agent, you can do the following:

<Payload contentType="tex/xml">
  <User-agent>{request.header.user-agent}</User-agent>
</Payload>

With JSON, however, curly braces cannot be used to identify variables. Instead, you must declaratively configure the characters that will delimit the variable. For example, to embed the variable request.header.user-agent in a JSON property called user-agent, you can do the following:

<Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
    "user-agent": "@request.header.user-agent#"
  }
</Payload>

Working samples of the AssignMessage policy are available in the API Platform samples.

Configuring an AssignMessage policy

Configure the AssignMessage policy using the following elements.

Field Name Description
AssignTo (Optional)
Specifies the variable to which the message will be assigned.
  • If the AssignTo element is missing, it is treated as request or response, depending on the Flow to which the policy is attached. If attached to a request Flow, for example, the default type is request.
  createNew
If createNew is set to true, then a new variable of the type specified in type is created.
If createNew is set to false, then AssignTo responds in one of two ways:
  • If AssignTo resolves to a message, then it continues to the next flow.
  • If AssignTo cannot be resolved, or resolves to a non-message type, then the policy throws an error.
If createNew is not specified, AssignTo 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 in type is created.
type (Optional)
Specifies the type of the variable.
Valid values: request/response
Default value: request
IgnoreUnresolvedVariables (Optional)
If IgnoreUnresolvedVariables is set to false and any variable cannot be resolved, then the policy throws a fault. 
If it is set to true and any variable is unresolvable, the variable is treated as empty string (Null).
Valid values: true/false
Default value: false
Copy (Optional) source
Copies the specified information from the <source> to the variable specified in the <AssignTo> element.
  • If the source is not specified, it is treated as a simple message.
  • If the source variable can not be resolved, or resolves to a non-message type, <Copy> fails to respond.
Headers Copies HTTP headers. To copy all headers, specify <Copy><Headers/></Copy>
QueryParams Copies query parameters. Note that the QueryParams is copied only when both the source and AssignTo type are request. To copy all query parameters, specify <Copy><QueryParams/></Copy>.
FormParams Copies the form parameters. Note that the FormParams is copied only when the contentType is source and AssignTo is application/x-www-form-urlencoded. To copy all form parameters, specify <Copy><FormParams/></Copy>.
Payload Valid values: true/false. If true, the Content-Type header is copied.
Version Valid values: true/false. If true, the HTTP version is copied.
Verb Valid values: true/false. If true, it is assigned only when both the source and AssignTo type are request.
Path
StatusCode Valid values: true/false. If true, it is assigned only when both the source and AssignTo type are response.
ReasonPhrase
Remove (Optional) Headers Removes HTTP headers from the variable specified in the <AssignTo> element. To remove all the headers, specify <Remove><Headers/></Remove>
QueryParams Removes the query parameters. Note that the QueryParams are removed only when the AssignTo type is request. To remove all query paremeters, specify <Remove><QueryParams/></Remove>.
FormParams Removes the form parameters. Note that FormParams are removed only when the contentType of AssignTo is application/x-www-form-urlencoded. To remove all form parameters, specify <Remove><FormParams/></Remove>.
Payload Valid values: true/false. If true, the payload is cleared.
Add (Optional) Headers Adds the headers in the variable specified in the <AssignTo> element. Note that the empty header <Add><Headers/></Add> does not add any header. The same holds true for QueryParams and FormParams.
QueryParams Adds the query parameters.
FormParams Adds the form parameters and the contentType of message is changed to application/x-www-form-urlencoded.
Set (Optional) Headers Sets/overwrites the HTTP headers in the variable specified in the <AssignTo> element. Note that the empty header <Set><Headers/></Set> does not set any header. The same holds true for QueryParams and FormParams.
QueryParams Sets/overwrites the query parameters.
FormParams Sets/overwrites the form parameters and the contentType of message changes to application/x-www-form-urlencoded.
Payload You are allowed to set mixed payload contents. For example, <root1>sunday</root1><root2>funday</root2><root3>{var1}</root3>.
  contentType If contentType is specified, its value is treated as message template, and assigned to the contentType header.
Version Sets the version. Note that the content of <Version> is treated as message template. The same holds true for Verb, Path, StatusCode, and ReasonPhrase.
Verb Sets the HTTP verb and path only when AssignTo type is request.
Path
StatusCode Sets the status code and reason phrase only when AssignTo type is response.
ReasonPhrase
AssignVariable (Optional) Name Specifies the name of the variable.
Ref Reference that assigns value to the variable.
Value If <Ref> is not specified or is unresolvable, this value is assigned to the variable.

Example - AssignMessage policy

<AssignMessage name="create1">
<AssignTo type="[request]/response" createNew="[true]/false">sc.request</AssignTo>
<IgnoreUnresolvedVariables>true/[false]</IgnoreUnresolvedVariables>

// allow any order
<Copy source="request"> // if no children do copy all
    <Headers>
        <Header name="h1"/>
        <Header name="h2"/>
    </Headers>
    <QueryParams>
        <QueryParam name="q1"/>
        <QueryParam name="q2"/>
    </QueryParams>
    <FormParams>
        <FormParam name="f1"/>
        <FormParam name="f2"/>
    </FormParams>
    <Payload>true/[false]</Payload>
    <Verb>true/[false]</Verb>
    <Path>true/[false]</Path>
</Copy>

<Remove> // if no children do remove all
    <Headers>
        <Header name="h1"/>
        <Header name="h2"/>
    </Headers>
    <QueryParams>
        <QueryParam name="q1"/>
        <QueryParam name="q2"/>
    </QueryParams>
    <FormParams>
        <FormParam name="f1"/>
        <FormParam name="f2"/>
    </FormParams>
    <Payload>true</Payload>
</Remove>

<Add>
    <Headers>
        <Header name="h1">my{variable.v1}</Header>
    </Headers>
    <QueryParams>
        <QueryParam name="q1">my{variable.v1}</QueryParam>
    </QueryParams>
    <FormParams>
        <FormParam name="f1">my{variable.v1}</FormParam>
    </FormParams>
</Add>

<Set>
    <Headers>
        <Header name="h1">my{variable.v1}</Header>
    </Headers>
    <QueryParams>
        <QueryParam name="q1">my{variable.v1}</QueryParam>
    </QueryParams>
    <FormParams>
        <FormParam name="f1">my{variable.v1}</FormParam>
    </FormParams>

    <Payload contentType="text/xml">
        <root>this is my payload {variable.v1}</root>
    </Payload>

    <Verb>${variable.v1}</Verb>
    <Path>abc/def/{varaiable.v1}/d</Path>
</Set>

<AssignVariable>
    <Name>response.header.xyz</Name>
    <Ref>request.queryparam.abc</Ref>
    <Value>hello!</Value>
</AssignVariable>
</AssignMessage>

Policy-specific error codes

The default format for error codes returned by Policies is:

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

The AssignMessage Policy type defines the following error codes:

Error Code Message
UnresolvedVariable AssignMessage[{0}]: unable to resolve variable {1}
VariableOfNonMsgType AssignMessage[{0}]: value of variable {1} is not of type Message
SetVariableFailed AssignMessage[{0}]: failed to assign message to {1}
InvalidIndex AssignMessage[{0}]: index must be greater than zero in {1}
InvalidVariableName AssignMessage schema validation failed: invalid variable name - {0} - in assign variable
InvalidPayload Invalid payload {0}

Policy schema

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

コメント

Please add the following feature description (Variable Prefix and Suffix) to this page of documentation:

If the Payload of an AssignMessage policy is JSON. The variable delimiter conflicts with JSON syntax.
Then changing the variable delimiter helps in this case. An example given below

{
"Username":"#username%",
"Email":"#user_email%",
}

In the above example, "username" and "user_email" are variables that Edge resolves correctly.

Please add the following feature description (Variable Prefix and Suffix) to this page of documentation:

If the Payload of an AssignMessage policy is JSON. The variable delimiter conflicts with JSON syntax.
Then changing the variable delimiter helps in this case. An example given below

{
"Username":"#username%",
"Email":"#user_email%",
}

In the above example, "username" and "user_email" are variables that Edge resolves correctly.

コメントを追加

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

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

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