此页面由 Cloud Translation API 翻译。

AssignMessage 政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

内容

在 API 代理流期间，AssignMessage 政策会更改或创建新的请求和响应消息。该政策可让您对这些消息执行以下操作：

添加新的表单参数、标头或查询参数到消息
复制现有消息到另一消息
移除消息的标头、查询参数、表单参数和/或消息载荷
设置消息中现有属性的值

您通常使用 AssignMessage 政策来添加、更改或移除请求或响应的属性。不过，您也可以使用 AssignMessage 政策创建自定义请求或响应消息，并将其传递给替代目标，如创建自定义请求消息中所述。

使用场景

在很多情况下，您可能需要在 Apigee Edge 处理过程中修改请求或响应消息。例如：

定义查询字符串参数或其他类型输入的默认值。
先从请求消息中删除 HTTP 标头再将消息转发到后端服务。
先添加 HTTP 标头再将响应发送给消费者应用。
先插入 JSON 或 XML 消息内容再发送响应。
生成完整的请求或响应消息。例如，您可以使用 ServiceCallout 政策从 API 代理中调用远程 API。您可以使用 AssignMessage 政策创建自定义请求消息并将它分配给变量。然后，使用“服务调用”将该消息发送到远程 API。
将标头添加至请求和响应以便进行调试和问题排查。

AssignMessage 政策可以使用以下子元素来创建或更改流变量：

`<AssignMessage>` 元素

定义 AssignMessage 政策。

默认值	请参阅下面的默认政策标签页
是否必需？	必需
类型	复杂对象
父元素	不适用
子元素	`<Add>` `<AssignTo>` `<AssignVariable>` `<Copy>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Remove>` `<Set>`

<AssignMessage> 元素使用以下语法：

语法

<AssignMessage> 元素使用以下语法：

<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>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>

  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</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>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>policy_display_name</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</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>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

默认政策

以下示例显示了在 Edge 界面中将 AssignMessage 政策添加至流时的默认设置：

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <ReasonPhrase/>
    <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>

当您在 Edge 界面中插入新的 AssignMessage 政策时，该模板将包含所有可能操作的存根。您通常可以选择要对此政策执行的操作，并移除其余的子元素。例如，如果您要执行复制操作，则使用 <Copy> 元素并从政策中移除 <Add>、<Remove> 和其他子元素，以提高可读性。

此元素具有所有政策中常见的以下属性：

属性	默认	是否必需？	说明
`name`	N/A	必需	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`continueOnError`	false	可选	设置为“false” 可在政策失败时返回错误。这是大多数政策的预期行为。如果设置为“true”，则即使政策失败，仍可继续执行流。
`enabled`	是	可选	设为“true”可强制执行政策。设为“false”可“关闭”政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	false	已弃用	此属性已弃用。

下表提供了 <AssignMessage> 的子元素的简要说明：

子元素	是否必需？	说明
常见操作
`<Add>`	可选	将信息添加到由 `<AssignTo>` 元素指定的消息对象。 `<Add>` 会将原始消息中不存在的标头或参数添加到消息。如需覆盖现有的标头或参数，请使用 `<Set>` 元素。
`<Copy>`	可选	将由 `source` 属性指定的消息中的信息复制到由 `<AssignTo>` 元素指定的消息对象。
`<Remove>`	可选	从在 `<AssignTo>` 元素中指定的消息变量中删除指定的元素。
`<Set>`	可选	替换由 `<AssignTo>` 元素指定的请求或响应中的现有属性的值。 `<Set>` 会覆盖原始消息中已存在的标头或参数。如需添加新的标头或参数，请使用 `<Add>` 元素。
其他子元素
`<AssignTo>`	可选	指定 AssignMessage 政策要处理的消息。这可以是标准请求或响应，也可以是新的自定义消息。
`<AssignVariable>`	可选	将值分配给流变量。如果该流变量不存在，则 `<AssignVariable>` 会创建它。
`<IgnoreUnresolvedVariables>`	可选	确定在遇到无法解析的变量时处理是否停止。

后续各部分介绍了每个子元素。

示例

以下示例展示了使用 AssignMessage 政策的一些方法：

1: 添加标头

以下示例使用 <Add> 元素将标头添加到请求：

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

2: 移除载荷

以下示例使用 <Remove> 元素从响应中删除载荷：

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

3: 修改响应

以下示例通过将标头添加到现有响应对象来修改该对象：

<AssignMessage name="modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" type="response"></AssignTo>
</AssignMessage>

此示例不会创建新消息。而是通过添加 HTTP 标头修改现有的响应消息。

因为此示例在 <AssignTo> 元素中省略了变量名称，并将 type 指定为 “response”，所以此政策会修改目标服务器返回的响应对象。

此政策添加到响应消息中的 HTTP 标头派生自通过 LookupCache 政策填充的变量。因此，此“分配消息”政策修改的响应消息包含一个 HTTP 标头，用于指示是否已从缓存中提取结果。在响应中设置标头可以方便进行调试和问题排查。

4: 设置动态内容

您可以使用“分配消息”将动态内容嵌入到响应和请求消息的载荷中。

如需在 XML 载荷中嵌入 Edge 流变量，请将指定的变量括在大括号中，如下所示：{prefix.name}。

以下示例将 user-agent HTTP 标头流变量的值嵌入在名为 User-agent 的 XML 元素中：

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

对于 JSON 载荷，可以使用带分隔符的 variablePrefix 和 variableSuffix 属性插入变量，如以下示例所示：

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

如需查看流变量的完整列表，请参阅流变量参考。

从 16.08.17 版本开始，您还可以使用大括号来插入变量。

5: 移除查询参数

以下示例从请求中移除 apikey 查询参数：

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

使用 VerifyAPIKey 政策进行用户身份验证时，最佳做法是从请求消息中删除 apikey 查询参数。这样做可以防止将敏感密钥信息传递到后端目标。

6: 设置/获取变量

以下示例使用了三个“分配消息”政策：

使用静态值在请求中创建三个流变量
动态获取请求流的第二个政策中的流变量
在响应的载荷中设置这些变量

<!-- Policy #1: Set variables in the request -->
<AssignMessage continueOnError="false" enabled="true" name="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>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

在第一个政策中，<AssignVariable> 元素在请求中创建并设置三个变量。每个 <Name> 元素都指定一个变量名称，<Value> 指定值。

第二个政策使用 <AssignVariable> 元素读取值并创建三个新的变量：

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

在第二个政策中，<Ref> 元素引用来源变量，<Name> 元素指定新变量的名称。如果 <Ref> 元素引用的变量无法访问，则可以使用由 <Value> 元素指定的值。

如需试用这组政策，请执行以下操作：

将政策 1 和政策 2 添加到请求流。请务必将政策 1 放置在政策 2 前面。
在响应流中添加第三个政策。

第三个政策使用 <Set> 元素将变量添加到响应。以下示例在 Edge 返回到客户端的响应中构造 XML 载荷：

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

请注意，用于访问 <Set> 中流变量的语法是将它们用大括号括起来。

请务必将 <Payload> 元素的 contentType 属性设置为 "application/xml"。

向您的 API 代理发送请求；例如：

curl -vL https://ahamilton-eval-test.apigee.net/myproxy

（可选）您可以通过 xmllint 等实用程序传输结果，使得 XML 以格式设置良好的结构显示：

curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

响应的正文应如下所示：

<wrapper>
  <secret>42</secret>
  <config>
    <environment>test</environment>
    <protocol>gopher</protocol>
  </config>
</wrapper>

7: 获取服务调用响应标头

在以下示例中，假设 ServiceCallout 政策位于 API 代理请求中，调用响应包含多个同名 (Set-Cookie) 的标头。假设服务调用的响应变量是默认的 calloutResponse，以下政策将获取第二个 Set-Cookie 标头值。

<AssignMessage continueOnError="false" enabled="true" name="get-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

如需列出所有标头值，请改用以下变量：

{calloutResponse.header.Set-Cookie.values}

本参考中的每个子元素均有额外的示例。如需更多示例，请参阅 GitHub 上的 AssignMessage 示例。

子元素参考

本部分介绍 <AssignMessage> 的子元素。

`<Add>`

将信息添加到由 <AssignTo> 元素指定的请求或响应。

<Add> 元素会在消息中添加在原始消息中不存在的新属性。要更改现有属性的值，请使用 <Set> 元素。

默认值	不适用
是否必需？	可选
类型	复杂类型
父元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<QueryParams>`

<Add> 元素使用以下语法：

语法

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

示例 1

以下示例使用 <FormParams> 元素获取初始请求中三个查询字符串参数的值，并将它们设置为目标端点请求中的表单参数：

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

示例 2

以下示例使用 <Headers> 元素将 User-Agent 标头添加到目标端点请求：

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

示例 3

以下示例使用 <QueryParams> 元素将带有静态值的单个查询参数添加到请求：

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

此示例在请求 PreFlow 中使用 <Add>。如果您在 Trace 工具等工具中查看结果，则对 "http://httpbin.org/get" 的请求会变成 "http://httpbin.org/get?myParam=42"。

<Add> 的子元素支持名为消息模板的动态字符串替换。

`<FormParams>`（`<Add>` 的子元素）

将新的表单参数添加到请求消息。此元素对响应消息没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<FormParam>` 元素的数组
父元素	`<Add>`
子元素	`<FormParam>`

<FormParams> 元素使用以下语法：

语法

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

示例 1

以下示例将一个表单参数 ("answer") 和一个静态值 ("42") 添加到请求：

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"></AssignTo>
</AssignMessage>

示例 2

以下示例获取 name 查询字符串参数的值，并将它作为表单参数添加到请求：

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
</AssignMessage>

请注意，此示例没有使用 <AssignTo> 指定目标。此政策仅将参数添加到请求。

示例 3

以下示例将多个表单参数添加到请求：

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

此示例从起源请求获取查询字符串参数，并将它们作为表单参数添加到发送到目标端点的请求。

您可以使用 Trace 工具来查看流。您将看到请求的正文包含网址编码的表单数据，这些数据最初是作为查询字符串参数传递的：

%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en

仅在满足以下条件时才能使用 <FormParams>：

HTTP 谓词：POST
消息类型：请求
以下其中一项或全部两项：
- 表单数据：设置为某个值或 “”（空字符串）。例如，使用 curl 将 -d "" 添加到请求。
- Content-Length 标头：设置为 0（如果原始请求中没有数据，否则设置为当前长度，以字节为单位）。例如，使用 curl 将 -H "Content-Length: 0" 添加到请求。

例如：

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

添加 <FormParams> 时，Edge 会先将请求的 Content-Type 标头设置为 "application/x-www-form-urlencoded"，然后再将消息发送到目标服务。

`<Headers>`（`<Add>` 的子元素）

将新的标头添加到由 <AssignTo> 元素指定的请求或响应。

默认值	不适用
是否必需？	可选
类型	`<Header>` 元素的数组
父元素	`<Add>`
子元素	`<Header>`

<Headers> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

示例 1

以下示例将 user-agent 标头添加到请求消息，并将 request.user.agent 流变量的值分配给该标头。

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

`<QueryParams>`（`<Add>` 的子元素）

将新的查询参数添加到请求。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<QueryParam>` 元素的数组
父元素	`<Add>`
子元素	`<QueryParam>`

<QueryParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

示例 1

以下示例将查询参数 "myParam" 添加到请求并为其分配值 “42”：

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

仅在满足以下条件时才能使用 <QueryParams>：

HTTP 谓词：GET
消息类型：请求

此外，仅当 <AssignTo> 元素的 type 属性是请求消息时，才能设置查询参数。在响应中设置它们没有任何影响。

如果您在政策 (<Add><QueryParams/></Add>) 中定义空的查询参数数组，则该政策不会添加任何查询参数。这与省略 <QueryParams> 相同。

`<AssignTo>`

确定 AssignMessage 政策的作用对象。选项包括：

请求消息：API 代理收到的 request
响应消息：从目标服务器返回的 response
自定义消息：自定义请求或响应对象

请注意，在某些情况下，无法更改 AssignMessage 政策的作用对象。例如，您不能使用 <Add> 或 <Set> 来添加或更改响应中的查询参数 (<QueryParams>) 或表单参数 (<FormParams>)。您只能操作请求中的查询参数和表单参数。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<AssignMessage>`
子元素	无

如果您未指定 <AssignTo>，则该政策作用于默认的请求或响应（基于该政策执行位置）。如果该政策在请求流中执行，则它会影响请求消息。如果该政策在响应流中执行，则默认情况下它会影响响应。

<AssignTo> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

示例 1

以下示例指定目标是将发送到目标端点的原始请求：

<AssignMessage name="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

如果将 createNew 设置为 “false”（默认值）时，此示例不会创建新请求。此政策中的所有操作都会影响原始请求。

示例 2

以下示例会创建一个新的请求对象：

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

创建新的请求或响应对象时，AssignMessage 政策的其他元素（例如 <Add>、<Set> 和 <Set>）会作用于这个新的请求对象。

您可以稍后访问流中其他政策中的新请求对象，也可以使用 ServiceCallout 政策将新请求对象发送到外部服务。

示例 3

以下示例会创建一个名为 “MyRequestObject” 的新请求对象：

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>

创建新的请求或响应对象时，AssignMessage 政策的其他元素（例如 <Add>、<Set> 和 <Set>）会作用于这个新的请求对象。

您可以稍后访问流中其他政策中的新请求对象，也可以使用 ServiceCallout 政策将新请求对象发送到外部服务。

下表介绍 <AssignTo> 的属性：

属性说明是否必需？类型

属性	说明	是否必需？	类型
`createNew`	确定在分配值时，该政策是否创建新的消息。如果设置为 “true”，该政策将创建一个由 `type` 指定的类型（“请求”或“响应”）的新变量。如果您未指定新变量的名称，则该政策将根据 `type` 的值创建新的请求或响应对象。注意：创建新请求或响应对象时，系统会删除现有的请求或响应对象并替换为新的请求或响应对象，这意味着对象中的所有信息都会丢失。如果设置为 “false”，则该政策会通过以下两种方式之一做出响应：如果 `<AssignTo>` 可以将变量名称解析为请求或响应，则它会继续处理。例如，如果该政策位于请求流中，则变量是请求对象。如果该政策在响应中，则变量是响应对象。如果 `<AssignTo>` 无法解析或解析为非消息类型，则该政策会抛出错误。如果未指定 `createNew`，则该政策将通过以下两种方式之一做出响应：如果 `<AssignTo>` 解析为消息，则处理将移至下一步。如果 `<AssignTo>` 无法解析或解析为非消息类型，则会创建在 `type` 中指定的类型的新变量。	可选	布尔值
`transport`	指定请求或响应消息类型的传输类型。默认值为 “http”（唯一支持的值）。	可选	字符串
`type`	当 `createNew` 为 “true” 时，指定新消息的类型。有效值为 “request” 或 “response”。默认值为 “request”。如果省略此属性，则 Edge 会创建一个请求或响应，具体取决于此政策执行所在的流。	可选	字符串

createNew

确定在分配值时，该政策是否创建新的消息。

如果设置为 “true”，该政策将创建一个由 type 指定的类型（“请求”或“响应”）的新变量。如果您未指定新变量的名称，则该政策将根据 type 的值创建新的请求或响应对象。

如果设置为 “false”，则该政策会通过以下两种方式之一做出响应：

如果 <AssignTo> 可以将变量名称解析为请求或响应，则它会继续处理。例如，如果该政策位于请求流中，则变量是请求对象。如果该政策在响应中，则变量是响应对象。
如果 <AssignTo> 无法解析或解析为非消息类型，则该政策会抛出错误。

如果未指定 createNew，则该政策将通过以下两种方式之一做出响应：

如果 <AssignTo> 解析为消息，则处理将移至下一步。
如果 <AssignTo> 无法解析或解析为非消息类型，则会创建在 type 中指定的类型的新变量。

可选

布尔值

transport

指定请求或响应消息类型的传输类型。

默认值为 “http”（唯一支持的值）。

可选

字符串

type

当 createNew 为 “true” 时，指定新消息的类型。有效值为 “request” 或 “response”。

默认值为 “request”。如果省略此属性，则 Edge 会创建一个请求或响应，具体取决于此政策执行所在的流。

可选

字符串

`<AssignVariable>`

为目标流变量（例如，由 AssignMessage 政策设置值的变量）分配值。如果该流变量不存在，则 <AssignVariable> 会创建它。

默认值	不适用
是否必需？	可选
类型	复杂类型
父元素	`<AssignMessage>`
子元素	`<Name>` （必需） `<Ref>` `<Template>` `<Value>`

您分配给目标流变量的值可以是以下值之一：

字面量字符串：使用 <Value> 子元素指定目标流变量的字面量字符串值。
流变量：使用 <Ref> 子元素指定目标流变量的现有流变量的值。如需可用作来源的流变量的完整列表，请参阅流变量参考。
消息模板：使用 <Template> 子元素指定目标流变量的消息模板。

<AssignVariable> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

使用 <Ref> 元素指定来源变量。如果 <Ref> 引用的变量不可访问，则 Edge 会使用由 <Value> 元素指定的值。如果您定义了 <Template>，则它的优先级将高于其他子元素。

示例 1

以下示例将新变量 myvar 的值设为字面量值 “42”：

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

示例 2

以下示例将流变量 request.header.user-agent 的值分配给目标流变量 myvar，并将查询参数 country 的值分配给目标流变量 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>

如果任一分配失败，Edge 都会将值“ErrorOnCopy”分配给目标流变量。

如果 myvar 或 Country 流变量不存在，则 <AssignVariable> 会创建它们。

示例 3

以下示例使用 <Template> 子元素使用一个字面量字符串（连字符）将两个上下文变量串联在一起：

<AssignMessage name='template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

<AssignVariable> 的一个常见用例是设置查询参数、标头或可随请求一起传递的其他值的默认值。您可以通过结合使用 <Ref> 和 <Value> 子元素来实现此目的。如需了解详情，请参阅 <Ref> 的示例。

`<Name>`（`<AssignVariable>` 的子元素）

指定目标流变量（例如，由 AssignMessage 政策设置其值的变量）的名称。如果在 <AssignVariable> 中指定的变量不存在，则该政策将使用该名称创建一个变量。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<AssignVariable>`
子元素	无

<Name> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
  </AssignVariable>
</AssignMessage>

示例 1

以下示例将目标变量指定为 myvar，并将其设置为字面量值 “42”：

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

如果 myvar 不存在，则 <AssignVariable> 会创建它。

`<Ref>`（`<AssignVariable>` 的子元素）

将流的来源指定为流变量。流变量可以是预定义的流变量（如流变量参考中列出的流变量）之一，也可以是您创建的自定义流变量。

<Ref> 的值始终解释为流变量；无法指定字面量字符串作为值。如需分配字面量字符串值，请改用 <Value> 元素。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<AssignVariable>`
子元素	无

使用 <Ref> 指定流变量时，请忽略您通常用来引用流变量的括号 “{}”。例如，如需将新变量的值设置为 client.host 流变量的值：

Do this (no brackets):
  <Ref>client.host</Ref>

Do NOT do this (brackets):
  <Ref>{client.host}</Ref>

如需定义目标流变量的默认值，请结合使用 <Value> 和 <Ref>。如果 <Ref> 指定的流变量不存在、无法读取或为 null，则 Edge 会改为将 <Value> 的值分配给目标流变量。

<Ref> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
  </AssignVariable>
</AssignMessage>

示例 1

以下示例将流变量 request.header.user-agent 的值分配给目标流变量 myvar，并将查询参数 country 的值分配给 Country 变量：

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

在此示例中，Edge 没有为任一分配指定默认值（或后备值）。

示例 2

以下示例将流变量 request.header.user-agent 的值分配给目标流变量 myvar，并将查询参数 country 的值分配给 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>

在此示例中，如果 request.header.user-agent 流变量或 Country 查询参数的值为 null、无法读取或格式不正确，则 Edge 会将值“ErrorOnCopy”分配给新变量。

示例 3

<AssignVariable> 的常见用例是设置查询参数、标头或可随请求一起传递的其他值设置默认值。例如，您将创建一个天气 API 代理，在其中，请求会使用名为 “w” 的单个查询参数。此参数包含您想要查看其天气的城市的 ID。请求网址采用以下形式：

http://myCO.com/v1/weather/forecastrss?w=city_ID

如需为“w”定义默认值，请创建如下所示的“分配消息”政策：

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

在此示例中，<AssignVariable> 获取 request.queryparam.w 的值并将该值分配给它本身。如果流变量为 null，表示在请求中省略了 “w” 查询参数，则此示例使用 <Value> 元素中的默认值。因此，您可以省略 “w” 查询参数向此 API 代理发出请求：

http://myCO.com/v1/weather/forecastrss

...并仍会让 API 代理返回有效结果。

与使用 <Value> 时的情况不同，<Ref> 必须是流变量，例如 request、response 或 target 对象的属性。该值也可以是您创建的自定义流变量。

如果指定的流变量在 <Ref> 的值中不存在，并且 <IgnoreUnresolvedVariables> 值为“true”，则 Edge 会抛出错误。

`<Template>`（`<AssignVariable>` 的子元素）

指定消息模板。消息模板可让您在政策执行时执行变量字符串替换，并且可以将字面量字符串与用大括号括起来的变量名称组合起来。此外，消息模板还支持函数，如转义和大小写转换。

使用 ref 属性指定流变量，其值为消息模板。例如，您可以将消息模板存储为开发者应用的自定义属性。当 Edge 在验证 API 密钥或安全令牌（通过其他政策）后识别开发者应用时，<AssignVariable> 元素可以使用应用自定义属性中的消息模板，该模板可作为安全政策中的流变量使用。以下示例假定消息模板存在于进行 API 调用的开发者应用的名为 message_template 的自定义属性中，其中使用了 VerifyAPIKey 政策来验证应用的 API 密钥：

<AssignVariable ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<AssignVariable>`
子元素	无

<Template> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
  </AssignVariable>
</AssignMessage>

示例 1

以下示例使用消息模板语法使用一个字面量字符串（连字符）将两个上下文变量串联在一起：

<AssignMessage name='template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

示例 2

以下示例指定了一个流变量，其值是预定义的消息模板。如果要在运行时注入预定义的模板而无需修改该政策，请使用此选项：

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>

  </AssignVariable>
</AssignMessage>

示例 3

以下示例指定了一个流变量和一个文本值。在这种情况下，如果引用的变量非 null，则该值将用作模板。如果引用的值为 null，则将文本值（在本例中为 {system.uuid}-{messageid}）用作模板。此格式可用于提供“替换”值，在某些情况下，您可能希望使用动态设置的值替换默认模板（文本部分）。例如，条件语句可能会从键值对映射中获取值，并将引用的变量设置为该值：

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

`<Value>`（`<AssignVariable>` 的子元素）

使用 <AssignVariable> 定义目标流变量集的值。该值始终解释为字面量字符串；无法指定字面量字符串作为值，即使您将值用括号 (“{}”) 括起来也不例外。如需使用流程变量，请改用 <Ref>。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<AssignVariable>`
子元素	无

与 <Ref> 元素结合使用时，<Value> 用作默认值（或后备值）。如果 <Ref> 未指定、无法解析或为 null，则使用 <Value> 的值。

<Value> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

示例 1

以下示例将目标流变量的值 myvar 设置为字面量值 “42”：

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

示例 2

以下示例将流变量 request.header.user-agent 的值分配给流变量 myvar，并将查询参数 country 的值分配给 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>

如果任一分配失败，<AssignVariable> 都会将值 “ErrorOnCopy” 分配给目标流变量。

`<Copy>`

将由 source 属性指定的消息中的值复制到由 <AssignTo> 元素指定的消息。如果您没有使用 <AssignTo> 指定目标，则此政策会将值复制到请求或响应，具体取决于此政策执行所在的流。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Path>` `<Payload>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

<Copy> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
    <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</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>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <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>

示例 1

以下示例将请求中的标头、三个表单参数、路径以及所有查询参数复制到新的自定义请求：

<AssignMessage continueOnError="false" enabled="true" name="copy-1">
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1">Header value 1</Header>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_2">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_3">Form param value 1</FormParam>
    </FormParams>
    <Payload>false</Payload>
    <Path>true</Path>
    <QueryParams/>
    <ReasonPhrase>false</ReasonPhrase>
    <StatusCode>false</StatusCode>
    <Verb>false</Verb>
    <Version>false</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

<Copy> 元素具有以下特性：

属性说明是否必需？类型

来源

属性	说明	是否必需？	类型
来源	指定副本的来源对象。如果未指定 `source`，则系统会将其视为简单消息。例如，如果该政策位于请求流程中，则来源默认为 `request` 对象。如果该政策位于响应流中，则默认为 `response` 对象。如果省略 `source`，则可以使用流变量的绝对引用作为复制的来源。例如，您可以将值指定为 `{request.header.user-agent}`。如果来源变量无法解析或解析为非消息类型，则 `<Copy>` 无法响应。	可选	字符串

指定副本的来源对象。

如果未指定 source，则系统会将其视为简单消息。例如，如果该政策位于请求流程中，则来源默认为 request 对象。如果该政策位于响应流中，则默认为 response 对象。如果省略 source，则可以使用流变量的绝对引用作为复制的来源。例如，您可以将值指定为 {request.header.user-agent}。
如果来源变量无法解析或解析为非消息类型，则 <Copy> 无法响应。

可选

字符串

`<FormParams>`（`<Copy>` 的子元素）

将由 <Copy> 元素的 source 属性指定的请求中的表单参数复制到由 <AssignTo> 元素指定的请求。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<FormParam>` 元素的数组或空数组
父元素	`<Copy>`
子元素	`<FormParam>`

<FormParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

示例 1

以下示例将请求中的单个表单参数复制到自定义请求 “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>

示例 2

以下示例将所有表单参数复制到自定义请求 “MyCustomRequest”：

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

示例 3

以下示例将三个表单参数复制到自定义请求 “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>

示例 4

如果有多个具有相同名称的表单参数，请使用以下语法：

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

此示例复制 “f1”、“f2” 和 “f3” 的第二个值。如果 “f3” 只有一个值，则不会复制。

仅在满足以下条件时才能使用 <FormParams>：

HTTP 谓词：POST
消息类型：响应
以下其中一项或全部两项：
- 表单数据：设置为某个值或 “”（空字符串）。例如，使用 curl 将 -d "" 添加到请求。
- Content-Length 标头：设置为 0（如果原始请求中没有数据，否则设置为当前长度）。例如，使用 curl 将 -H "Content-Length: 0" 添加到请求。

复制 <FormParams> 时，<Copy> 会先将消息的 Content-Type 设置为 “application/x-www-form-urlencoded”，然后再将消息发送到目标服务。

`<Headers>`（`<Copy>` 的子元素）

将由 <Copy> 元素的 source 属性指定的请求或响应消息中的 HTTP 标头复制到由 <AssignTo> 元素指定的请求或响应消息。

默认值	不适用
是否必需？	可选
类型	`<Header>` 元素的数组或空数组
父元素	`<Copy>`
子元素	`<Header>`

<Headers> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

示例 1

以下示例将请求中的 user-agent 标头复制到新的自定义请求对象：

<AssignMessage name="copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

示例 2

如需复制所有标头，请使用空的 <Headers> 元素，如以下示例所示：

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

示例 3

如果多个标头同名，请使用以下语法：

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

此示例复制“h1”、“h2”和“h3”的第二个值。如果 “h3” 只有一个值，则不复制。

`<Path>`（`<Copy>` 的子元素）

确定是否应将来源请求中的路径复制到目标请求。此元素对响应没有任何影响。

如果设置为 “true”，则此政策会将由 <Copy> 元素的 source 属性指定的请求消息中的路径复制到由 <AssignTo> 元素指定的请求消息。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<Path> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

示例 1

以下示例表明 AssignMessage 政策应将来源请求中的路径复制到新的自定义请求对象：

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <Path>：

消息类型：请求

`<Payload>`（`<Copy>` 的子元素）

确定是否应将载荷从来源复制到目标。来源和目标可以是请求或响应。

如果设置为 “true”，则此政策将由 <Copy> 元素的 source 属性指定的消息中的载荷复制到由 <AssignTo> 元素指定的消息。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<Payload> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

示例 1

以下示例将 <Payload> 设置为 “true”，以便将请求载荷从请求复制到响应：

<AssignMessage name="copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

`<QueryParams>`（`<Copy>` 的子元素）

将由 <Copy> 元素的 source 属性指定的请求中的查询字符串参数复制到由 <AssignTo> 元素指定的请求。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<QueryParam>` 元素的数组或空数组
父元素	`<QueryParam>`
子元素	无

<QueryParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

示例 1

以下示例将请求中的 "my_param" 查询参数复制到新的自定义请求对象：

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

示例 2

以下示例将所有查询参数从请求复制到新的自定义请求对象：

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

示例 3

如果有多个具有相同名称的查询参数，请使用以下语法：

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

此示例复制 "qp1"、"qp2" 和 "qp3" 的第二个值。如果 "qp3" 只有一个值，则不复制。

仅在满足以下条件时才能使用 <QueryParams>：

HTTP 谓词：GET
消息类型：请求

`<ReasonPhrase>`（`<Copy>` 的子元素）

确定是否应将来源响应中的原因短语复制到目标响应。此元素对请求没有任何影响。

如果设置为 “true”，则此政策会将 ReasonPhrase 从由 <Copy> 元素的 source 属性指定的响应复制到由 <AssignTo> 元素指定的响应。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<ReasonPhrase> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <ReasonPhrase>[false|true]</ReasonPhrase>
  </Copy>
</AssignMessage>

示例 1

以下示例将 <ReasonPhrase> 设置为 “true”，这会导致 <Copy> 将默认响应中的原因语句复制到自定义响应对象：

<AssignMessage name="copy-reasonphrase-1">
  <Copy source="response">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo createNew="trie" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <ReasonPhrase>：

消息类型：响应

`<StatusCode>`（`<Copy>` 的子元素）

确定是否将状态代码从来源响应复制到目标响应。此元素对请求没有任何影响。

如果设置为 “true”，则此政策会将由 <Copy> 元素的 source 属性指定的响应消息中的状态代码复制到由 <AssignTo> 元素指定的响应消息。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<StatusCode> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

示例 1

以下示例将 <StatusCode> 设置为 “true”，这会将默认响应对象中的状态代码复制到新的自定义响应对象：

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <StatusCode>：

消息类型：响应

<StatusCode> 的一个常见用例途是，当 <AssignTo> 的 createNew 属性设置为 “true” 时，确保代理响应的状态与从目标接收到响应的状态相同。

`<Verb>`（`<Copy>` 的子元素）

确定是否将来源请求中的 HTTP 谓词复制到目标请求。此元素对响应没有任何影响。

如果设置为 “true”，则将在 <Copy> 元素的 source 属性中找到的谓词复制到在 <AssignTo> 元素中指定的请求。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<Verb> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

示例 1

以下示例将 <Verb> 设置为 “true”，这会将默认请求中的谓词复制到新的自定义请求：

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <Verb>：

消息类型：请求

`<Version>`（`<Copy>` 的子元素）

确定是否将 HTTP 版本从来源请求复制到目标请求。此元素对响应没有任何影响。

如果设置为 “true”，则将在 <Copy> 元素的 source 属性中找到的 HTTP 版本复制到在 <AssignTo> 元素指定的对象。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Copy>`
子元素	无

<Version> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

示例 1

以下示例会在请求中将 <Version> 设置为 “true”，这会将默认请求对象中的版本复制到新的自定义请求对象：

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <Version>：

消息类型：请求

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 `<DisplayName>`，则会使用政策的 `name` 属性的值
Type	字符串
父元素	<`PolicyElement`>
子元素	无

<DisplayName> 元素使用以下语法：

语法

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

示例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素没有属性或子元素。

`<IgnoreUnresolvedVariables>`

确定在遇到无法解析的变量时处理是否停止。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<AssignMessage>`
子元素	无

设置为 true 可忽略无法解析的变量并继续处理；否则设置为 false。默认值为 false。

将 <IgnoreUnresolvedVariables> 设置为 true 不同于将 <AssignMessage> 的 continueOnError 设置为 true，因为前者专用于设置和获取变量的值。如果将 continueOnError 设置为 true，则 Edge 会忽略所有错误，而不仅仅是忽略使用变量时遇到的错误。

<IgnoreUnresolvedVariables> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</AssignMessage>

示例 1

以下示例将 <IgnoreUnresolvedVariables> 设置为 “true”：

<AssignMessage name="ignoreunresolvedvariables">
  <Copy source="response">
    ...
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  </Copy>
</AssignMessage>

`<Remove>`

移除消息的标头、查询参数、表单参数和/或消息载荷。消息可以是请求消息，也可以是响应消息。您可以使用 <AssignTo> 元素指定 <Remove> 作用于的消息。

默认值	不适用
是否必需？	可选
类型	复杂类型
父元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Payload>` `<QueryParams>`

<Remove> 的一个常见用例是从传入请求对象中删除包含敏感信息的查询参数，以避免将该其传递给后端服务器。

<Remove> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

示例 1

以下示例从响应中移除消息正文：

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

在响应流中，此政策会移除响应的正文，仅将 HTTP 标头返回给客户端。

示例 2

以下示例从传入请求中移除所有表单参数和查询参数：

<AssignMessage continueOnError="false" enabled="true" name="remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

`<FormParams>`（`<Remove>` 的子元素）

从请求中删除指定的表单参数。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<FormParam>` 元素的数组或空数组
父元素	`<Remove>`
子元素	`<FormParam>`

<FormParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

示例 1

以下示例从请求中移除三个表单参数：

<AssignMessage name="remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

示例 2

以下示例从请求中移除所有表单参数：

<AssignMessage name="remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

示例 3

如果有多个具有相同名称的表单参数，请使用以下语法：

<AssignMessage name="remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

此示例移除 “f1”、“f2” 和 “f3” 的第二个值。如果 “f3” 只有一个值，则不移除。

仅在满足以下条件时才能使用 <FormParams>：

消息类型：请求
Content-Type："application/x-www-form-urlencoded"

`<Headers>`（`<Remove>` 的子元素）

从由 <AssignTo> 元素指定的请求或响应中移除指定的 HTTP 标头。

默认值	不适用
是否必需？	可选
类型	`<Header>` 元素的数组或空数组
父元素	`<Remove>`
子元素	`<Header>`

<Headers> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

示例 1

以下示例从请求中移除 user-agent 标头：

<AssignMessage name="remove-headers-1">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

示例 2

以下示例从请求中移除所有标头：

<AssignMessage name="remove-headers-2">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

示例 3

如果多个标头同名，请使用以下语法：

<AssignMessage name="remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

此示例从请求中移除 “h1”、“h2” 和 “h3” 的第二个值。如果 “h3” 只有一个值，则不移除。

`<Payload>`（`<Remove>` 的子元素）

确定 <Remove> 是否会删除由 <AssignTo> 元素指定的请求或响应中的载荷。设置为 “true” 以清除载荷；否则请设置为 “false”。默认值为 “False”。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<Remove>`
子元素	无

<Payload> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

示例 1

以下示例将 <Payload> 设置为 “true”，以便清除请求载荷：

<AssignMessage name="remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

`<QueryParams>`（`<Remove>` 的子元素）

从请求中删除指定的查询参数。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<QueryParam>` 元素的数组或空数组
父元素	`<Remove>`
子元素	`<QueryParam>`

<QueryParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

示例 1

以下示例从请求中移除单个查询参数：

<AssignMessage name="remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

示例 2

以下示例从请求中移除所有查询参数：

<AssignMessage name="remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

示例 3

如果有多个具有相同名称的查询参数，请使用以下语法：

<AssignMessage name="remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

以下示例从请求中移除 “qp1”、“qp2” 和 “qp3” 的第二个值。如果 “qp3” 只有一个值，则不移除。

示例 4

以下示例从请求中移除 apikey 查询参数：

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

仅在满足以下条件时才能使用 <QueryParams>：

HTTP 谓词：GET
消息类型：请求

`<Set>`

设置由 <AssignTo> 元素指定的请求或响应消息中的信息。<Set> 会覆盖原始消息中已存在的标头或参数。要创建新的标头或参数，请改用 <Add> 元素。

默认值	不适用
是否必需？	可选
类型	复杂类型
父元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Payload>` `<Path>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

注意：<Set> 的子元素支持名为消息模板化的动态字符串替换功能。

<Set> 元素使用以下语法：

语法

<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>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

示例 1

以下示例展示了 <Set> 元素：

<AssignMessage continueOnError="false" enabled="true" name="set-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
    <QueryParams>
      <QueryParam name="name">{request.header.name}</QueryParam>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
    <!-- <Verb>GET</Verb> -->
    <Payload contentType="text/plain">42</Payload>
    <Path/>
    <ReasonPhrase>Bad request</ReasonPhrase>
    <StatusCode>400</StatusCode>
    <Verb>POST</Verb>
    <Verb>{my_variable}</Verb>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

`<FormParams>`（`<Set>` 的子元素）

覆盖请求中的现有表单参数，并将其替换为您使用此元素指定的新值。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<FormParam>` 元素的数组
父元素	`<Set>`
子元素	`<FormParam>`

<FormParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

示例 1

以下示例在新的自定义请求中将名为 “myparam” 的表单参数设置为 request.header.myparam 变量的值：

<AssignMessage name="set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
    <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

仅在满足以下条件时才能使用 <FormParams>：

HTTP 谓词：POST
消息类型：请求

如果您在政策 (<Add><FormParams/></Add>) 中定义了空的表单参数，则该政策不会添加任何表单参数。这与省略 <FormParams> 相同。

<Set> 会将消息的 Content-Type 更改为 “application/x-www-form-urlencoded”，再将消息发送到目标端点。

`<Headers>`（`<Set>` 的子元素）

覆盖由 <AssignTo> 元素指定的请求或响应）中的现有 HTTP 标头。

默认值	不适用
是否必需？	可选
类型	`<Header>` 元素的数组
父元素	`<Set>`
子元素	`<Header>`

<Headers> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

示例 1

以下示例将 user-agent 标头设置为 request.header.user-agent 变量的值：

<AssignMessage name="set-headers-1">
  <Set>
    <Headers>
      <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

如果您在政策 (<Add><Headers/></Add>) 中定义了空的标头，则该政策不会添加任何标头。这与省略 <Headers> 相同。

`<Path>`（`<Set>` 的子元素）

注意：

此元素目前未按预期替换/重写代理的目标网址。（它可以在 Service Callout 中设置路径，如下面的“动手实践示例”所示。）

有时，您可能需要将消息发送到在 API 代理的 TargetEndpoint 中定义的网址以外的网址。如果要重写目标网址，请使用 <AssignVariable> 元素替换 TargetEndpoint 中的 target.url 变量。（您无法替换 ProxyEndpoint 中的 target.url，因为 Edge 在 TargetEndpoint 中设置该变量。）

以下示例展示了 AssignMessage 政策如何替换 target.url。同样，将政策添加到 TargetEndpoint 请求。借助此政策，代理会调用下面的网址，而不是调用在 TargetEndpoint 中定义的网址。

<AssignMessage name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

还可以使用 TargetEndpoint 中的 JavaScript 政策来替换 target.url。

`<Payload>`（`<Set>` 的子元素）

定义由 <AssignTo> 元素指定的请求或响应的消息正文。载荷可以是任何有效的内容类型，例如纯文本、JSON 或 XML。

默认值	空字符串
是否必需？	可选
类型	字符串
父元素	`<Set>`
子元素	无

<Payload> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
  </Set>
</AssignMessage>

示例 1

以下示例设置纯文本载荷：

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

示例 2

以下示例设置 JSON 载荷：

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

示例 3

以下示例通过用大括号括住变量名称将变量值插入到载荷中：

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

在较早版本的 Apigee Edge 中（例如，16.08.17 版本之前），您不能在 JSON 载荷中使用大括号表示变量引用。在这些版本中，您需要使用 variablePrefix 和 variableSuffix 属性来指定分隔符，并使用这些属性来封装变量名称，如下面所示：

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

这种较早的语法仍然有效。

示例 4

<Payload> 的内容被视为消息模板。这意味着，AssignMessage 政策在运行时会用所引用变量的值替换用大括号括住的变量。

以下示例使用大括号语法将载荷的一部分设置为变量值：

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

下表介绍 <Payload> 的特性：

属性	说明	状态	类型
`contentType`	如果指定，则会将 `contentType` 的值分配给 `Content-Type` HTTP 标头。	可选	字符串
`variablePrefix`	（可选）指定流变量的前导分隔符。默认值为 “{”。如需了解详情，请参阅流变量参考。	可选	Char
`variableSuffix`	（可选）指定流变量的尾随分隔符。默认值为 “}”。如需了解详情，请参阅流变量参考。	可选	Char

`<QueryParams>`（`<Set>` 的子元素）

使用新值覆盖请求中的现有查询参数。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	`<QueryParam>` 元素的数组
父元素	`<Set>`
子元素	`<QueryParam>`

<QueryParams> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

示例 1

以下示例将 “address” 查询参数设置为 request.header.address 变量的值：

<AssignMessage continueOnError="false" enabled="true" name="set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

仅在满足以下条件时才能使用 <QueryParams>：

HTTP 谓词：GET
消息类型：请求

如果您在政策 (<Set><QueryParams/></Set>) 中定义了空的查询参数，则该政策不会设置任何查询参数。这与省略 <QueryParams> 相同。

`<ReasonPhrase>`（`<Set>` 的子元素）

设置响应的原因短语。这通常用于与 <StatusCode> 结合使用进行调试。此元素对请求没有任何影响。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<Set>`
子元素	无

<ReasonPhrase> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
  </Set>
</AssignMessage>

示例 1

以下示例定义了一个简单的原因短语：

<AssignMessage name="set-reasonphrase-1">
  <Set>
    <ReasonPhrase>Bad medicine</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

示例 2

<ReasonPhrase> 的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称，如以下示例所示：

<AssignMessage name="set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

仅在满足以下条件时才能使用 <ReasonPhrase>：

消息类型：响应

`<StatusCode>`（`<Set>` 的子元素）

设置响应的状态代码。此元素对请求没有任何影响。

默认值	'200'（当 `<AssignTo>` 的 `createNew` 属性设置为 “true” 时）
是否必需？	可选
类型	字符串或 `variable`
父元素	`<Set>`
子元素	无

<StatusCode> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
  </Set>
</AssignMessage>

示例 1

以下示例设置一个简单的状态代码：

<AssignMessage name="set-statuscode-1">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

示例 2

<StatusCode> 的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称，如以下示例所示：

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

仅在满足以下条件时才能使用 <StatusCode>：

消息类型：响应

`<Verb>`（`<Set>` 的子元素）

设置请求的 HTTP 谓词。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	字符串或 `variable`
父元素	`<Set>`
子元素	无

<Verb> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>

示例 1

以下示例设置请求的一个简单谓词：

<AssignMessage name="set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

示例 2

<Verb> 的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称。

以下示例使用变量来填充谓词：

<AssignMessage name="set-verb-2">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

仅在满足以下条件时才能使用 <Verb>：

消息类型：请求

`<Version>`（`<Set>` 的子元素）

设置请求的 HTTP 版本。此元素对响应没有任何影响。

默认值	不适用
是否必需？	可选
类型	字符串或 `variable`
父元素	`<Set>`
子元素	无

<Version> 元素使用以下语法：

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

示例 1

以下示例将版本号设置为 “1.1”：

<AssignMessage name="set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

示例 2

以下变量使用用大括号括住的变量设置版本号：

<AssignMessage name="set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

<Version> 的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称。

仅在满足以下条件时才能使用 <Version>：

消息类型：请求

创建自定义请求消息

您可以使用 AssignMessage 政策创建自定义请求消息。创建自定义请求后，您可以通过以下方式使用它：

在其他政策中访问它的变量
将它传递到外部服务

如需创建自定义请求消息，请在 AssignMessage 政策中使用 <AssignTo> 元素。将 createNew 设置为 “true”，并在元素正文中指定新消息的名称，如以下示例所示：

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

默认情况下，Edge 不会对自定义请求消息执行任何操作。创建之后，Edge 将以原始请求继续执行流。如需使用自定义请求，请政策（例如 ServiceCallout 政策）添加到代理，以便将自定义请求传递到外部服务。

以下示例创建自定义请求消息：

示例 1

以下示例使用“分配消息”创建自定义请求对象：

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

以下示例：

创建名为 “MyCustomRequest” 的新请求消息对象。
在 MyCustomRequest 中，此政策：
- 将传入请求的 user-agent HTTP 标头的值复制到新消息。因为 <Copy> 使用对 user-agent 流变量的绝对引用，所以不需要将 source 属性指定为 <Copy>。
- 将自定义消息的 address 查询参数设置为传入请求的 addy 查询参数的值。
- 将 HTTP 谓词设置为 GET。
将 <IgnoreUnresolvedVariables> 设置为 “false”。当 <IgnoreUnresolvedVariables> 为 “false” 时，如果政策尝试添加的其中一个变量不存在，则 Edge 将停止在 API 流中处理。

示例 2

以下示例说明了如何使用“分配消息”创建自定义请求对象：

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

此示例创建一个名为 “partner.request” 的新自定义请求。然后，该方法会在新请求上设置 <Verb> 和 <Payload>。

您可以在流中后面部分出现的另一个 AssignMessage 政策中访问自定义请求消息。以下示例获取自定义请求消息的 user-agent 标头的值：

<AssignMessage name="custom-request-1-access">
  <DisplayName>custom-request-1-access</DisplayName>
  <AssignTo createNew="false" type="request"></AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

视频

观看以下视频，详细了解 AssignMessage 政策。

视频	说明
为什么要使用分配消息政策？	了解使用 AssignMessage 政策修改 API 请求或响应而无需修改后端代码的优势。
使用 AssignMessage 政策复制 API 元素	复制 API 请求或响应中的元素并使用 AssignMessage 政策构造新的请求或响应对象。
使用 AssignMessage 政策移除 API 元素	移除 API 元素并使用 AssignMessage 政策修改 API，然后再将 API 传送到目标后端。
使用 AssignMessage 政策添加和设置 API 元素	使用 AssignMessage 政策添加查询参数、标头、表单参数或载荷，以更改 API 请求或响应。
使用 AssignMessage 政策创建自定义变量	使用 AssignMessage 政策设置自定义流变量以及利用 API 代理中的其他政策中的变量。
使用 AssignMessage 政策创建新的请求或响应对象	在 API 运行时中使用 AssignMessage 政策创建新的 API 请求或响应对象。
使用 AssignMessage 政策创建模拟 API	通过在响应流中添加 AssignMessage 政策来创建简单的模拟 REST API。
使用 AssignMessage 政策设置或修改载荷	通过在 API 运行时中使用“分配消息”政策设置 SOAP 载荷，将 REST 请求转换为 SOAP 请求。

错误代码

本部分介绍了此政策触发错误时返回的错误代码和错误消息，以及 Edge 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态原因修复

steps.assignmessage.SetVariableFailed 500 该政策无法设置变量。请参阅故障字符串，查看未解析变量的名称。

故障代码	HTTP 状态	原因
`steps.assignmessage.SetVariableFailed`	500	该政策无法设置变量。请参阅故障字符串，查看未解析变量的名称。
`steps.assignmessage.VariableOfNonMsgType`	500	如果 `<Copy>` 元素中的 `source` 属性类型不是消息类型，则会出现此错误。消息类型变量表示整个 HTTP 请求和响应。内置 Edge 流变量 `request`、`response` 和 `message` 都属于消息类型。如需详细了解消息变量，请参阅变量参考。
`steps.assignmessage.UnresolvedVariable`	500	如果“分配消息”政策中指定的变量为以下任一项，就会出现此错误：超出范围（在执行政策的特定流中不可用）或无法解析（未定义）

steps.assignmessage.VariableOfNonMsgType

500

如果 <Copy> 元素中的 source 属性类型不是消息类型，则会出现此错误。

消息类型变量表示整个 HTTP 请求和响应。内置 Edge 流变量 request、response 和 message 都属于消息类型。如需详细了解消息变量，请参阅变量参考。

steps.assignmessage.UnresolvedVariable

500

如果“分配消息”政策中指定的变量为以下任一项，就会出现此错误：

超出范围（在执行政策的特定流中不可用）
无法解析（未定义）

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	原因	修复
`InvalidIndex`	如果在“分配消息”政策的 `<Copy>` 和/或 `<Remove>` 元素中指定的索引为 0 或负数，则 API 代理的部署会失败。
`InvalidVariableName`	如果子元素 `<Name>` 为空或未在 `<AssignVariable>` 元素中指定，则 API 代理的部署将失败，因为没有向其分配值的有效变量名称。必须提供有效的变量名称。
`InvalidPayload`	政策中指定的负载无效。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	地点	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "UnresolvedVariable"`
`assignmessage.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`assignmessage.AM-SetResponse.failed = true`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

故障规则示例

<faultrule name="VariableOfNonMsgType"></faultrule><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>

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

AssignMessage 政策

内容

使用场景

<AssignMessage> 元素

语法

默认政策

示例

1: 添加标头

2: 移除载荷

3: 修改响应

4: 设置动态内容

5: 移除查询参数

6: 设置/获取变量

7: 获取服务调用响应标头

子元素参考

<Add>

语法

示例 1

示例 2

示例 3

<FormParams>（<Add> 的子元素）

语法

示例 1

示例 2

示例 3

<Headers>（<Add> 的子元素）

语法

示例 1

<QueryParams>（<Add> 的子元素）

语法

示例 1

<AssignTo>

语法

示例 1

示例 2

示例 3

<AssignVariable>

语法

示例 1

示例 2

示例 3

<Name>（<AssignVariable> 的子元素）

语法

示例 1

<Ref>（<AssignVariable> 的子元素）

语法

示例 1

示例 2

示例 3

<Template>（<AssignVariable> 的子元素）

语法

示例 1

示例 2

示例 3

<Value>（<AssignVariable> 的子元素）

语法

示例 1

示例 2

<Copy>

语法

示例 1

<FormParams>（<Copy> 的子元素）

语法

示例 1

示例 2

示例 3

示例 4

<Headers>（<Copy> 的子元素）

语法

示例 1

示例 2

示例 3

<Path>（<Copy> 的子元素）

语法

示例 1

<Payload>（<Copy> 的子元素）

语法

示例 1

<QueryParams>（<Copy> 的子元素）

语法

`<AssignMessage>` 元素

`<Add>`

`<FormParams>`（`<Add>` 的子元素）

`<Headers>`（`<Add>` 的子元素）

`<QueryParams>`（`<Add>` 的子元素）

`<AssignTo>`

`<AssignVariable>`

`<Name>`（`<AssignVariable>` 的子元素）

`<Ref>`（`<AssignVariable>` 的子元素）

`<Template>`（`<AssignVariable>` 的子元素）

`<Value>`（`<AssignVariable>` 的子元素）

`<Copy>`

`<FormParams>`（`<Copy>` 的子元素）

`<Headers>`（`<Copy>` 的子元素）

`<Path>`（`<Copy>` 的子元素）

`<Payload>`（`<Copy>` 的子元素）

`<QueryParams>`（`<Copy>` 的子元素）

`<ReasonPhrase>`（`<Copy>` 的子元素）

`<StatusCode>`（`<Copy>` 的子元素）

`<Verb>`（`<Copy>` 的子元素）

`<Version>`（`<Copy>` 的子元素）

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

`<FormParams>`（`<Remove>` 的子元素）

`<Headers>`（`<Remove>` 的子元素）

`<Payload>`（`<Remove>` 的子元素）

`<QueryParams>`（`<Remove>` 的子元素）

`<Set>`

`<FormParams>`（`<Set>` 的子元素）

`<Headers>`（`<Set>` 的子元素）

`<Path>`（`<Set>` 的子元素）

`<Payload>`（`<Set>` 的子元素）

`<QueryParams>`（`<Set>` 的子元素）

`<ReasonPhrase>`（`<Set>` 的子元素）

`<StatusCode>`（`<Set>` 的子元素）