您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息
内容
在 API 代理流期间,AssignMessage 政策会更改或创建新的请求和响应消息。该政策可让您对这些消息执行以下操作:
您通常使用 AssignMessage 政策来添加、更改或移除请求或响应的属性。不过,您也可以使用“分配消息”政策来创建自定义请求或响应消息,并将其传递给替代目标,如创建自定义请求消息中所述。
使用场景
在很多情况下,您可能需要在 Apigee Edge 处理过程中修改请求或响应消息。例如:
- 定义查询字符串参数或其他类型输入的默认值。
- 先从请求消息中删除 HTTP 标头再将消息转发到后端服务。
- 先添加 HTTP 标头再将响应发送给消费者应用。
- 先插入 JSON 或 XML 消息内容再发送响应。
- 生成完整的请求或响应消息。例如,您可以使用 ServiceCallout 政策从 API 代理中调用远程 API。您可以使用 AssignMessage 政策创建自定义请求消息并将它分配给变量。然后,使用“服务调用”将该消息发送到远程 API。
- 将标头添加至请求和响应以便进行调试和问题排查。
AssignMessage 政策可以创建或更改消息或流变量。使用此政策可在通过代理将请求消息发送到上游系统之前修改这些消息,或者在将响应消息中继到 API 使用者应用之前修改这些消息。
<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 | 必需 |
政策的内部名称。 (可选)使用 |
continueOnError |
false | 可选 | 设置为“false” 可在政策失败时返回错误。这是大多数政策的预期行为。如果设置为“true”,则即使政策失败,仍可继续执行流。 |
enabled |
是 | 可选 | 设为“true”可强制执行政策。设为“false”可“关闭”政策。即使政策仍附加到某个流,也不会强制执行该政策。 |
async |
false | 已弃用 | 此属性已弃用。 |
下表提供了 <AssignMessage>
的子元素的简要说明:
子元素 | 是否必需? | 说明 |
---|---|---|
常见操作 | ||
<Add> |
可选 | 将信息添加到由 <AssignTo> 元素指定的消息对象。
|
<Copy> |
可选 | 将由 source 属性指定的消息中的信息复制到由 <AssignTo> 元素指定的消息对象。 |
<Remove> |
可选 | 从在 <AssignTo> 元素中指定的消息变量中删除指定的元素。 |
<Set> |
可选 | 替换由 <AssignTo> 元素指定的请求或响应中的现有属性的值。
|
其他子元素 | ||
<AssignTo> |
可选 | 指定 AssignMessage 政策要处理的消息。这可以是标准请求或响应,也可以是新的自定义消息。 |
<AssignVariable> |
可选 | 将值分配给流变量。如果该流变量不存在,则 <AssignVariable> 会创建它。 |
<IgnoreUnresolvedVariables> |
可选 | 确定在遇到无法解析的变量时处理是否停止。 |
后续各部分介绍了每个子元素。
示例
以下示例展示了使用 AssignMessage 政策的一些方法:
以下示例使用 <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>
以下示例使用 <Remove>
元素从响应中删除载荷:
<AssignMessage name="AM-remove-1"> <DisplayName>remove-1</DisplayName> <Remove> <Payload>true</Payload> </Remove> <AssignTo>response</AssignTo> </AssignMessage>
以下示例通过将标头添加到现有响应对象来修改该对象:
<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 标头,用于指示是否已从缓存中提取结果。在响应中设置标头可以方便进行调试和问题排查。
您可以使用“分配消息”将动态内容嵌入到响应和请求消息的载荷中。
如需在 XML 载荷中嵌入 Edge 流变量,请将指定的变量括在大括号中,如下所示:{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>
如需查看流变量的完整列表,请参阅流变量参考。
从 16.08.17 版本开始,您还可以使用大括号来插入变量。
以下示例从请求中移除 apikey
查询参数:
<AssignMessage name="AM-remove-query-param"> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <AssignTo>request</AssignTo> </AssignMessage>
使用 VerifyAPIKey 政策进行用户身份验证时,最佳做法是从请求消息中删除 apikey
查询参数。这样做可以防止将敏感密钥信息传递到后端目标。
以下示例使用了三个“分配消息”政策:
- 使用静态值在请求中创建三个流变量
- 动态获取请求流的第二个政策中的流变量
- 在响应的载荷中设置这些变量
<!-- 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>
在以下示例中,假设 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}
本参考中的每个子元素均有额外的示例。如需更多示例,请参阅 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>
以下示例使用 <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>
以下示例使用 <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>
以下示例使用 <QueryParams>
元素将带有静态值的单个查询参数添加到请求:
<AssignMessage name="AM-add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
此示例在请求 PreFlow 中使用 <Add>
。如果您在 Trace 工具等工具中查看结果,则对 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>
以下示例将一个表单参数 ("answer") 和一个静态值 ("42") 添加到请求:
<AssignMessage name="AM-add-formparams-1"> <Add> <FormParams> <FormParam name="answer">42</FormParam> </FormParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
以下示例获取 name
查询参数的值,并将其作为表单参数添加到请求中,然后移除该查询参数:
<AssignMessage name="AM-Swap-QueryParam-to-FormParams"> <Add> <FormParam name="name">{request.queryparam.name}</FormParam> </Add> <Remove> <QueryParam name="name"/> </Remove> </AssignMessage>
请注意,此示例没有使用 <AssignTo>
指定目标。此政策仅将参数添加到请求。
以下示例将多个表单参数添加到请求:
<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 会将修改后的请求发送到目标端点。
您可以使用 Trace 工具来查看流。您将看到请求的正文包含网址编码的表单数据,这些数据最初是作为查询字符串参数传递的:
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>
时,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>
以下示例将 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>
以下示例将查询参数 "myParam" 添加到请求并为其分配值 “42”:
<AssignMessage name="AM-add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo>request</AssignTo> </AssignMessage>
仅在满足以下条件时才能使用 <QueryParams>
:
- HTTP 谓词:GET
- 消息类型:请求
此外,仅当 <AssignTo>
元素的 type
属性是请求消息时,才能设置查询参数。在响应中设置它们没有任何影响。
如果您在政策 (<Add><QueryParams/></Add>
) 中定义空的查询参数数组,则该政策不会添加任何查询参数。这与省略 <QueryParams>
相同。
<AssignTo>
确定 AssignMessage 政策的作用对象。选项包括:
请注意,在某些情况下,无法更改 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>
以下示例指定目标是将发送到目标端点的原始请求:
<AssignMessage name="assignto-1"> <!-- DO NOT do this --> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
以下示例会创建一个新的请求对象:
<AssignMessage name="AM-assignto-2"> <AssignTo createNew="true" transport="http" type="request">NameOfNewMessage</AssignTo> </AssignMessage>
创建新的请求或响应对象时,AssignMessage 政策的其他元素(例如 <Add>
、<Set>
和 <Copy>
)会作用于这个新的请求对象。
您可以稍后访问流中其他政策中的新请求对象,也可以使用 ServiceCallout 政策将新请求对象发送到外部服务。
以下示例会创建一个名为 “MyRequestObject” 的新请求对象:
<AssignMessage name="assign>to-<2" AssignTo createNew="true" transport=&"http" ty&pe="req>u<est"gt;My>RequestObjectlt;/AssignTo /AssignMessage
创建新的请求或响应对象时,AssignMessage 政策的其他元素(例如 <Add>
、<Set>
和 <Copy>
)会作用于这个新的请求对象。
您可以稍后访问流中其他政策中的新请求对象,也可以使用 ServiceCallout 政策将新请求对象发送到外部服务。
下表介绍 <AssignTo>
的属性:
属性 | 说明 | 是否必需? | 类型 |
---|---|---|---|
createNew |
确定在分配值时,该政策是否创建新的消息。 如果设置为 “true”,该政策将创建一个由 如果设置为 “false”,则该政策会通过以下两种方式之一做出响应:
如果未指定
|
可选 | 布尔值 |
transport |
指定请求或响应消息类型的传输类型。 默认值为 “http”(唯一支持的值)。 |
可选 | 字符串 |
type |
当 createNew 为 “true” 时,指定新消息的类型。有效值为 “request” 或 “response”。如果省略此属性,则 Edge 会创建一个请求或响应,具体取决于此政策执行所在的流。 |
可选 | 字符串 |
<AssignVariable>
将值分配给流变量。如果该流变量不存在,则 <AssignVariable>
会创建它。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 复杂类型 |
父元素 |
<AssignMessage>
|
子元素 |
<Name> (必需)<Ref> <Template> <Value> |
您分配给流变量的值可以是以下值之一:
- 字面量字符串:使用
<Value>
子元素指定流变量的字面量字符串值。 - 流变量:使用
<Ref>
子元素指定目标流变量的现有流变量的值。如需可用作来源的流变量的完整列表,请参阅流变量参考。 - 消息模板:使用
<Template>
子元素指定要插值的消息模板,以获取要放入目标流变量中的值。
<AssignVariable>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="polic>y_nam<e&qu>ot; Assign<Varia>ble < >Namevariable_na <me/N>ame < Refso>urce_variable /Re<f Tem>platemessage<_template/Template or Te><mplate re>f=<9;tem>plate_variable <'/>Tem<plate Value>v<ariable_value/>Value /AssignVariable /AssignMessage
使用 <Ref>
元素指定来源变量。如果 <Ref>
引用的变量不可访问,则 Edge 会使用由 <Value>
元素指定的值。如果您定义了 <Template>
,则它的优先级将高于其他子元素。
以下示例将新变量 myvar
的值设为字面量值 “42”:
<AssignMessage name="assignvariab>le-<1" Assi>gnVar<iabl>e < Name>myvar</Name> < Val>ue4<2/Value /Assi>g<nVariable /Ass>ignMessage
以下示例将流变量 request.header.user-agent
的值分配给目标流变量 myvar
,并将查询参数 country
的值分配给目标流变量 Country
:
<AssignMessage name="assignvariab>le-<2" Assi>gnVar<iabl>e < Name>myvar</Na>me Refrequest.header.<user>-agen<t/Ref> ValueE<rrorOn>Cop<y/Value /Assi>gnV<ariable Assi>gnVar<iabl>e N<ameCo>untry</Na>me Refrequest.querypar<am.c>ountr<y/Ref> ValueE<rrorOn>Cop<y/Value /Assi>g<nVariable /Ass>ignMessage
如果任一分配失败,Edge 都会将值“ErrorOnCopy”分配给目标流变量。
如果 myvar
或 Country
流变量不存在,则 <AssignVariable>
会创建它们。
以下示例使用 <Template>
子元素使用一个字面量字符串(连字符)将两个上下文变量串联在一起:
<AssignMessage name='AV-via-templat>e-1<' IgnoreUnresolvedV>ariab<lesfalse/IgnoreUnresolvedV>ari<ables Assign>Varia<ble<>/span> Namemy_destination_<varia>ble/N<ame > Value<BADDBE>EF/Va<lue >Template{system.uuid}-{me<ssageid}/>Tem<plate /Assign>V<ariable /Assig>nMessage
<AssignVariable>
的一个常见用例是设置查询参数、标头或可随请求一起传递的其他值的默认值。您可以通过结合使用 <Ref>
和 <Value>
子元素来实现此目的。如需了解详情,请参阅 <Ref>
的示例。
<Name>
(<AssignVariable>
的子元素)
指定目标流变量(例如,由“分配消息”政策设置其值的变量)的名称。如果在 <AssignVariable>
中指定的变量不存在,则该政策将使用该名称创建一个变量。
默认值 | 不适用 |
是否必需? | 必需 |
类型 | 字符串 |
父元素 |
<AssignVariable>
|
子元素 | 无 |
<Name>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="polic>y_nam<e&qu>ot; Assign<Varia>ble< Namevariab>l<e_name/Name >/AssignVariable /AssignMessage
以下示例将目标变量指定为 myvar
,并将其设置为字面量值 “42”:
<AssignMessage name="assignvariab>le-<1" Assi>gnVar<iabl>e < Name>myvar</Name> < Val>ue4<2/Value /Assi>g<nVariable /Ass>ignMessage
如果 myvar
不存在,则 <AssignVariable>
会创建它。
<Ref>
(<AssignVariable>
的子元素)
将流的来源指定为流变量。流变量可以是预定义的流变量(如流变量参考中列出的流变量)之一,也可以是您创建的自定义流变量。
<Ref>
的值始终解释为流变量;无法指定字面量字符串作为值。如需分配字面量字符串值,请改用 <Value>
元素。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<AssignVariable>
|
子元素 | 无 |
使用 <Ref>
指定流变量时,请忽略您通常用来引用流变量的括号 “{}”。例如,如需将新变量的值设置为 client.host
流变量的值:
Do this (no brackets): <Ref>client.host</Ref> DoNOT do this (brackets): <Ref>{client.host}</Ref>
如需定义目标流变量的默认值,请结合使用 <Value>
和 <Ref>
。如果 <Ref>
指定的流变量不存在、无法读取或为 null,则 Edge 会改为将 <Value>
的值分配给目标流变量。
<Ref>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="polic>y_nam<e&qu>ot; Assign<Varia>ble < >Namevariable_na <me/N>ame< Refsource_>v<ariable/Ref >/AssignVariable /AssignMessage
以下示例将流变量 request.header.user-agent
的值分配给目标流变量 myvar
,并将查询参数 country
的值分配给 Country
变量:
<AssignMessage name="assignvariab>le-<4" Assi>gnVar<iabl>e < Name>myvar</Na>me Refrequest.header.<user>-ag<ent/Ref /Assi>gnV<ariable Assi>gnVar<iabl>e N<ameCo>untry</Na>me Refrequest.querypar<am.c>oun<try/Ref /Assi>g<nVariable /Ass>ignMessage
在此示例中,Edge 没有为任一分配指定默认值(或后备值)。
以下示例将流变量 request.header.user-agent
的值分配给目标流变量 myvar
,并将查询参数 country
的值分配给 Country
变量:
<AssignMessage name="assignvariab>le-<2" Assi>gnVar<iabl>e < Name>myvar</Na>me Refrequest.header.<user>-agen<t/Ref> ValueE<rrorOn>Cop<y/Value /Assi>gnV<ariable Assi>gnVar<iabl>e N<ameCo>untry</Na>me Refrequest.querypar<am.c>ountr<y/Ref> ValueE<rrorOn>Cop<y/Value /Assi>g<nVariable /Ass>ignMessage
在此示例中,如果 request.header.user-agent
流变量或 Country
查询参数的值为 null、无法读取或格式不正确,则 Edge 会将值 “ErrorOnCopy” 分配给新变量。
<AssignVariable>
的常见用例是设置查询参数、标头或可随请求一起传递的其他值设置默认值。例如,您将创建一个天气 API 代理,在其中,请求会使用名为 “w” 的单个查询参数。此参数包含您想要查看其天气的城市的 ID。请求网址采用以下形式:
http://myCO.com/v1/weather/forecastrss?w=city_ID
如需定义“w”的默认值,请创建如下所示的 AssignMessage 政策:
<AssignMessage continueOnError="false" enabled="true" nam>e=&<quot;assignvariable-3" AssignTo createNew="fals>e&q<uot; transport="http>" <type="request"/ > I<gnoreUnresolve>dVari<able>strue /IgnoreUnres<olved>Varia<ble>s AssignVariable < N>amere<quest>.querypa<ram.w/>Nam<e Refreques>t<.queryparam.w/>Ref Value12797282/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>
元素可以使用应用自定义属性中的消息模板,该模板可作为安全政策中的流变量使用。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<AssignVariable>
|
子元素 | 无 |
<Template>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="polic>y_nam<e" >AssignVariabl <e Tem>platemessage<_template/Template or Te><mplate re>f=&<#39;template_va>r<iable'/Tem>plate /AssignVariable /AssignMessage
以下示例使用消息模板语法使用一个字面量字符串(连字符)将两个上下文变量串联在一起:
<AssignMessage name='AV-via-templat>e-1<' IgnoreUnresolvedV>ariab<lesfalse/IgnoreUnresolvedV>ari<ables Assign>Varia<ble<>/span> Namemy_destination_<varia>ble/N<ame > Value<BADDBE>EF/Va<lue >Template{system.uuid}-{me<ssageid}/>Tem<plate /Assign>V<ariable /Assig>nMessage
以下示例指定了一个流变量,其值是预定义的消息模板。如果要在运行时注入预定义的模板而无需修改该政策,请使用此选项:
<AssignMessage name='AV-via-template-indirec>tly&#<39; IgnoreUnresolvedV>ariab<lesfalse/IgnoreUnresolvedV>ari<ables Assign>Varia<ble<>/span> Namemy_destination_<varia>ble/N<ame > Value<BADDBE>EF/Va<lue Template ref='my_templat>e_v<ariable'/ > </AssignVariabl>e /AssignMessage
以下示例指定了一个流变量和一个文本值。在这种情况下,如果引用的变量非 null,则该值将用作模板。如果引用的值为 null,则将文本值(在本例中为 {system.uuid}-{messageid}
)用作模板。此格式可用于提供“替换”值,在某些情况下,您可能希望使用动态设置的值替换默认模板(文本部分)。例如,条件语句可能会从键值对映射中获取值,并将引用的变量设置为该值:
<AssignMessage name='AV-template-with-fallb>ack<' IgnoreUnresolvedV>ariab<lesfalse/IgnoreUnresolvedV>ari<ables Assign>Varia<ble<>/span> Namemy_destination_<varia>ble/N<ame > Value<BADDBE>EF/Va<lue Template ref='>my_variable'{system.u<uid}-{mes>sag<eid}/Template > </AssignVariabl>e /AssignMessage
<Value>
(<AssignVariable>
的子元素)
使用 <AssignVariable>
定义目标流变量集的值。该值始终解释为字面量字符串;无法指定字面量字符串作为值,即使您将值用括号 (“{}”) 括起来也不例外。如需使用流程变量,请改用 <Ref>
。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<AssignVariable>
|
子元素 | 无 |
与 <Ref>
元素结合使用时,<Value>
用作默认值(或后备值)。如果 <Ref>
未指定、无法解析或为 null,则使用 <Value>
的值。
<Value>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="polic>y_nam<e&qu>ot; Assign<Varia>ble < Na>mevariable_nam <e/Name> < Valuevariable>_<value/Value >/AssignVariable /AssignMessage
以下示例将目标流变量的值 myvar
设置为字面量值 “42”:
<AssignMessage name="assignvariab>le-<1" Assi>gnVar<iabl>e < Name>myvar</Name> < Val>ue4<2/Value /Assi>g<nVariable /Ass>ignMessage
以下示例将流变量 request.header.user-agent
的值分配给流变量 myvar
,并将查询参数 country
的值分配给 Country
变量:
<AssignMessage name="assignvariab>le-<2" Assi>gnVar<iabl>e < Name>myvar</Na>me Refrequest.header.<user>-agen<t/Ref> ValueE<rrorOn>Cop<y/Value /Assi>gnV<ariable Assi>gnVar<iabl>e N<ameCo>untry</Na>me Refrequest.querypar<am.c>ountr<y/Ref> ValueE<rrorOn>Cop<y/Value /Assi>g<nVariable /Ass>ignMessage
如果任一分配失败,<AssignVariable>
都会将值 “ErrorOnCopy” 分配给目标流变量。
<Copy>
将由 source
属性指定的消息中的值复制到由 <AssignTo>
元素指定的消息。如果您没有使用 <AssignTo>
指定目标,则此政策会将值复制到请求或响应,具体取决于此政策执行所在的流。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Path> <Payload> <QueryParams> <ReasonPhrase> <StatusCode> <Verb> <Version> |
如果您在 <Copy>
元素下未指定子元素,则将复制指定源消息的所有部分。
<Copy>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > name<="policy_name" Co>py so<urce="[request|response]&qu<ot; !--> Can also <be an empt>y array< (FormParams/) --> FormP>arams For<mParam nam>e="formpar<am_name&quo>t;for<mparam_value/FormParam ...< /Fo>rmParams < !-- >Can als<o be an emptyarray (Hea d>ers/) --> < He>aders Hea<der name>=&quo<t;he>ader_name&qu<ot;he>ader_<value/H>eader <... >/Head<ers Path[false|true]/Path < Payload[fa>lse|true]/<Payload > !-- Ca<n also be an empty array (QueryPa>rams /) --> < QueryPara>ms QueryP<aram name=&q>uot;q<ueryparam_na>me"quer<yparam_value/>Query<Param > ... /Q<ueryParams<>/span> R<easo>nPhrase[fals<e|tru>e]/Re<asonPhr>ase Stat<usCode[f>als<e|tru>e]/<StatusCode Verb[false|true]/Verb< >
Version[f>als<e|true]/Version /Copy !-- Used as the destination for the Copy values -- A>ssignTo createNew="[<true|fals>e<]" transp>ort="http" type="[request|response]"destination_variable_name/AssignTo /AssignMessage
以下示例将 request
消息中的标头、三个表单参数、路径以及所有查询参数复制到新的自定义请求 newRequest
:
<AssignMessage name="AM-co>py-<1" AssignTo createNew="true" transport=&>quot;http&<quot; typ>e=&<quot;request"new>Reque<st/Assi>gnTo <Copy source="request&qu>ot; < Heade>rs < Header> name=&<quot;Header_Name_1"/ /Head>ers < FormParams FormParam name=&q>uot;For<m_Param_Name_1"/ FormPar>am na<me="Fo>rm_Pa<ram_>Name<_2&qu>ot;/ < FormPa>ram< name>=<"Form_Par>am_Name_3"/ /FormParams Pathtrue/Path QueryParams/ /Copy /AssignMessage
以下示例首先移除现有 response
消息中的所有内容,然后将名为 secondResponse
的其他消息中的所有值复制到 response
消息中:
<AssignMessage name='AM-Copy-Respo>nse<' AssignTo createNew="false" transport=&quo>t;http&q<uot; type>=&q<uot;response"response/AssignTo !>-- <first r>emo<ve any existing values -- Remove/ !-- then copy eve>ryt<hing from the designated mess>a<ge -- Copy s>ource="secondResponse"/ /AssignMessage
<Copy>
元素具有单一特性:
属性 | 说明 | 是否必需? | 类型 |
---|---|---|---|
来源 |
指定副本的来源对象。
|
可选 | 字符串 |
<FormParams>
(<Copy>
的子元素)
将由 <Copy>
元素的 source
属性指定的请求中的表单参数复制到由 <AssignTo>
元素指定的请求。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <FormParam> 元素的数组或空数组 |
父元素 |
<Copy>
|
子元素 |
<FormParam> |
<FormParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce="[request|response]&qu<ot; !--> Can also <be an empt>y array< (FormParams/) --> FormP>arams For<mParam nam>e="formpar<am_name&quo>t;f<ormpa>r<am_value/FormP>aram ... /FormParams /Copy /AssignMessage
以下示例将请求中的单个表单参数复制到自定义请求 “MyCustomRequest”:
<AssignMessage name="copy-formpara>ms-<1" Copy source>=&quo<t;request&>quot; < FormParams FormPa>ram name="par<amName&quo>t;For<m param val>ue <1/For>mPa<ram /FormParams /Copy AssignTo createNew="tr>ue" transp<ort=">;<http" typ>e="request"MyCustomRequest/AssignTo /AssignMessage
以下示例将所有表单参数复制到自定义请求 “MyCustomRequest”:
<AssignMessage name="copy-formpara>ms-<2" Copy source>=&quo<t;request&q>uot<; > Fo<rmParams/ /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"MyCustomRequest/AssignTo /AssignMessage
以下示例将三个表单参数复制到自定义请求 “MyCustomRequest”:
<AssignMessage name="copy-formpara>ms-<3" Copy source>=&quo<t;request&>quot; < FormParams FormPara>m name=<"paramName1"/ > FormP<aram name="paramName2&q>uot;/< Form>Par<am na>me=<"paramName3"/ /FormParams /Copy AssignT>o createNew=&qu<ot;true&q>u<ot; transport=>"http" type="request"MyCustomRequest/AssignTo /AssignMessage
如果有多个具有相同名称的表单参数,请使用以下语法:
<AssignMessage name="copy-formpara>ms-<4" Copy source>=&quo<t;request&>quot; < FormParams >FormPar<am name="f1&quo>t;/ < FormParam name=&quo>t;f2&<quot;/ > F<ormPa>ram< name="f3.2"/ /FormParams /Copy AssignT>o createNew=&qu<ot;true&q>u<ot; 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]" > na<me="policy_name" Co>py so<urce="[request|response]&qu<ot; >!-- Can al<so be a>n empty< array (Headers /) --> >Headers < H>eader name=&quo<t;header>_na<me&qu>o<t;header_value>/Header ... /Headers /Copy /AssignMessage
以下示例将请求中的 user-agent
标头复制到新的自定义请求对象:
<AssignMessage name="copy-heade>rs-<1" Copy source>=&quo<t;reque>st"<; Headers Heade>r nam<e=">use<r-age>nt&<quot;/ /Headers /Copy AssignTo createNew="tr>ue" transp<ort=">;<http" typ>e="request"MyCustomRequest/AssignTo /AssignMessage
如需复制所有标头,请使用空的 <Headers>
元素,如以下示例所示:
<AssignMessage name="copy-heade>rs-<2" Copy source>=&quo<t;reques>t&q<uot;<>/span> < Headers/ /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"MyCustomRequest/AssignTo /AssignMessage
如果多个标头同名,请使用以下语法:
<AssignMessage name="copy-heade>rs-<3" Copy source>=&quo<t;reque>st"<; Headers > Head<er name="h1&>quot;/ < Header name=&>quot;<h2">/ < >Hea<der name="h3.2"/ /Headers /Copy AssignT>o createNew=&qu<ot;true&q>u<ot; 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]" > na<me="policy_name" Co>py so<urce>="[requ<est|r>esp<onse]>&<quot; Path>[false|true]/Path /Copy /AssignMessage
以下示例表明 AssignMessage 政策应将来源请求中的路径复制到新的自定义请求对象:
<AssignMessage name="copy-pa>th-<1" Copy source>=&quo<t;re>ques<t&quo>t; < P>ath<true/Path /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"MyCustomRequest/AssignTo /AssignMessage
仅在满足以下条件时才能使用 <Path>
:
- 消息类型:请求
<Payload>
(<Copy>
的子元素)
确定是否应将载荷从来源复制到目标。来源和目标可以是请求或响应。
如果设置为 “true”,则此政策将由 <Copy>
元素的 source
属性指定的消息中的载荷复制到由 <AssignTo>
元素指定的消息。
默认值 | False |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Copy>
|
子元素 | 无 |
<Payload>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce=&q>uot;[request<|respons>e]&<quot;> < Payload[fa>lse|true]/Payload /Copy /AssignMessage
以下示例将 <Payload>
设置为 “true”,以便将请求载荷从请求复制到响应:
<AssignMessage name="AM-copy-paylo>ad-<1" Copy source>=&quo<t;reque>st&q<uot; > Pa<yload>tru<e/Payloa>d /Cop<y Assig>n<Toresponse/Ass>ignTo /AssignMessage
<QueryParams>
(<Copy>
的子元素)
将由 <Copy>
元素的 source
属性指定的请求中的查询字符串参数复制到由 <AssignTo>
元素指定的请求。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <QueryParam> 元素的数组或空数组 |
父元素 |
<QueryParam>
|
子元素 | 无 |
<QueryParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce="[request|response]&qu<ot; !-- >Can also b<e an empty >array (<QueryParams/) --> QueryPar>ams QueryP<aram name=&>quot;queryparam<_name"q>uer<ypara>m<_value/QueryPa>ram ... /QueryParams /Copy /AssignMessage
以下示例将请求中的 "my_param" 查询参数复制到新的自定义请求对象:
<AssignMessage name="copy-querypara>ms-<1" Copy source>=&quo<t;request&q>uot; < QueryParams QueryPa>ram n<ame="my>_pa<ram&q>uot<;/ /QueryParams /Copy AssignTo createNew="tr>ue" transp<ort=">;<http" typ>e="request"MyCustomRequest/AssignTo /AssignMessage
以下示例将所有查询参数从请求复制到新的自定义请求对象:
<AssignMessage name="copy-querypara>ms-<2" Copy source>=&quo<t;request&qu>ot;< >Que<ryParams/ /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"MyCustomRequest/AssignTo /AssignMessage
如果有多个具有相同名称的查询参数,请使用以下语法:
<AssignMessage name="copy-querypara>ms-<3" Copy source>=&quo<t;request&q>uot; < QueryParams Qu>eryPara<m name="qp1">/ < QueryParam name="q>p2&qu<ot;/ Q>uer<yPara>m n<ame="qp3.2"/ /QueryParams /Copy AssignT>o createNew=&qu<ot;true&q>u<ot; 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]" > na<me="policy_name" Co>py so<urce="[>request|resp<onse]" > <Reaso>n<Phrase[false|t>rue]/ReasonPhrase /Copy /AssignMessage
以下示例将 <ReasonPhrase>
设置为 true
。使用指定的源和 <AssignTo>
元素时,这会使 <Copy>
将指定响应消息中的原因短语复制到 response
对象:
<AssignMessage name="AM-copy-reasonphra>se-<1" Copy source="serviceC>allou<tResponse&qu>ot; < ReasonPhr>ase<true/>Rea<sonPhras>e /Cop<y Assig>n<Toresponse/Ass>ignTo /AssignMessage
仅当来源和目标消息的类型为“响应”时,才能使用 <ReasonPhrase>
。
<StatusCode>
(<Copy>
的子元素)
确定是否将状态代码从来源响应复制到目标响应。此元素对请求没有任何影响。
如果设置为 “true”,则此政策会将由 <Copy>
元素的 source
属性指定的响应消息中的状态代码复制到由 <AssignTo>
元素指定的响应消息。
默认值 | False |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Copy>
|
子元素 | 无 |
<StatusCode>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce=">;[request|re<sponse]&quo>t; < S>t<atusCode[false>|true]/StatusCode /Copy /AssignMessage
以下示例将 <StatusCode>
设置为 “true”,这会将默认响应对象中的状态代码复制到新的自定义响应对象:
<AssignMessage name="copy-statusco>de-<1" Copy source=>"<;response&>quot<; Statu>sCo<detru>e/S<tatusCode /Copy AssignTo createNew="true" tr>ansport="ht<tp" >t<ype="resp>onse"MyCustomResponse/AssignTo /AssignMessage
仅当来源和目标消息的类型为“响应”时,才能使用 <StatusCode>
。
<StatusCode>
的一个常见用例是将代理响应状态代码设置为与从目标接收的值不同的值。
<Verb>
(<Copy>
的子元素)
确定是否将来源请求中的 HTTP 谓词复制到目标请求。此元素对响应没有任何影响。
如果设置为 “true”,则将在 <Copy>
元素的 source
属性中找到的谓词复制到在 <AssignTo>
元素中指定的请求。
默认值 | False |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Copy>
|
子元素 | 无 |
<Verb>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce>="[requ<est|r>esp<onse]>&<quot; Verb>[false|true]/Verb /Copy /AssignMessage
以下示例将 <Verb>
设置为 “true”,这会将默认请求中的谓词复制到新的自定义请求:
<AssignMessage name="copy-ve>rb-<1" Copy source>=&quo<t;re>ques<t&quo>t; < V>erb<true/Verb /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"MyCustomRequest/AssignTo /AssignMessage
仅在满足以下条件时才能使用 <Verb>
:
- 消息类型:请求
<Version>
(<Copy>
的子元素)
确定是否将 HTTP 版本从来源请求复制到目标请求。此元素对响应没有任何影响。
如果设置为 “true”,则将在 <Copy>
元素的 source
属性中找到的 HTTP 版本复制到在 <AssignTo>
元素指定的对象。
默认值 | False |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Copy>
|
子元素 | 无 |
<Version>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me="policy_name" Co>py so<urce=&q>uot;[request<|respons>e]&<quot;> < Version[fa>lse|true]/Version /Copy /AssignMessage
以下示例会在请求中将 <Version>
设置为 “true”,这会将默认请求对象中的版本复制到新的自定义请求对象:
<AssignMessage name="copy-versi>on-<1" Copy source>=&quo<t;reque>st&q<uot; > Ve<rsion>tru<e/Version /Copy AssignTo createNew="true" t>ransport="<http">;< type="re>quest"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]" > na<me="policy_name">; IgnoreUnre<solvedVariables[true|false>]< /IgnoreUnre>solvedVariables /AssignMessage
以下示例将 <IgnoreUnresolvedVariables>
设置为 “true”:
<AssignMessage name="AM-Set-Hea>der<s&q>uot; < Set > Head<ers Header name=&#>39;new-header'{possibly<-defin>ed-va<riable}H>ead<er > </Headers /Set IgnoreU>nresolv<edVariablestrue /IgnoreU>n<resolvedVariab>les /AssignMessage
由于 <IgnoreUnresolvedVariables>
设置为 true
,如果未定义 possibly-defined-variable
变量,则此政策不会抛出故障。
<Remove>
移除消息的标头、查询参数、表单参数和/或消息载荷。消息可以是请求消息,也可以是响应消息。您可以使用 <AssignTo>
元素指定 <Remove>
作用于的消息。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 复杂类型 |
父元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Payload> <QueryParams> |
<Remove>
的一个常见用例是从传入请求对象中删除包含敏感信息的查询参数或标头,以避免将其传递给后端服务器。
<Remove>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=&qu>ot;po<licy_name" Remove !-<- Can also >be an empt<y array (F>ormPara<ms/) -->FormParams >FormParam nam <e="fo>rmparam_name&qu<ot;formpara>m_val<ue/FormParam ... /Form<Params > !-- Can< also b>e an em<pty array (Headers /) --&g>t; Heade<rs > Header name=&<quot;hea>der_n<ame&quo>t;header_val<ue/Heade>r < ... /Headers Payload[<false|true]/>Payload < !-- Can a>lso be <an empty array (QueryParams /) --&>gt; QueryPar<ams Q>ueryParam name=<"queryp>ara<m_name&>q<uot;queryparam>_value/QueryParam ... /QueryParams /Remove /AssignMessage
以下示例从响应中移除消息正文:
<AssignMessage name="AM-remo>ve-<1" D>isplayNa<meremove-1/D>isp<layNam>e R<emove > P<ayloadtr>ue/<Payload> </Remove > Assign<Torespons>e</AssignTo /Ass>ignMessage
在响应流中,此政策会移除响应的正文,仅将 HTTP 标头返回给客户端。
以下示例从 request
对象中移除所有表单参数和查询参数:
<AssignMessage name="AM-remo>ve-<2">; R<emove !<-- Empty (F>ormParams/) removes all form par>amete<rs -- F>ormPa<rams/ Q>ueryPar<ams QueryParam n>ame=&<quot;qp1&quo>t;/< /Q>uer<yParams > /Remo<ve Assi>g<nTorequest/Ass>ignTo /AssignMessage
以下示例将移除消息对象中的所有内容:
<AssignMessage name="AM-remo>ve-<3"> <Remove/ > Assig<nToreques>t</AssignTo /Ass>ignMessage
<FormParams>
(<Remove>
的子元素)
从请求中删除指定的表单参数。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <FormParam> 元素的数组或空数组 |
父元素 |
<Remove>
|
子元素 |
<FormParam> |
<FormParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=&qu>ot;po<licy_name" Remove !-<- Can also >be an empt<y array (F>ormPara<ms/) -->FormParams >FormParam nam <e="fo>rmparam_name&qu<ot;formpara>m_v<alue/Fo>r<mParam .>.. /FormParams /Remove /AssignMessage
以下示例从请求中移除三个表单参数:
<AssignMessage name="AM-remove-formpara>ms-<1">; R<emove >FormPar<ams FormParam name=">;form_p<aram_1"/ FormParam >name=&q<uot;form_param_2"/ >FormP<aram name=&>quo<t;form_>par<am_3&quo>t;/ < /FormPar>a<ms /Remove > AssignTorequest/AssignTo /AssignMessage
以下示例从请求中移除所有表单参数:
<AssignMessage name="AM-remove-formpara>ms-<2">; R<emove F>orm<Params/> </Remove > Assig<nToreques>t</AssignTo /Ass>ignMessage
如果有多个具有相同名称的表单参数,请使用以下语法:
<AssignMessage name="AM-remove-formpara>ms-<3">; R<emove >FormPar<ams FormParam >name=&q<uot;f1"/ >FormPar<am name="f2">/ < FormPara>m n<ame=&qu>ot;<f3.2&quo>t;/ < /FormPar>a<ms /Remove > AssignTorequest/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]" > na<me=&qu>ot;po<licy_name" Remove !-<- Can al>so be an e<mpty ar>ray (He<aders/) -->; Header>s Head<er name>="header_n<ame">;he<ader_va>l<ue/Header > ... /Headers /Remove /AssignMessage
以下示例从请求中移除 user-agent
标头:
<AssignMessage name="AM-remove-one-he>ade<r">; R<emove > Head<ers Header name=&qu>ot;us<er-agent>&qu<ot;/ > /<Headers > /Remo<ve Assi>g<nTorequest/Ass>ignTo /AssignMessage
以下示例从请求中移除所有标头:
<AssignMessage name="AM-remove-all-hea>der<s">; R<emove > H<eaders/> </Remove > Assig<nToreques>t</AssignTo /Ass>ignMessage
如果多个标头同名,请使用以下语法:
<AssignMessage name="AM-remove-heade>rs-<3">; R<emove > Head<ers Header >name=&q<uot;h1"/ > Head<er name="h2&qu>ot;/ < He>ade<r name=>&qu<ot;h3.2&>quot;/ < /Head>e<rs /Remove > AssignTorequest/AssignTo /AssignMessage
此示例从请求中移除 “h1”、“h2” 和 “h3” 的第二个值。如果 “h3” 只有一个值,则不移除。
<Payload>
(<Remove>
的子元素)
确定 <Remove>
是否会删除由 <AssignTo>
元素指定的请求或响应中的载荷。设置为 “true” 以清除载荷;否则请设置为 “false”。默认值为 “False”。
默认值 | False |
是否必需? | 可选 |
类型 | 布尔值 |
父元素 |
<Remove>
|
子元素 | 无 |
<Payload>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=&qu>ot;po<licy_na>me" <Remove > <Payload>[<false|true]/Pa>yload /Remove /AssignMessage
以下示例将 <Payload>
设置为 “true”,以便清除请求载荷:
<AssignMessage name="AM-remove-paylo>ad-<1">; R<emove > P<ayloadtr>ue/<Payload> </Remove > Assig<nToreques>t</AssignTo /Ass>ignMessage
<QueryParams>
(<Remove>
的子元素)
从请求中删除指定的查询参数。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <QueryParam> 元素的数组或空数组 |
父元素 |
<Remove>
|
子元素 |
<QueryParam> |
<QueryParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=&qu>ot;po<licy_name" Remove !-<- Can also b>e an empty< array (Que>ryParam<s/) --> QueryParams >QueryParam name= <"query>param_name"<;queryparam_>val<ue/Quer>y<Param ..>. /QueryParams /Remove /AssignMessage
以下示例从请求中移除单个查询参数:
<AssignMessage name="AM-remove-querypara>ms-<1">; Rem<ove Q>ueryParam<s QueryParam n>ame=&qu<ot;qp1">/ < /Q>uer<yParams > /Remo<ve Assi>g<nTorequest/Ass>ignTo /AssignMessage
以下示例从请求中移除所有查询参数:
<AssignMessage name="AM-remove-querypara>ms-<2">; Rem<ove Qu>ery<Params/> </Remove > Assig<nToreques>t</AssignTo /Ass>ignMessage
如果有多个具有相同名称的查询参数,请使用以下语法:
<AssignMessage name="AM-remove-querypara>ms-<3">; Rem<ove Q>ueryParam<s QueryParam n>ame="<;qp1"/ Qu>eryParam <name="qp2"/ > Q<ueryParam na>me=<"q>p3.<2"/> </QueryPar>a<ms /Remove > AssignTorequest/AssignTo /AssignMessage
以下示例从请求中移除 “qp1”、“qp2” 和 “qp3” 的第二个值。如果 “qp3” 只有一个值,则不移除。
以下示例从请求中移除 apikey
查询参数:
<AssignMessage name="AM-remove-query-p>ara<m">; R<emove Q>ueryPar<ams QueryParam name>=&quo<t;apikey&quo>t;/< /Q>uer<yParams > /Remo<ve Assi>g<nTorequest/Ass>ignTo /AssignMessage
仅在满足以下条件时才能使用 <QueryParams>
:
- HTTP 谓词:GET
- 消息类型:请求
<Set>
设置由 <AssignTo>
元素指定的请求或响应消息中的信息。<Set>
会覆盖原始消息中已存在的标头、查询或表单参数。HTTP 消息中的标头、查询和表单参数可以包含多个值。如需为标头或参数添加其他值,请改用 <Add>
元素。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 复杂类型 |
父元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Payload> <Path> <QueryParams> <ReasonPhrase> <StatusCode> <Verb> <Version> |
<Set>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_na>me"<; Set FormParams F>ormParam name=&<quot;formp>aram_name"<formparam_v>alue/<FormPar>am < ... /FormParams >Headers < Head>er name="h<eader_na>me&qu<ot;h> eade <r_val>ue/He<ader ... /Headers Pathpath/Path Payload contentType="content_type& q>uot; variab<lePrefix>=&quo<t;prefix&qu>ot; < variableSuffix ="suffix&>quot; new_payload</Payload > QueryParams < QueryPa>ram n<ame="qu>eryparam_name&qu ot;queryparam_<value/QueryPa>ram < ... >/QueryParams ReasonPhra<sereason_fo>r_err<or o>r {variable}/ReasonPhrase StatusCo<deHTT>P_sta<tus_cod>e or {variable}/Stat<usCod>e < V>e<rb[GET|POST|PU>T|PATCH|DELETE|{variable}]/Verb Version[1.0|1.1|{variable}]/Verb /Set /AssignMessage
以下示例设置特定标头。将此政策附加在请求流中后,将允许上游系统接收原始入站请求中未包含的额外标头。
<AssignMessage name="AM-Set-He>ade<r&q>uot; < Set > Header<s Header name="authentic>ated-developer"{verifyapikey<.VAK-1.>devel<oper.id}>/He<ader> < /Heade>rs /S<et Assi>g<nTorequest/Ass>ignTo /AssignMessage
以下示例将覆盖响应的载荷以及 Content-Type
标头。
<AssignMessage name="AM-Overwrite-Pay>loa<d&q>uot; < Set Payload contentType="ap>plication/json&qu<ot;{ &qu>ot;<stat>us&<quot; : >42 }/Pay<load /S>e<t AssignTore>sponse/AssignTo /AssignMessage
<FormParams>
(<Set>
的子元素)
覆盖请求中的现有表单参数,并将其替换为您使用此元素指定的新值。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <FormParam> 元素的数组 |
父元素 |
<Set>
|
子元素 |
<FormParam> |
<FormParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_na>me"<; Set FormParams F>ormParam name=& <quot;formp>aram_name"<formparam_v>alu<e/Fo>r<mParam .>.. /FormParams /Set /AssignMessage
以下示例在新的自定义请求中将名为 “myparam” 的表单参数设置为 request.header.myparam
变量的值:
<AssignMessage name="AM-set-formpara>ms-<1&q>uot; < Set >FormPar<ams FormParam name>="myparam"{req<uest.heade>r.myp<aram}/FormP>ara<m > /<FormParams /Set AssignTo createNew="true" t>ransport="<http">;< type="re>quest"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]" > na<me=>"<;policy>_name&q<uot; SetHeaders >Header <name=&q>uot;header_name<"he>ade<r_va>l<ue/Header > ... /Headers /Set /AssignMessage
以下示例将 x-ratelimit-remaining
标头设置为 ratelimit.Quota-1.available.count
变量的值:
<AssignMessage name="AM-Set-RateLimit-He>ade<r&q>uot; < Set > Head<ers Header name="X-RateL>imit-Remaining"{ratelimit.Quot<a-1.ava>ilabl<e.count}>/He<ader> < /Heade>rs /Se<t Assig>n<Toresponse/Ass>ignTo /AssignMessage
如果您在政策 (<Set><Headers/></Set>
) 中定义了空的标头,则该政策不会设置任何标头。这将与省略 <Headers>
的效果相同。
<Path>
(<Set>
的子元素)
<Payload>
(<Set>
的子元素)
定义由 <AssignTo>
元素指定的请求或响应的消息正文。载荷可以是任何有效的内容类型,例如纯文本、JSON 或 XML。
默认值 | 空字符串 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<Set>
|
子元素 | 无 |
<Payload>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_name"Set Payload contentType=& quot;c ontent_type" variablePrefix =>"prefi <x"<>/span> < > <variableSuffix>="suffix"new_payload/Payload /Set /AssignMessage
以下示例设置纯文本载荷:
<AssignMessage name="set-paylo>ad-<1&q>uot; < Set Payload contentType=&q>uo<t;text/p>lai<n&qu>o<t;42/Payload > /Set /AssignMessage
以下示例设置 JSON 载荷:
<AssignMessage name="set-paylo>ad-<2&q>uot; < Set Payload contentType="ap>plication/json" {"name&q<uot;:&qu>ot;<foo&>q<uot;, "ty>pe":"bar"} /Payload /Set /AssignMessage
以下示例通过用大括号括住变量名称将变量值插入到载荷中:
<AssignMessage name="set-paylo>ad-<3&q>uot; < Set Payload contentType="ap>plication/json" {"name":"f<oo">, &<quot>;<type":&qu>ot;{variable_name}"} /Payload /Set /AssignMessage
在之前的 Apigee 版本中,您不能在 JSON 载荷中使用大括号表示变量引用。在这些版本中,您需要使用 variablePrefix
和 variableSuffix
属性来指定分隔符,并使用这些属性来封装变量名称,如下面所示:
<AssignMessage name="set-payloa>d-3<b&q>uot; < Set Payload contentType="application/json" variablePrefix=&q>uot;@" variableSuffix="#" {&quo<t;name&q>uot<;:&q>u<ot;foo", >"type":"@variable_name#"} /Payload /Set /AssignMessage
这种较早的语法仍然有效。
<Payload>
的内容被视为消息模板。这意味着,AssignMessage 政策在运行时会用所引用变量的值替换用大括号括住的变量。
以下示例使用大括号语法将载荷的一部分设置为变量值:
<AssignMessage name="set-paylo>ad-<4&q>uot; < Set Payload contentType=>"t<ext/>xml"< > r<oot> <e1>sunday</e1> <e2>funday</e2> < e3{>var1}</e3 > /<root> < /Payload > /Set /AssignMessage
下表介绍 <Payload>
的特性:
属性 | 说明 | 状态 | 类型 |
---|---|---|---|
contentType |
如果指定,则会将 |
可选 | 字符串 |
variablePrefix |
(可选)指定流变量的前导分隔符。默认值为 “{”。如需了解详情,请参阅流变量参考。 | 可选 | Char |
variableSuffix |
(可选)指定流变量的尾随分隔符。默认值为 “}”。如需了解详情,请参阅流变量参考。 | 可选 | Char |
<QueryParams>
(<Set>
的子元素)
使用新值覆盖请求中的现有查询参数。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | <QueryParam> 元素的数组 |
父元素 |
<Set>
|
子元素 |
<QueryParam> |
<QueryParams>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_nam>e"< Set QueryParams Qu e>ryParam name=&qu <ot;querypar>am_name"qu<eryparam_val>ue/<Quer>y<Param ..>. /QueryParams /Set /AssignMessage
以下示例将 “address” 查询参数设置为 request.header.address
变量的值:
<AssignMessage name="AM-set-querypara>ms<-1&>quot;< Set Q>ueryPar<ams QueryParam name>="address"{req<uest.header>.addr<ess}/QueryPa>ram< > </QueryParams > /Set /AssignMessage
仅在满足以下条件时才能使用 <QueryParams>
:
- HTTP 谓词:GET
- 消息类型:请求
如果您在政策 (<Set><QueryParams/></Set>
) 中定义了空的查询参数,则该政策不会设置任何查询参数。这与省略 <QueryParams>
相同。
<ReasonPhrase>
(<Set>
的子元素)
设置响应的原因短语。这通常用于与 <StatusCode>
结合使用进行调试。此元素对请求没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串 |
父元素 |
<Set>
|
子元素 | 无 |
<ReasonPhrase>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_name>" Set ReasonPhrase<reason_for_er>ror< or >{<variable}/Reas>onPhrase /Set /AssignMessage
以下示例定义了一个简单的原因短语:
<AssignMessage name="set-reasonphra>se-<1&q>uot; < Set Re>asonPhraseBa<d medicine/Re>aso<nPhr>ase< /Set AssignTo createNew="true" transport=&qu>o<t;http" t>ype="response"/ /AssignMessage
<ReasonPhrase>
的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称,如以下示例所示:
<AssignMessage name="AM-set-reasonphra>se-<2&q>uot; < Set Re>asonPhrase{calloutresponse.reas<on.phrase}/Re>aso<nPhr>ase< /Set > Assign<Torespons>e</AssignTo /Ass>ignMessage
仅在满足以下条件时才能使用 <ReasonPhrase>
:
- 消息类型:响应
<StatusCode>
(<Set>
的子元素)
设置响应的状态代码。此元素对请求没有任何影响。
默认值 | '200'(当 <AssignTo> 的 createNew 属性设置为 “true” 时) |
是否必需? | 可选 |
类型 | 字符串或 variable |
父元素 |
<Set>
|
子元素 | 无 |
<StatusCode>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy_na>me" Set StatusCode<HTTP_status>_co<de o>r< {variable}/St>atusCode /Set /AssignMessage
以下示例设置一个简单的状态代码:
<AssignMessage name="AM-set-statuscode>-40<4&q>uot; < Set >Sta<tusCode404/>Sta<tusC>ode< /Set > Assign<Torespons>e</AssignTo /Ass>ignMessage
<StatusCode>
的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称,如以下示例所示:
<AssignMessage name="set-statusco>de-<2&q>uot; < Set >StatusCode{calloutresponse.st<atus.code}/>Sta<tusC>ode< /Set > Assign<Torespons>e</AssignTo /Ass>ignMessage
仅在满足以下条件时才能使用 <StatusCode>
:
- 消息类型:响应
<Verb>
(<Set>
的子元素)
设置请求的 HTTP 谓词。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串或 variable |
父元素 |
<Set>
|
子元素 | 无 |
<Verb>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;pol>icy_name" Set Verb[GET|POS<T|PUT>|PA<TCH|>D<ELETE|{variabl>e}]/Verb /Set /AssignMessage
以下示例设置请求的一个简单谓词:
<AssignMessage name="AM-set-ve>rb-<1&q>uot; < Se>t < Ver>bPO<ST/V>erb< /Set > Assig<nToreques>t</AssignTo /Ass>ignMessage
<Verb>
的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称。
以下示例使用变量来填充谓词:
<AssignMessage name="AM-set-verb-to-dynamic-v>alu<e&q>uot; < Se>t Verb{my<_vari>abl<e}/V>erb< /Set > Assig<nToreques>t</AssignTo /Ass>ignMessage
仅在满足以下条件时才能使用 <Verb>
:
- 消息类型:请求
<Version>
(<Set>
的子元素)
设置请求的 HTTP 版本。此元素对响应没有任何影响。
默认值 | 不适用 |
是否必需? | 可选 |
类型 | 字符串或 variable |
父元素 |
<Set>
|
子元素 | 无 |
<Version>
元素使用以下语法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" > na<me=>"<;policy>_name" Set < Ve>rsi<on[1>.<0|1.1|{variabl>e}]/Verb /Set /AssignMessage
以下示例将版本号设置为 “1.1”:
<AssignMessage name="AM-set-versi>on-<1&q>uot; < Set > <Version1>.1/<Vers>io<n /Set /Ass>ignMessage
以下变量使用用大括号括住的变量设置版本号:
<AssignMessage name="AM-set-versi>on-<2&q>uot; < Set > Version{m<y_versio>n}/<Vers>ion< /Set > Assig<nToreques>t</AssignTo /Ass>ignMessage
<Version>
的内容被视为消息模板。这意味着将在运行时使用所引用变量的值替换用大括号括起来的变量名称。
仅在满足以下条件时才能使用 <Version>
:
- 消息类型:请求
创建自定义请求消息
您可以使用 AssignMessage 政策创建自定义请求消息。创建自定义请求后,您可以通过以下方式使用它:
- 在其他政策中访问它的变量
- 将它传递到外部服务
如需创建自定义请求消息,请在 AssignMessage 政策中使用 <AssignTo>
元素。将 createNew
设置为 “true”,并在元素正文中指定新消息的名称,如以下示例所示:
<AssignMessage name="AM-assign>to-2<" AssignTo createNew="true" transport=&>quot;http" <type=&quo>t;<request"N>ameOfNewMessage/AssignTo /AssignMessage
默认情况下,Edge 不会对自定义请求消息执行任何操作。创建之后,Edge 将以原始请求继续执行流。如需使用自定义请求,请政策(例如 ServiceCallout 政策)添加到代理,以便将自定义请求传递到外部服务。
以下示例创建自定义请求消息:
以下示例使用“分配消息”创建自定义请求对象:
<AssignMessage name="AssignMessa>ge-<3" AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;M>yCust<omReque>st/Ass<ignTo Copy Headers > <Header n>ame<=&quo>t;u<ser>-agen<t"/ > /Head<ers /Copy Set Que>ryParams QueryParam< name=">;addr<ess"{re>quest<.que>ryp<aram.>add<y}/Q>uer<yParam /QueryParams > VerbG<ET/Verb /Set IgnoreUnr>e<solvedVariable>sfalse /IgnoreUnresolvedVariables /AssignMessage
以下示例:
- 创建名为 “MyCustomRequest” 的新请求消息对象。
- 在 MyCustomRequest 中,此政策:
- 将传入请求的
user-agent
HTTP 标头的值复制到新消息。因为<Copy>
使用对user-agent
流变量的绝对引用,所以不需要将source
属性指定为<Copy>
。 - 将自定义消息的
address
查询参数设置为传入请求的addy
查询参数的值。 - 将 HTTP 谓词设置为
GET
。
- 将传入请求的
- 将
<IgnoreUnresolvedVariables>
设置为 “false”。当<IgnoreUnresolvedVariables>
为 “false” 时,如果政策尝试添加的其中一个变量不存在,则 Edge 将停止在 API 流中处理。
以下示例说明了如何使用“分配消息”创建自定义请求对象:
<AssignMessage name="AssignMessa>ge-<2" AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;>partn<er.r>eque<st/As>signT<o Set VerbPOST/Verb >Payload< conten><tType=&qu>ot;<text/xml&q><uot; > re<questope>rat<ion1>0<5/operation/re>quest /Payload /Set /AssignMessage
此示例创建一个名为 “partner.request” 的新自定义请求。然后,该方法会在新请求上设置 <Verb>
和 <Payload>
。
您可以在流中后面部分出现的另一个 AssignMessage 政策中访问自定义请求消息。以下示例获取自定义请求消息的 user-agent
标头的值:
<AssignMessage name="custom-request-1-ac>ces<s" D>isplayNamecustom-reques<t-1-access/D>isp<layName > AssignTopartn<er.reques>t/A<ssi>gnTo < Set > Head<ers Header name="user-agentCop>yCustomRequest"{MyCustomReques<t.heade>r.use<r-agent}>/He<ader> < /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 运行时中使用 AssignMessage 政策设置 SOAP 载荷,将 REST 请求转换为 SOAP 请求。 |
错误代码
本部分介绍此政策触发错误时返回的错误代码和错误消息,以及 Edge 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
故障代码 | HTTP 状态 | 原因 | 修复 |
---|---|---|---|
steps.assignmessage.SetVariableFailed |
500 | 该政策无法设置变量。请参阅故障字符串,查看未解析变量的名称。 | |
steps.assignmessage.VariableOfNonMsgType |
500 |
如果 消息类型变量表示整个 HTTP 请求和响应。内置 Edge
流变量 |
build |
steps.assignmessage.UnresolvedVariable |
500 |
如果“分配消息”政策中指定的变量属于以下任一种情况,便会出现此错误:
|
build |
部署错误
在您部署包含此政策的代理时,可能会发生这些错误。
错误名称 | 原因 | 修复 |
---|---|---|
InvalidIndex |
如果分配消息的 <Copy> 和/或 <Remove> 元素中指定的索引
为 0 或负数,则 API 代理的部署会失败。
|
build |
InvalidVariableName |
如果子元素 <Name> 为空或未在 <AssignVariable> 元素中指定,则 API 代理的部署将失败,因为没有向其分配值的有效变量名称。必须提供有效的变量名称。
|
build |
InvalidPayload |
政策中指定的负载无效。 |
故障变量
当此政策在运行时触发错误时,将设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
变量 | 地点 | 示例 |
---|---|---|
fault.name="fault_name" |
fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "UnresolvedVariable" |
assignmessage.policy_name.failed |
policy_name 是抛出故障的政策的用户指定名称。 | assignmessage.AM-SetResponse.failed = true |
错误响应示例
{ "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 提供了政策架构作为参考。
相关主题
API 平台示例中提供了 AssignMessage 的工作示例政策。
如需如何替换 ProxyEndpoint 中的 target.url
的更高级示例,请参阅这篇 Apigee 社区文章。
如需了解 ServiceCallout 政策中的 “set path” 的实际操作,请在 Apigee GitHub 示例中查看动手实践示例。只需克隆代码库,然后按照该主题中的说明操作即可。该示例使用 AssignMessage 政策设置请求路径,然后使用 Service Callout 政策向外部服务发出请求。