API 管理中的後端

適用於：所有 APIM 層

API 管理中的「後端」 (或 API 後端) 是一種 HTTP 服務，可實作您的前端 API 及其作業。

當你匯入某些 API 時，API Management 會自動配置 API 後端。 例如，API 管理在匯入時設定後端 Web 服務：

• OpenAPI 規格。
• SOAP API。

對於其他 API，例如 Azure 服務的 API，你匯入 Azure 資源時不會明確指定後端服務。 範例包括：

• 一個HTTP觸發的 Azure Function App
• 一個 邏輯應用程式。

API 管理也支援使用其他資源作為 API 後端，例如：

• Service Fabric 叢集。
• AI 服務
• 一個客製化服務

對於這些後端，你可以在 API Management 中建立 後端實體 ，並在 API 中引用它。

後端的優點

APIM 支援後端實體，因此您可以管理 API 的後端服務。 後端實體會封裝後端服務的相關資訊，促進跨 API 的重複使用性，並改善治理。

針對下列一或多個項目使用後端：

• 授權對後端服務的要求認證
• 如果標頭或查詢參數認證已設定 命名值 ，請利用 API 管理功能在 Azure Key Vault 中維護秘密
• 定義斷路器規則，以保護後端免於太多要求
• 將要求路由或負載平衡至多個後端

在 Azure 入口網站中配置和管理後端實體，或使用 Azure API 或工具。

建立後端

你可以在 Azure 入口網站建立後端，或使用 Azure API 或工具。

附註

當你匯入某些 API，例如 Microsoft Foundry 或其他 AI 服務的 API，API Management 會自動配置一個後端實體。

若要在入口網站中建立後端：

1. 登入至 入口，然後前往你的 API 管理實例。
2. 在左側功能表中，選取 [ API>後端>+ 建立新後端]。
3. 在 後端 頁面，請完成以下步驟：
   1. 為後端輸入一個名稱和選填的描述。
   2. 選擇 端主機類型，例如 Azure 資源（如 Function App 或 Logic App），自訂 URL 作為自訂服務，或 Service Fabric 叢集。
   3. 在 [運行時間 URL] 中，輸入 API 要求轉送至之後端服務的 URL。
   4. 在 [ 進階] 下，選擇性地停用後端的憑證鏈結或憑證名稱驗證。
   5. 在 [ 將此後端服務新增至後端集區] 下，選擇性地選取或建立後端的 負載平衡集區 。
   6. 在 [斷路器規則] 下，選擇性地設定後端的 斷路器 。
   7. 在 [授權認證] 底下，選擇性地設定認證以授權存取後端。 選項包括 API 管理實例中所設定的要求標頭、查詢參數、 用戶端憑證或系統指派或使用者指派的 受控識別 。
   8. 選取 ，創建。

建立後端之後，您可以隨時更新後端設定。 例如，你可以新增斷路器規則、更改執行時網址，或新增授權憑證。

設定管理的身分識別以取得授權憑證

您可以使用 API 管理實例中設定的系統指派或使用者指派的 受控識別 ，來授權存取後端服務。 要設定授權憑證的管理身份，請完成以下步驟：

1. 在後端組態的 [ 授權認證 ] 區段中，選取 [ 受控識別] 索引卷 標，然後選取 [ 啟用]。

2. 在 客戶端身份中，選擇系統 指派身份 或你在實例中設定的使用者指派身份。

3. 在 [資源標識符] 中，輸入代表後端的目標 Azure 服務或您自己Microsoft Entra 應用程式的應用程式識別符。 例如，輸入 https://cognitiveservices.azure.com 為 Azure OpenAI 服務。

   如需更多範例，請參閱 authentication-managed-identity 原則參考。

4. 選取 ，創建。

附註

同時將適當的權限或 RBAC 角色指派給受控身分，以存取後端服務。 例如，如果後端是 Azure OpenAI 服務，就將管理身份分配給該 Cognitive Services User 角色。

設定授權用的憑證

你可以透過使用客戶端憑證或自訂憑證授權機構（CA）憑證的互惠 TLS 認證，來保護後端服務的閘道存取。

設定用戶端憑證

如果後端服務是由知名 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 Management 總是會驗證憑證名稱和憑證鏈，無論你在後端 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 Management 傳送請求的後端服務 URL 相符，它就會使用該後端實體。 你不必明確使用 set-backend-service。

斷路器

APIM 會在後端資源中公開斷路器屬性，以保護後端服務不至負荷過多要求。

• 斷路器屬性會定義規則來中斷斷路器，例如定義時間間隔期間失敗狀況的數目或百分比，以及指出失敗的狀態代碼範圍。
• 斷路器跳脫時，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 小時內發生錯誤時，在 APIM 執行個體 myAPIM 的 5xx 中的斷路器會跳掉。

此範例中的斷路器會在1小時後重設。 如果回應中有 Retry-After 標頭，斷路器會接受值，並在再次將要求傳送至後端之前等候指定的時間。

入口網站

1. 在 Azure 入口網站中，移至您的 API 管理實例。
2. 在左側功能表中，選取 [API]>[後端]> 您的後端。
3. 在後端頁面中，選取 [ 設定>斷路器設定>] [新增]。
4. 在 [ 建立新的斷路器] 頁面中，設定規則：
   • 規則名稱：輸入規則的名稱，例如 myBackend。
   • 失敗計數：輸入 3。
   • 失敗間隔：保留預設值 1 小時。
   • 失敗狀態代碼範圍：選取 500 - 599。
   • 車程持續時間：保留預設值 1 小時。
   • 在 HTTP 回應中檢查 'Retry-After' 標頭：選取 [True] [接受]。

肱二頭肌

針對具有斷路器的後端資源，請在 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 Management 支援後端 池 ，當你想為一個 API 實作多個後端並在這些後端間做負載平衡時。 集區是將多個後端視為單一實體來進行負載平衡的集合。

針對類似下列案例的案例使用後端集區：

• 將負載分散到多個後端，這些後端可能有獨立的後端斷路器。
• 將負載從一組後端轉移到另一組進行升級（藍綠部署）。

附註

• 您可以在集區中包含最多 30 個後端。
• 由於 API 管理架構的分散式本質，後端負載平衡大致近似。 不同的閘道器實例不會根據相同實例的資訊進行同步以及負載平衡。

負載平衡選項

APIM 支援後端集區的下列負載平衡選項：

負載平衡選項	說明
循環輪替	根據預設，要求會被平均分配到集區中的各個後端。
加權	為池中的後端分配權重，並根據每個後端的相對權重分配請求。 適用於藍綠部署等案例。
優先順序型	將後端組織成優先順序群組。 先將請求發送給較高優先權的群組;在群組內，請平均分配請求或依分配權重。

附註

API 管理服務只有在所有高優先權群組的後端因斷路器規則觸發而無法使用時，才會使用較低優先權群組的後端。

工作階段感知

透過上述任一負載平衡選項，你可以啟用 會話感知 （會話親和性），以確保會話中特定使用者的所有請求都會送到池中相同的後端。 API 管理會將會話標識碼 Cookie 設定為維護會話狀態。 例如，在具有 AI 聊天助理或其他交談代理程式等後端的案例中，此選項很有用，可將來自相同會話的要求路由傳送至相同的端點。

附註

負載平衡集區中的工作階段感知會先被發佈給 AI 閘道早期更新群組。

管理用於辨識會話狀態的 Cookie

當您使用會話感知時，客戶端必須妥善處理 cookie。 客戶端必須儲存 Set-Cookie 標頭值，並且在後續要求中發送它來維護會話狀態。

您可以使用 API 管理策略來幫助設定用於會話感知的 Cookie。 例如，以 Assistants 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，並將 backend-2 的權數設定為 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" 
        } 
      } 
    }
  }
}

限制

• 對於開發人員和進階層，當閘道端點 URL 與後端 URL 相同時，內部虛擬網路中部署的 API 管理執行個體會擲出 HTTP 500 BackendConnectionFailure 錯誤。 如果發生此限制，請遵循 Tech Community 部落格中內部虛擬網路模式中自我鏈結 API 管理要求限制一文中的指示。
• 目前，後端斷路器只能設定一條規則。

相關內容

• 部落格：搭配 Azure OpenAI 服務使用 Azure API 管理斷路器和負載平衡
• 使用 Azure 入口網站來設定 Service Fabric 後端。
• 快速入門：在 Azure API 管理中使用 Bicep 建立後端集區，以對 OpenAI 要求進行負載平衡
• 請參閱作為事件方格來源的 Azure API 管理 (部分機器翻譯)，以了解當斷路器跳脫或重設時，閘道所產生的事件方格事件相關資訊。 使用這些事件以在後端問題惡化之前採取動作。