共用方式為

Forward request

適用於：所有 APIM 層

forward-request 原則會將內送要求轉送給要求內容中指定的後端服務。 後端服務 URL 會指定於 API 設定中，而且可以使用設定後端服務原則加以變更。

Important

  • 需要此原則，才能將要求轉送至 API 後端。 根據預設，APIM 於全域範圍設定此原則。
  • 移除此原則會導致要求未轉接至後端服務。 輸出區段的原則會在輸入區段中的原則成功完成後立即評估。

Note

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則。

Policy statement

<forward-request http-version="1 | 2or1 | 2" timeout="time in seconds (alternatively, use timeout-ms)" | timeout-ms="time in milliseconds (alternatively, use timeout)" continue-timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

Attributes

Attribute Description Required Default
timeout 等待後端服務在逾時錯誤引發之前傳回 HTTP 回應標頭的秒數。 最小值為 0 秒。 不接受大於 240 秒的值，因為基礎網路基礎結構在此時間之後可能會捨棄閒置連線。 允許使用原則運算式。 您可以指定 timeout 或 timeout-ms 其中一項，但不能兩者並存。 No 300
timeout-ms 等待後端服務在逾時錯誤引發之前傳回 HTTP 回應標頭的毫秒數。 最小值為 0 毫秒。 允許使用原則運算式。 您可以指定 timeout 或 timeout-ms 其中一項，但不能兩者並存。 No N/A
continue-timeout 等待後端服務在逾時錯誤引發之前傳回 100 Continue 狀態碼的秒數。 允許使用原則運算式。 No N/A
http-version 將 HTTP 要求傳送至後端服務時要使用的 HTTP 通訊協定版本：
- 1：HTTP/1
- 2：HTTP/2
- 2or1：閘道偏好 HTTP/2 而非 HTTP/1，但如果 HTTP/2 無法運作，則會回復為 HTTP/1。

選取的閘道支援 HTTP/2 輸出。 如需詳細資訊，請參閱 使用量注意事項 。		 No 1
follow-redirects 指定來自後端服務的重新導向會由閘道遵循或傳回給呼叫者。 允許使用原則運算式。 No false
buffer-request-body 設定為 true 時，要求會進行緩衝處理，並在重試時重複使用。 No false
buffer-response 影響區塊式回應的處理。 設定為 false 時，從後端收到的每個區塊都會立即傳回給呼叫者。 設定為 true 時，區塊會進行緩衝處理 (8 KB，除非偵測到資料流結尾)，然後才會傳回給呼叫者。

使用後端設定為 false，例如實作要求內容立即傳回或串流至呼叫者的伺服器傳送事件 (SSE)。 不允許使用原則運算式。		 No true
fail-on-error-status-code 設定為 true 時，會觸發範圍介於 400 到 599 (含此二值) 之回應碼的 on-error 區段。 不允許使用原則運算式。 No false

Usage

Usage notes

  • http-version使用 屬性來啟用從閘道輸出到後端的 HTTP/2 通訊協定。 將 屬性設定為 2or1 或 2。 目前，自我裝載閘道和 v2 閘道的預覽版支援 HTTP/2 輸出。

    Important

    在 v2 閘道中，支援 HTTP/2 輸入至 API 管理閘道，並從閘道輸出至後端，但不支援端對端。 目前，v2 閘道會在將要求轉送至後端之前，將連入 HTTP/2 連線降級至 HTTP/1。

Examples

將要求傳送至 HTTP/2 後端

下列 API 層級原則會將所有 API 要求轉送至 HTTP/2 後端服務。 例如，使用此原則將自我裝載網關的要求轉送至 gRPC 後端。

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request http-version="2or1"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

使用逾時間隔轉送要求

下列 API 層級原則會將所有 API 要求轉送至後端服務，且逾時間隔為 60 秒。

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

從父範圍繼承原則

此作業層級原則使用 base 元素，從父 API 層級範圍繼承後端原則。

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

不要從父範圍繼承原則

此作業層級原則會明確地將所有要求轉送至後端服務 (逾時值為 120)，且不會繼承父 API 層級的後端原則。 如果後端服務回應了錯誤狀態碼從 400 到 599 (含這兩者)，則會觸發 on-error 區段。

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120" fail-on-error-status-code="true" />
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

不要將要求轉送至後端

此作業層級原則不會將要求轉送至後端服務。

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Related content

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

  • Last updated on