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-Agent
、WWW-Authenticate
、Proxy-Authenticate
) - 可能包含日期(
Cookie
、Set-Cookie
、Warning
), - 包含日期(
Date
、Expires
、If-Modified-Since
、If-Unmodified-Since
、Last-Modified
、Retry-After
)。
如果出现这些例外情况,多个标头值将不会连接成一个字符串,并将作为单独的标头传递,例如:
User-Agent: value1
User-Agent: value2
User-Agent: value3
适用以下限制:
- 不支持移除
Server
标头。 - 标头:无法修改或删除
Connection
、ContentLength
、KeepAlive
、TransferEncoding
。
示例
添加标头,替代现有标头
<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>
相关策略
后续步骤
有关使用策略的详细信息,请参阅:
- 教程:转换和保护 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 策略示例