AssignMessage 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

内容

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

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

分配消息时，您还可以设置任意上下文变量，与上述可能适用于消息的任何操作无关。

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

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

使用场景

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

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

视频

观看以下视频，详细了解 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 运行时中使用 AssignMessage 政策设置 SOAP 载荷，将 REST 请求转换为 SOAP 请求。

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

您用于组织 <Add>、<Copy>、<Set> 和 <Remove> 元素的顺序很重要。政策按照这些操作在政策配置中出现的顺序执行这些操作。如果您需要移除所有标头，然后设置特定标头，则应该在 <Set> 元素之前添加 <Remove> 元素。

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

默认政策

以下示例显示了在 Apigee 界面中将 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/>
    <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>

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

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

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

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

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

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

示例

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

1: 添加标头

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

<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> 元素从响应中删除载荷：

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

3: 修改响应

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

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

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

因为此示例在 <AssignTo> 元素中指定 response 作为变量名称，所以此政策会修改最初由目标服务器返回的数据设置的响应对象。

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

4: 设置动态内容

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

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

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

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

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

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

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

您还可以使用大括号来插入变量。

5: 移除查询参数

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

6: 设置/获取变量

以下示例使用了三个“AssignMessage”政策：

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

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

在第一个政策中，<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 响应标头

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

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

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

{calloutResponse.header.Set-Cookie.values}

8：存储和移除表单参数、标头、查询参数

如果您要使用 <Remove> 删除标头、查询参数或表单参数，但稍后在政策流中保留对它们值的访问权限，则可以使用 <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>

注意：在分配消息政策中使用 <Remove> 剥离的表单参数、标头和查询参数在政策流完成后无法访问，除非它们的值存储在变量中，如本示例所述。

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

子元素参考

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

`<Add>`

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

<Add> 元素会在消息中添加在原始消息中不存在的新属性。请注意，<Set> 也提供此功能。如需更改现有属性的值，请使用 <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 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>

示例 2

以下示例使用 <Headers> 元素将 partner-id 标头添加到将发送到目标端点的请求：

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

示例 3

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

此示例在请求 PreFlow 中使用 <Add>。如果您在调试概览等工具中查看结果，则对 https://example-target.com/get 的请求将变为 https://example-target.com/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 name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 2

以下示例获取 name 查询参数的值，并将其作为表单参数添加到请求中，然后移除该查询参数：

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

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

示例 3

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

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

此示例从起源请求获取查询字符串参数，并将它们添加为具有不同名称的表单参数。然后移除原始查询参数。 Apigee 会将修改后的请求发送到目标端点。

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

username=nick&zip_code=90210&default_language=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> 时，Apigee 会将请求的 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

以下示例将 partner-id 标头添加到请求消息，并将 verifyapikey.VAK-1.developer.app.partner-id 流变量的值分配给该标头。

<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>`（`<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 name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

HTTP 动词：GET、POST、PATCH、DELETE
消息类型：请求

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

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

`<AssignTo>`

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

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

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

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

如果未指定 <AssignTo>，或者如果指定了 <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

以下示例指定了 <AssignTo> 文本中没有消息。这意味着政策将应用于 request 或 response 消息，具体取决于政策执行的位置。

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

如果您指定了 createNew="false"，并且未明确提供消息名称，则 <AssignTo> 的其他特性无关。在这种情况下，您可能希望完全省略 <AssignTo> 元素。

示例 2

以下示例会创建一个新的请求对象，并覆盖现有对象：

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

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

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

示例 3

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

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

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

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

下表介绍 <AssignTo> 的特性：

特性说明是否必需？类型

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

createNew

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

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

如果为 false，则政策将通过以下两种方式之一做出响应：

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

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

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

可选

布尔值

transport

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

默认值为 http（这是唯一支持的值）。

可选

字符串

type

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

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

可选

字符串

`<AssignVariable>`

为目标流变量（例如，由 AssignMessage 政策设置值的变量）分配值。如果该流变量不存在，则 <AssignVariable> 会创建它。您可以在 AssignMessage 政策中使用多个 AssignVariable 元素。它们按照在政策配置中的显示顺序执行。

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

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

字面量字符串：使用 <Value> 子元素指定目标流变量的字面量字符串值。
流变量：使用 <Ref> 子元素指定目标流变量的现有流变量的值。如需可用作来源的流变量的完整列表，请参阅流变量参考。
属性集：使用 <PropertySetRef> 子元素从属性集名称/密钥对中检索值，并将其存储在流变量中。可让您动态访问属性集。
资源网址：使用 <ResourceURL> 子元素指定 XSL、XSD、WSDL、JavaScript 或 OpenAPI Spec 类型的文本资源的网址。这会将资源的内容分配到已命名的流变量中。
消息模板：使用 <Template> 子元素指定目标流变量的消息模板。

这些子元素的优先顺序为：ResourceURL、Template、Ref、Value、PropertySetRef。

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

语法

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

使用 <Ref> 元素指定来源变量。如果 <Ref> 引用的变量不可访问，则 Apigee 会使用由 <Value> 元素指定的值。如果您定义 <Template>，则它优先于 <Ref> 和 <Value> 同级元素。

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

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

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

示例 3

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

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

示例 4

以下示例使用 <AssignVariable> 停用将代理请求中的路径后缀传播到目标请求的默认行为：

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

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

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

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

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<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> 会创建它。

注意：ratelimit 名称已被保留。如需了解详情，请参阅 Apigee 社区中的配额政策抛出 NullPointerException。

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

此元素可让您动态检索某个属性集名称/键的值。如需了解属性集，请参阅使用属性集。

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

属性集由名称/键对组成。例如：propset1.id=12345，其中 propset1 是属性集的名称，id 是键，12345 是键的值。

PropertySetRef 子元素可让您动态选择属性集名称和/或键。假设您在属性集文件中有 200 个路由规则。您可以按如下方式访问属性集规则，其中 routingrules 是属性集名称，rule1、rule2 和 rulen 是键：

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

如需在 API 代理流中访问这些属性，您必须在设计时知道要选择哪个规则。但是，假设规则名称出现在请求标头或载荷中。选择规则的一种方法是使用具有如下代码的 JavaScript 政策：

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

另一方面，AssignMessage PropertySetRef 功能可让您动态选择属性键，而无需引入 JavaScript。

您可以在 <PropertySetRef> 元素中混合使用流变量和字面量字符串值。如需了解详情，请参阅示例。

注意：在使用此功能时，不要使用前缀 propertyset 来引用属性集，如 propertyset.PROPNAME.KEY 中所示。假定前缀为 propertyset。

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

示例 1

本例将属性集键中的值分配给流变量。在本例中，属性集名称是从标头 propset_name 中获取的，键由标头 propset_key 提供，分配给键的值存储在变量 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>

您可以在 <PropertySetRef> 元素中使用流变量和字面量字符串的任意组合。

示例 2

本示例使用固定键名（字面量字符串）将属性集键的值分配给流变量。在这种情况下，属性集名称是从标头 propset_name 中获取的，键是字面量字符串 key1，分配给键的值存储在变量 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>

您可以在 <PropertySetRef> 元素中使用流变量和字面量字符串的任意组合。

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

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

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

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

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

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

如需定义目标流变量的默认值，请结合使用 <Value> 和 <Ref>。如果 <Ref> 指定的流变量不存在、无法读取或为 null，则 Apigee 会改为将 <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>

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

示例 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、无法读取或格式不正确，则 Apigee 会将值 ErrorOnCopy 分配给新变量。

示例 3

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

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

如需为 w 定义默认值，请创建 AssignMessage 政策，如下所示：

<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 代理返回有效结果。

<Ref> 的值必须是流变量，例如 request、response 或target 对象或自定义流变量的名称。

如果您为 <Ref> 的值指定的流变量不存在，且 <IgnoreUnresolvedVariables> 值为 false，则 Apigee 会抛出错误。

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

将文本资源的网址指定为变量赋值的来源。Apigee 会加载 <Name> 中指定的流变量和所引用资源的内容。资源的类型可以是 XSD、XSL、WSDL、JavaScript、属性集或 OpenAPI Spec。

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

如果 <ResourceURL> 指定的资源不存在，那么：如果 <IgnoreUnresolvedVariables> 的值为 true，Apigee 会将值 null 分配给目标流变量，而如果 <IgnoreUnresolvedVariables> 的值为 false，Apigee 会抛出错误。

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>

文本值采用字符串值，并被解释为消息模板。以下均有效：

<ResourceURL>jsc://my-js-file.js</ResourceURL>
<ResourceURL>wsdl://{variable-goes-here}</ResourceURL>
<ResourceURL>{variable-goes-here}</ResourceURL>

示例 1

以下示例将加载到 jsc 文件夹中的代理中的 JSON 资源值分配给流变量 assigned-variable：

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

示例 2

以下示例将加载到 oas 文件夹中的代理中的 OpenAPI Spec 资源的值分配到流变量 assigned-variable 中，然后将该值设置为响应正文中的 Payload：

<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>`（`<AssignVariable>` 的子元素）

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

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

<Template 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='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

示例 2

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

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

示例 3

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

<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>`（`<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>` `<StatusCode>` `<Verb>` `<Version>`

如果您在 <Copy> 元素下未指定子元素，则将复制指定源消息的所有部分。

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

语法

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

示例 1

以下示例将请求中的 request 消息中的标头、三个表单参数、路径以及所有查询参数复制到新的自定义请求 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>

由于 <Payload> 和 <Verb> 等元素不存在，因此政策不会复制消息的这些部分。

示例 2

以下示例首先移除现有 response 消息中的所有内容，然后将名为 secondResponse 的其他消息中的所有值复制到 response 消息中：

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

<Copy> 元素具有单一特性：

特性说明是否必需？类型

source

特性	说明	是否必需？	类型
source	指定副本的来源对象。如果未指定 `source`，则默认为 `message`，根据政策执行所在的流程，该值会有所不同。如果政策在请求流中执行，则 `message` 变量会引用 `request` 对象。如果政策在响应流中执行，则 `message` 变量会引用 `response` 对象。如果 `source` 特性中指定的变量无法解析或解析为非消息类型，则 `<Copy>` 无效。确保您为 `source` 指定的值与目标消息不同，无论是默认目标消息还是使用 `<AssignTo>` 明确指定的目标。如果 `source` 与目标消息相同，则 `<Copy>` 不会产生任何影响。	可选	字符串

指定副本的来源对象。

如果未指定 source，则默认为 message，根据政策执行所在的流程，该值会有所不同。如果政策在请求流中执行，则 message 变量会引用 request 对象。如果政策在响应流中执行，则 message 变量会引用 response 对象。
如果 source 特性中指定的变量无法解析或解析为非消息类型，则 <Copy> 无效。
确保您为 source 指定的值与目标消息不同，无论是默认目标消息还是使用 <AssignTo> 明确指定的目标。如果 source 与目标消息相同，则 <Copy> 不会产生任何影响。

可选

字符串

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

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

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

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

语法

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

示例 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="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>

示例 1

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

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

示例 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> 元素指定的请求消息中。

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

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> 元素指定的消息中。

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

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

示例 1

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

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

语法

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

示例 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、POST、PATCH、DELETE
消息类型：请求

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

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

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

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

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> 的一个常见用例是将代理响应状态代码设置为与从目标接收的值不同的值。

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

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

如果为 true，请将 <Copy> 元素的 source 属性中的动词复制到 <AssignTo> 元素中指定的请求中。

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

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> 元素指定的对象中。

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

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

语法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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` 属性的值
类型	字符串
父元素	<`PolicyElement`>
子元素	无

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

语法

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

示例

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

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

`<IgnoreUnresolvedVariables>`

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

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

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

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

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

语法

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

示例 1

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

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

由于 <IgnoreUnresolvedVariables> 设置为 true，如果未定义 possibly-defined-variable 变量，则此政策不会抛出故障。

`<Remove>`

移除消息的标头、查询参数、表单参数和/或消息载荷。如果 <Remove> 标记为空，则系统会从消息中移除所有内容。

受影响的消息可以是请求消息，也可以是响应消息。您可以使用 <AssignTo> 元素指定 <Remove> 作用于的消息。

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

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

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

语法

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

示例 1

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

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

示例 2

以下示例从 request 对象中移除所有表单参数和查询参数：

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 3

以下示例将移除消息对象中的所有内容：

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

通常，只有在您要使用 <Set> 元素或 <Copy> 元素在消息中设置一些替换值时，才会这样做。

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

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

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

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

语法

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

示例 1

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

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

示例 2

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

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 3

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

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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" >
  <!-- 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>

示例 1

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

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 2

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

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 3

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

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

以下示例从请求中移除 h1 和 h2，以及 h3 的第二个值。如果 h3 只有一个值，则不移除。

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

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

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

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

语法

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

示例 1

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

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

语法

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

示例 1

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

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 2

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

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 3

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

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

示例 4

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

HTTP 动词：GET、POST、PATCH、DELETE
消息类型：请求

`<Set>`

设置由 <AssignTo> 元素指定的请求或响应消息中的信息。<Set> 会覆盖原始消息中已存在的标头、查询或表单参数，如果不存在，则会添加新标头、查询或表单参数。

HTTP 消息中的标头、查询和表单参数可以包含多个值。如需为标头或参数添加其他值，请改用 <Add> 元素。

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

以下示例设置特定标头。将此政策附加在请求流中后，将允许上游系统接收原始入站请求中未包含的额外标头。

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 2

以下示例将覆盖响应的载荷以及 Content-Type 标头。

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</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="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>

仅在满足以下条件时才能使用 <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

以下示例将 x-ratelimit-remaining 标头设置为 ratelimit.Quota-1.available.count 变量的值：

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

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

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

注意：

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

有时，您可能需要将消息发送到在 API 代理的 TargetEndpoint 中定义的网址以外的网址。如果要重写目标网址，请使用 <AssignVariable> 元素替换 TargetEndpoint 中的 target.url 变量。（您不能替换 ProxyEndpoint 中的 target.url，因为 Apigee 在 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 中（例如，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 name="AM-set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

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

HTTP 动词：GET、POST、PATCH、DELETE
消息类型：请求

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

`<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="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

示例 2

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

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</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="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

示例 2

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

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

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</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="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

示例 2

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

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

消息类型：请求

创建自定义请求消息

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

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

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

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

默认情况下，Apigee 不会对自定义请求消息执行任何操作。创建之后，Apigee 将以原始请求继续执行流。如需使用自定义请求，请将 ServiceCallout 政策等政策添加到代理，并在该政策的配置中明确引用新创建的请求消息。这样，您就可以将自定义请求传递给外部服务端点。

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

示例 1

以下示例使用“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>

以下示例：

创建名为 MyCustomRequest 的新请求消息对象。
在 MyCustomRequest 中，此政策：
- 将传入请求的 user-agent HTTP 标头的值复制到新消息。由于 <Copy> 未指定 source 特性，因此 Apigee 将使用 request 消息作为来源。
- 将自定义消息的 address 查询参数设置为传入请求的 addy 查询参数的值。
- 将 HTTP 谓词设置为 GET。
将 <IgnoreUnresolvedVariables> 设置为 false。当 <IgnoreUnresolvedVariables> 为 false 时，如果政策配置中引用的其中一个变量不存在，则 Apigee 将在 API 流中输入故障状态。

示例 2

以下示例说明了如何使用“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>

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

您可以在流中后面部分出现的另一个 AssignMessage 政策中访问自定义消息的各种属性。以下示例从已命名的自定义响应中获取标头的值，并将其置于请求消息的新标头中：

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

错误代码

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

运行时错误

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

故障代码 HTTP 状态原因修复

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

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

steps.assignmessage.VariableOfNonMsgType

500

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

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

steps.assignmessage.UnresolvedVariable

500

如果 AssignMessage 政策中指定的变量为以下任一项，就会出现此错误：

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

部署错误

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

错误名称	原因	修复
`InvalidIndex`	如果 `AssignMessage` 政策的 `<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="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: 获取 ServiceCallout 响应标头

8：存储和移除表单参数、标头、查询参数

子元素参考

<Add>

语法

示例 1

示例 2

示例 3

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

语法

示例 1

示例 2

示例 3

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

语法

示例 1

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

语法

示例 1

<AssignTo>

语法

示例 1

示例 2

示例 3

<AssignVariable>

语法

示例 1

示例 2

示例 3

示例 4

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

语法

示例 1

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

语法

示例 1

示例 2

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

语法

示例 1

示例 2

示例 3

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

语法

示例 1

示例 2

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

语法

示例 1

示例 2

示例 3

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

语法

示例 1

示例 2

<Copy>

语法

示例 1

示例 2

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

语法

示例 1

示例 2

示例 3

示例 4

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

`<AssignMessage>` 元素

`<Add>`

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

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

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

`<AssignTo>`

`<AssignVariable>`

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

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

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

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

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

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

`<Copy>`

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

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

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

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

`<QueryParams>`（`<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>` 的子元素）