設定標頭

  • 發行項

適用於：所有 API 管理 層

set-header 原則會將值指派給現有的 HTTP 回應和/或要求標頭，或新增回應和/或要求標頭。

使用原則將 HTTP 標頭清單插入 HTTP 訊息中。 放在輸入管線中時，此原則會為傳遞至目標服務的要求設定 HTTP 標頭。 放在輸出管線中時，此原則會為傳送至閘道器用戶端的回應設定 HTTP 標頭。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 為了協助您設定此原則，入口網站會提供引導式表單型編輯器。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<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 時，編列多個相同名稱的項目會導致根據所有項目來設定標頭 (列出多次)；只有列出的值才會設定在結果中。

允許原則運算式。		 No override
NAME 指定要設定之標頭的名稱。 允許原則運算式。 Yes N/A

元素

名稱 描述 必要
value 指定要設定的標頭值。 允許原則運算式。 針對多個具有相同名稱的標頭，新增其他 value 元素。 No

使用方式

使用注意事項

多個標頭值會串連成一個 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、KeepAliveTransferEncoding無法修改或刪除。

範例

新增標頭、覆寫現有項目

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

如需詳細資訊，請參閱原則運算式和內容變數。

相關內容

如需使用原則的詳細資訊，請參閱：