设置后端服务

项目
08/19/2024

适用于：所有 API 管理层级

使用 set-backend-service 策略将传入请求重定向到一个后端，此后端不同于在 API 设置中为该操作指定的后端。此策略将传入请求的后端服务基 URL 更改为在策略中指定的一个 URL 或后端。

通过引用后端实体，可以在单个位置管理后端服务基 URL 和其他设置，并在多个 API 和操作中重复使用它们。此外，还可以实施跨后端服务池的流量负载均衡和断路器规则，以保护后端免受过多请求。

注意

后端实体可以通过 Azure 门户管理 API 和 PowerShell 进行管理。

注意

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

策略语句

<set-backend-service base-url="base URL of the backend service"  backend-id="name of the backend entity specifying base URL of the backend service" sf-resolve-condition="condition" sf-service-instance-name="Service Fabric service name" sf-listener-name="Service Fabric listener name" />

属性

属性	说明	需要	默认
base-url	新的后端服务基 URL。允许使用策略表达式。	必须存在 `base-url` 或 `backend-id` 中的一个。	空值
backend-id	用于路由分区的主要或次要副本的后端标识符（名称）。允许使用策略表达式。	必须存在 `base-url` 或 `backend-id` 中的一个。	空值
sf-resolve-condition	只有在后端为 Service Fabric 服务时才适用。确定对 Service Fabric 后端的调用是否针对新解析重复进行的条件。允许使用策略表达式。	否	空值
sf-service-instance-name	只有在后端为 Service Fabric 服务时才适用。允许在运行时更改服务实例。允许使用策略表达式。	否	空值
sf-partition-key	只有在后端为 Service Fabric 服务时才适用。指定 Service Fabric 服务的分区键。允许使用策略表达式。	否	空值
sf-listener-name	只有在后端为 Service Fabric 服务且使用 `backend-id` 指定时才适用。使用 Service Fabric Reliable Services 可在服务中创建多个侦听器。当后端可靠服务具有多个侦听器时，此属性用于选择特定侦听器。如果未指定此属性，API 管理将尝试使用没有名称的侦听器。没有名称的侦听器对于只有一个侦听器的 Reliable Services 来说是非常典型的。允许使用策略表达式。	否	空值

使用情况

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

使用注意事项

目前，如果你使用 backend-id 属性定义基本 set-backend-service 策略并在范围内使用 <base /> 继承基本策略，那么该策略只能被使用 backend-id 属性（而不是 base-url 属性）的策略替代。

示例

根据查询字符串中的值路由请求

在此示例中，set-backend-service 策略根据查询字符串中传递的版本值将请求路由到一个后端服务，该服务不同于在 API 中指定的服务。

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

后端服务基 URL 最初派生自 API 设置。因此，请求 URL https://contoso.azure-api.cn/api/partners/15?version=2013-05&subscription-key=abcdef 变为 http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef，其中 http://contoso.com/api/10.4/ 是在 API 设置中指定的后端服务 URL。

应用 <choose> 策略语句时，后端服务基 URL 可能会再次更改为 http://contoso.com/api/8.2 或 http://contoso.com/api/9.1，具体取决于版本请求查询参数的值。例如，如果值为 "2013-15"，最终请求 URL 将变为 http://contoso.com/api/8.2/partners/15?version=2013-15&subscription-key=abcdef。

如果需要进一步转换请求，可使用其他转换策略。例如，在将请求路由到特定于版本的后端以后，要删除版本查询参数，可以使用设置查询字符串参数策略删除现在的冗余版本属性。

将请求路由到 Service Fabric 后端

在此示例中，策略使用 userId 查询字符串作为分区键并使用该分区的主要副本，将请求路由到 Service Fabric 后端。

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

路由

后续步骤

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

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例

通过