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

Forward request

2025-07-26

适用于：所有 API 管理层级

forward-request 策略将传入请求转发到请求forward-request中指定的后端服务。后端服务 URL 在 API 设置中指定，可以使用设置后端服务策略进行更改。

Important

需有此策略才能将请求转发到 API 后端。默认情况下，API 管理会在全局范围设置此策略。
删除此策略会导致请求不会转发到后端服务。成功完成入站部分中的策略后，将立即评估出站部分中的策略。

Note

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

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 ms。允许使用策略表达式。你可以指定 `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

策略节：后端
策略范围：全局、工作区、产品、API、操作
网关：经典、v2、消耗、自承载、工作区

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>

Routing

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