通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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>

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

相关内容

有关使用策略的详细信息，请参阅：