共用方式為


轉寄要求

適用於:所有 APIM 層

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

重要

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

注意

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

原則陳述式

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

屬性

屬性 描述 是必要欄位 預設
timeout 等待後端服務在逾時錯誤引發之前傳回 HTTP 回應標頭的秒數。 最小值為 0 秒。 不接受大於 240 秒的值,因為基礎網路基礎結構在此時間之後可能會捨棄閒置連線。 允許使用原則運算式。 您可以指定 timeouttimeout-ms 其中一項,但不能兩者並存。 No 300
timeout-ms 等待後端服務在逾時錯誤引發之前傳回 HTTP 回應標頭的毫秒數。 最小值為 0 毫秒。 允許使用原則運算式。 您可以指定 timeouttimeout-ms 其中一項,但不能兩者並存。 No N/A
continue-timeout 等待後端服務在逾時錯誤引發之前傳回 100 Continue 狀態碼的秒數。 允許使用原則運算式。 No N/A
http-version 將 HTTP 回應傳送至後端服務時要使用的 HTTP 規格版本。 使用 2or1 時,閘道會優先使用 HTTP /2 而非 /1,但如果 HTTP /2 無法運作,則會切換回 HTTP /1。 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

使用方式

範例

將要求傳送至 HTTP/2 後端

下列 API 層級原則會將所有 API 要求轉送至 HTTP/2 後端服務。

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

這是 HTTP /2 或 gRPC 工作負載的必要項目,目前僅有自我裝載閘道才支援。 請在 API 閘道概觀中了解詳細資訊。

使用逾時間隔轉送要求

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

如需使用原則的詳細資訊,請參閱: