API 管理中的后端

适用于：所有 API 管理层级

API 管理中的后端（或 API 后端）是实现前端 API 及其操作的一项 HTTP 服务。

导入某些 API 时，API 管理会自动配置 API 后端。 例如，API 管理会在导入以下项时配置后端 Web 服务：

• OpenAPI 规范。
• SOAP API。

对于其他 API（例如来自 Azure 服务的 API），无需显式指定后端服务即可导入 Azure 资源。 示例包括：

• HTTP 触发的 Azure 函数应用
• 逻辑应用。

API 管理还支持将其他资源用作 API 后端，例如：

• Service Fabric 群集。
• AI 服务
• 自定义服务

对于这些后端，可以在 API 管理中创建 后端实体 ，并在 API 中引用它。

后端的优点

API 管理支持后端实体，方便你管理 API 的后端服务。 后端实体会封装有关后端服务的信息，提高在各 API 中的可重用性并改进了治理。

对以下一个或多个项使用后端：

• 授权后端服务请求的凭据
• 如果为标头或查询参数身份验证配置 了命名值 ，则利用 API 管理功能来维护 Azure Key Vault 中的机密
• 定义断路器规则来保护后端，以免请求过多
• 将请求路由或均衡负载到多个后端

在 Azure 门户中或使用 Azure API 或工具配置和管理后端实体。

创建后端

可以在 Azure 门户中或使用 Azure API 或工具创建后端。

注意

从 Microsoft Foundry 或其他 AI 服务导入某些 API 时，API 管理服务会自动配置后端实体。

若要在门户中创建后端，请执行以下作：

1. 登录到 门户 并转到 API 管理实例。
2. 在左侧菜单中，选择 “API>后端>+ 创建新后端”。
3. 在 “后端 ”页上，完成以下步骤：
   1. 输入 名称 和可选的 说明 以用于后端。
   2. 选择一种 后端托管类型，例如用于 Function App 或逻辑应用等的 Azure 资源，用于自定义服务的 自定义 URL，或 Service Fabric 群集。
   3. 在 运行时 URL 中，输入 API 请求转发到的后端服务的 URL。
   4. 在 “高级”下，可以选择禁用后端的证书链或证书名称验证。
   5. 在 “将此后端服务添加到后端池”下，可以选择或为后端创建 负载均衡池 。
   6. 在 断路器规则下，可以选择为后端配置 断路器 。
   7. 在 “授权凭据”下，可以选择配置凭据以授权访问后端。 选项包括 API 管理实例中配置的请求标头、查询参数、 客户端证书或系统分配的托管标识或用户分配的 托管标识 。
   8. 选择 创建。

创建后端后，可以随时更新后端设置。 例如，可以添加断路器规则、更改运行时 URL 或添加授权凭据。

为授权凭据配置托管标识

可以使用 API 管理实例中配置的系统分配或用户分配的 托管标识 来授权访问后端服务。 若要为授权凭据配置托管标识，请完成以下步骤：

1. 在后端配置的 “授权凭据 ”部分中，选择“ 托管标识 ”选项卡，然后选择“ 启用”。

2. 在 客户端标识中，选择 系统分配的标识 或实例中配置的用户分配标识。

3. 在 资源 ID 中，输入目标 Azure 服务或表示后端的 Microsoft Entra 应用程序的应用程序 ID。 例如，输入 https://cognitiveservices.azure.com 以访问 Azure OpenAI 服务。

   有关更多示例，请参阅 身份验证-托管身份 策略参考。

4. 选择 创建。

注意

此外，为托管标识分配适当的权限或 RBAC 角色以访问后端服务。 例如，如果后端是 Azure OpenAI 服务，请分配托管标识角色 Cognitive Services User 。

为授权凭据配置证书

可以通过使用客户端证书进行双向 TLS 身份验证或自定义证书颁发机构（CA）证书来确保网关访问后端服务的安全性。

配置客户端证书

如果后端服务使用由已知 CA 颁发的证书进行保护，则可以在后端实体中添加客户端证书：

1. 将证书添加到 API 管理实例。 可以引用在 Azure Key Vault 中管理的证书或上传 PFX 文件。
2. 在后端配置的 “授权凭据 ”部分中，选择 “客户端证书 ”选项卡。
3. 在下拉列表中，选择要使用的客户端证书。
4. 选择 创建。

配置 CA 证书

如果后端服务使用自定义 CA 证书，则可以在后端实体中引用自定义 CA 证书。 可能需要执行此步骤来建立后端服务器证书的信任 - 例如，使用自签名证书、不受信任的根证书或部分证书链。

注意

目前，只能在 v2 层的后端实体中配置 CA 证书详细信息。

若要添加 CA 证书详细信息，请执行以下步骤：

1. 在后端配置的 “授权凭据 ”部分中，选择 “CA 证书”。
2. 选择 “+ 添加 CA 证书详细信息”。
3. 在 “添加 CA 证书 ”窗格中，选择以下选项之一：
   • 证书指纹 - 输入自定义 CA 证书的指纹（SHA-1、SHA-256 或 SHA-512 哈希）。
   • 使用者名称和颁发者指纹 - 输入唯一标识 CA 和 CA 指纹的主题名称。
4. 选择 并添加。
5. 选择 创建。

注意

在后端实体中配置自定义 CA 证书的详细信息时，API 管理始终验证证书名称和证书链，而不考虑在后端 backendTlsProperties中启用或禁用验证设置。

使用 set-backend-service 策略来引用后端

创建后端后，可以在 API 中引用后端标识符（名称）。 使用 set-backend-service 策略将传入的 API 请求定向到后端。 如果已为 API 配置了后端 Web 服务，则可以改为使用 set-backend-service 策略将请求重定向到后端实体。 例如：

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

注意

也可使用 base-url。 通常，格式为 https://backend.com/api。 避免在末尾添加斜杠以防止配置错误。 通常，后端中的 base-url 和 HTTP(S) 终结点值应匹配，以便在前端和后端之间实现无缝集成。 请注意，API 管理实例会将后端服务名称追加到 base-url。

可以将条件逻辑与 set-backend-service 策略结合使用，根据位置、调用的网关或其他表达式来更改有效的后端。

例如，下面是一个基于调用的网关将流量路由到另一个后端的策略：

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

小窍门

API 管理还会在收到 API 请求时自动检测和使用后端实体。 在运行时，如果有与 API 管理向其发送请求的后端服务的 URL 匹配的后端实体，则它使用后端实体。 无需显式使用 set-backend-service。

断路器

API 管理在后端资源中公开了断路器属性，以防止后端服务因请求过多而过载。

• 断路器属性定义断路器的跳变规则，例如，在定义的时间间隔内故障条件的数量或百分比，以及指示故障的状态代码范围。
• 当断路器发生跳变时，API 管理在定义的时间内将停止向后端服务发送请求，并将“503 服务不可用”响应返回到客户端。
• 在配置的跳变持续时间过后，线路将重置，流量将恢复到后端。

后端断路器是一种断路器模式的实现方式，允许后端从过载情况中恢复。 它扩充了常规速率限制和并发限制策略，实施这些策略可以保护 API 管理网关和后端服务。

注意

• 目前，API 管理的消耗层不支持后端断路器。
• 由于 API 管理体系结构的分布式特性，断路器跳变规则是近似的。 网关的各个实例不会根据同一实例的信息来同步和应用断路器规则。
• 目前，只能为后端断路器配置一个规则。

谨慎

如果将 Azure OpenAI 服务配置为后端，并且服务收到过多请求，它将返回 429 Too Many Requests 响应状态代码和 Retry-After 标头，其值可能很大（例如，1 天）。 使用 Azure OpenAI 后端，实现断路器规则来处理 429 响应并接受 Retry-After 持续时间。

示例

使用 Azure 门户、API 管理 REST API 或 Bicep 或 ARM 模板在后端配置断路器。 在以下示例中，当 1 小时内出现三个或更多表示服务器错误的 状态代码时，API 管理实例 myAPIM 中 myBackend 的断路器就会跳闸5xx。

此示例中的断路器在 1 小时后重置。 如果响应中存在 Retry-After 标头，断路器会接受该值，并等待指定时间后再次向后端发送请求。

门户

1. 在 Azure 门户中，转到 API 管理实例。
2. 在左侧菜单中，选择“API”“后端”> 你的后端。>
3. 在后端页中，选择“设置>断路器设置”添加新设置>。
4. 在 “创建新的断路器 ”页中，配置规则：
   • 规则名称：输入规则的名称，例如 myBackend。
   • 故障计数：输入 3。
   • 失败间隔：保留默认值 1 小时。
   • 失败状态代码范围：选择 500 - 599。
   • 行程持续时间：保留默认值 1 小时。
   • 在 HTTP 响应中检查“Retry-After”标头：选择 True（Accept）。

肱二头肌

在具有断路器的后端资源的 Bicep 文件中包含类似于以下内容的代码片段：

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackend'
  properties: {
    url: 'https://mybackend.com'
    protocol: 'http'
    circuitBreaker: {
      rules: [
        {
          failureCondition: {
            count: 3
            errorReasons: [
              'Server errors'
            ]
            interval: 'PT1H' 
            statusCodeRanges: [
              {
                min: 500
                max: 599
              }
            ]
          }
          name: 'myBreakerRule'
          tripDuration: 'PT1H'  
          acceptRetryAfter: true
        }
      ]
    }
   }
 }

ARM

在具有断路器的后端资源的 ARM 模板中包含类似于以下内容的 JSON 代码片段：

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackend",
  "properties": {
    "url": "https://mybackend.com",
    "protocol": "http",
    "circuitBreaker": {
      "rules": [
        {
          "failureCondition": {
            "count": "3",
            "errorReasons": [ "Server errors" ],
            "interval": "PT1H",
            "statusCodeRanges": [
              {
                "min": "500",
                "max": "599"
              }
            ]
          },
          "name": "myBreakerRule",
          "tripDuration": "PT1H",
          "acceptRetryAfter": true
        }
      ]
    }
  }
}

负载均衡池

如果想要为 API 实现多个后端，并跨这些后端对请求进行负载均衡，API 管理支持后端 池 。 池是一个后端集合，这些后端被视为用于负载均衡的单个实体。

将后端池用于诸如以下场景：

• 将负载分散到多个后端，每个后端可能具备单独的断路器。
• 将负载从一组后端转移到另一组进行升级（蓝绿部署）。

注意

• 最多可以在池中包含 30 个后端。
• 由于 API 管理体系结构的分布式特性，后端负载均衡是近似的。 网关的不同实例不会根据同一实例上的信息进行同步和负载均衡。

负载均衡选项

API 管理支持以下后端池负载均衡选项：

负载均衡选项	DESCRIPTION
循环赛制	默认情况下，请求会均匀分发到池中的各个后端。
加权	为池中的后端分配权重，并根据每个后端的相对权重分配请求。 适用于蓝绿部署等场景。
基于优先级	将后端组织成优先级组。 首先将请求发送到更高的优先级组;在组中均匀分配请求，或根据分配的权重分配请求。

注意

仅当高优先级组中的所有后端都因触发断路器规则而不可用时，API 管理服务才会使用低优先级组中的后端。

会话感知

使用上述任一负载均衡选项，可以启用 会话感知（会话 相关性），以确保会话期间来自特定用户的所有请求都转到池中的同一后端。 API 管理设置会话 ID Cookie 来维护会话状态。 例如，在后端（如 AI 聊天助手或其他聊天代理）将请求从同一会话路由到同一终结点的情况下，此选项非常有用。

注意

负载均衡池中的会话感知功能将首先发布到 AI Gateway Early 更新组。

管理会话感知的 Cookie

使用会话感知时，客户端必须相应地处理 Cookie。 客户端需要存储 Set-Cookie 标头值，并使用后续请求发送它来维护会话状态。

可以使用 API 管理策略来帮助为会话感知设置 Cookie。 例如，对于助手 API（Microsoft Foundry 模型中 Azure OpenAI 的一项功能），客户端需要保留会话 ID，从主体中提取线程 ID，并为每个调用保留对，并发送正确的 cookie。 此外，客户端需要知道何时发送 Cookie 或何时不发送 Cookie 标头。 可以通过定义以下示例策略来适当地处理这些要求：

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

示例

使用门户、API 管理 REST API 或 Bicep 或 ARM 模板配置后端池。 在以下示例中，API 管理实例 myAPIM 中的后端 myBackendPool 配置了后端池。 池中的示例后端名为 backend-1 和 backend-2。 两个后端都处于最高优先级组中;在组中， backend-1 的权重大于 backend-2。

门户

1. 在 Azure 门户中，转到 API 管理实例。
2. 在左侧菜单中，选择“API”“后端”> 你的后端。>
3. 在 “后端 ”页中，选择 “负载均衡器 ”选项卡。
4. 选择 “+ 创建新池”。
5. 在 “创建新的负载均衡池 ”页中，输入以下信息：
   • 名称：输入池的名称，例如 myBackendPool。
   • 说明：（可选）输入说明。
   • 将后端添加到池：选择要添加到池的一个或多个后端。
   • 后端权重和优先级：选择 “自定义权重和 优先级”以配置池中每个后端的权重和优先级。 例如，如果添加了两个名为 backend-1 和 backend-2 的后端，请将 backend-1 的权重设置为 3，并将 后端 的权重设置为 1，并将两个后端的优先级设置为 1。
   • 选择 创建。

肱二头肌

在 Bicep 文件中为负载均衡池添加类似于以下内容的代码片段。 将后端实体的 type 属性设置为 Pool，并在池中指定后端。

此示例包含会话感知的可选 sessionAffinity 池配置。 它设置 Cookie，以便将来自用户会话的请求路由到池中的特定后端。

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackendPool'
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1'
          priority: 1
          weight: 3
        }
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2'
          priority: 1
          weight: 1
        }
      ],
      "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

ARM

在 ARM 模板中为负载均衡池包括如下所示的 JSON 代码片段。 将 type 后端资源的属性设置为 Pool，并在池中指定后端。

此示例包含会话感知的可选 sessionAffinity 池配置。 它设置 Cookie，以便将来自用户会话的请求路由到池中的特定后端。

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackendPool",
  "properties": {
    "description": "Load balancer for multiple backends",
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1",
          "priority": "1", 
          "weight": "3" 
        },
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2",
          "priority": "1",
          "weight": "1"    
        }
      ],
        "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

限制

• 对于“开发人员”层级和“高级”层级，在内部虚拟网络中部署的 API 管理实例可能会在网关终结点 URL 和后端 URL 相同时引发 HTTP 500 BackendConnectionFailure 错误。 如果遇到此限制，请按照技术社区博客中内部虚拟网络模式下的自链式 API 管理请求限制一文的说明操作。
• 目前，只能为后端断路器配置一个规则。

相关内容

• 博客：使用 Azure API 管理断路器和通过 Azure OpenAI 服务进行负载均衡
• 使用 Azure 门户设置 Service Fabric 后端。
• 快速入门 - 使用 Bicep 在 Azure API 管理中创建后端池，以便对 OpenAI 请求进行负载均衡
• 如需了解当断路器断开或重置时网关生成的事件网格事件的信息，请参阅 Azure API 管理作为事件网格源。 在后端问题呈报之前使用这些事件采取行动。