Set backend service
set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. This policy changes the backend service base URL of the incoming request to the one specified in the policy.
Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.
<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||New backend service base URL. Policy expressions are allowed.||One of
|backend-id||Identifier (name) of the backend to route primary or secondary replica of a partition. Policy expressions are allowed.||One of
|sf-resolve-condition||Only applicable when the backend is a Service Fabric service. Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. Policy expressions are allowed.||No||N/A|
|sf-service-instance-name||Only applicable when the backend is a Service Fabric service. Allows changing service instances at runtime. Policy expressions are allowed.||No||N/A|
|sf-partition-key||Only applicable when the backend is a Service Fabric service. Specifies the partition key of a Service Fabric service. Policy expressions are allowed.||No||N/A|
|sf-listener-name||Only applicable when the backend is a Service Fabric service and is specified using
- Policy sections: inbound, backend
- Policy scopes: global, workspace, product, API, operation
- Gateways: dedicated, consumption, self-hosted
Currently, if you define a base
set-backend-service policy using the
backend-id attribute and inherit the base policy using
<base /> within the scope, then it can only be overridden with a policy using the
backend-id attribute, not the
Route request based on value in query string
In this example the
set-backend-service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the 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>
Initially the backend service base URL is derived from the API settings. So the request URL
http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.
When the <choose> policy statement is applied the backend service base URL may change again either to
http://contoso.com/api/9.1, depending on the value of the version request query parameter. For example, if the value is
"2013-15" the final request URL becomes
If further transformation of the request is desired, other Transformation policies can be used. For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.
Route requests to a service fabric backend
In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.
<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>
For more information about working with policies, see: