Set 标头

适用于:所有 API 管理层级

set-header 策略向现有的 HTTP 响应和/或请求标头赋值,或者添加新的响应和/或请求标头。

使用策略将 HTTP 标头列表插入到 HTTP 消息。 将此策略放到入站管道中后,它将为传递给目标服务的请求设置 HTTP 标头。 将此策略放到出站管道中后,它将为发送到网关客户端的响应设置 HTTP 标头。

提示

为了帮助你配置此策略,门户提供了基于窗体的引导式编辑器。 详细了解如何设置或编辑 API 管理策略

策略语句

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

属性

客户 说明 需要 默认
exists-action 指定当标头已指定时要执行的操作。 此属性必须具有下列值之一。

- override - 替换现有标头的值。
- skip - 不替换现有标头值。
- append - 将值追加到现有标头值。
- delete - 从请求中删除标头。

如果设置为 override,则登记多个同名的条目会导致根据所有条目(将多次列出)设置标头;结果中只会设置列出的值。

允许使用策略表达式。
override
name 指定要设置的标头的名称。 允许使用策略表达式。 空值

元素

名称 说明 必需
value 指定要设置的标头的值。 允许使用策略表达式。 如需多个标头使用同一名称,可添加更多的 value 元素。

使用情况

使用注意事项

标头的多个值会连接到 CSV 字符串,例如:

headerName: value1,value2,value3

例外情况包括标准化标头,其值:

  • 可能包含逗号(User-AgentWWW-AuthenticateProxy-Authenticate
  • 可能包含日期(CookieSet-CookieWarning),
  • 包含日期(DateExpiresIf-Modified-SinceIf-Unmodified-SinceLast-ModifiedRetry-After)。

如果出现这些例外情况,多个标头值将不会连接成一个字符串,并将作为单独的标头传递,例如:

User-Agent: value1
User-Agent: value2
User-Agent: value3

适用以下限制:

  • 不支持移除 Server 标头。
  • 标头:无法修改或删除 ConnectionContentLengthKeepAliveTransferEncoding

示例

添加标头,替代现有标头

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

删除标头

 <set-header name="some header name" exists-action="delete" />

将上下文信息转发到后端服务

此示例演示了如何在 API 级别应用策略,以便将上下文信息提供给后端服务。

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

有关详细信息,请参阅策略表达式上下文变量

后续步骤

有关使用策略的详细信息,请参阅: