API 管理中的後端

2025-05-29

適用於：所有 APIM 階層

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

匯入特定 API 時，API 管理會自動設定 API 後端。例如，API 管理在匯入時設定後端 Web 服務：

OpenAPI 規格。
SOAP API。
Azure 資源，例如 Azure OpenAI API、HTTP 觸發的 Azure 函式應用程式或邏輯應用程式。

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

Service Fabric 叢集。
自訂服務。

後端的優點

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

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

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

設定和管理 Azure 入口網站中的後端實體，或使用 Azure API 或工具。

建立後端

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

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

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

建立後端之後，您可以隨時更新後端設定。例如，新增斷路器規則、變更運行時間 URL 或新增授權認證。

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

您可以使用 API 管理實例中設定的系統指派或使用者指派的受控識別，來授權存取後端服務。若要設定授權認證的受控識別，請執行下列動作：

在後端組態的 [ 授權認證 ] 區段中，選取 [ 受控識別] 索引卷 標，然後選取 [ 啟用]。
在 [用戶端身分識別] 中，選取 [系統指派 的身分識別] 或實例中設定的使用者指派身分識別。
在 [資源標識符] 中，輸入代表後端的目標 Azure 服務或您自己Microsoft Entra 應用程式的應用程式識別符。範例： https://cognitiveservices.azure.com 適用於 Azure OpenAI 服務。

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

注意

同時將適當的權限或 RBAC 角色指派給受控身分，以存取後端服務。例如，如果後端是 Azure OpenAI 服務，您可以指派角色的 Cognitive Services User 受控識別。

使用 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/>

斷路器

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

斷路器屬性會定義規則來中斷斷路器，例如定義時間間隔期間失敗狀況的數目或百分比，以及指出失敗的狀態代碼範圍。
斷路器跳脫時，API 管理會在定義的時間內停止將要求傳送至後端服務，並將 503 服務無法使用的回應傳回給用戶端。
設定的跳脫持續時間之後，線路會重設，流量會繼續傳到後端。

後端斷路器是斷路器模式的實作，可讓後端從多載情況復原。其可增強一般速率限制和並行限制原則，您可以實作這些原則來保護 API 管理閘道和後端服務。

注意

目前，API 管理的取用層不支援後端斷路器。
由於 API 管理架構的分散式本質，斷路器跳脫規則大致近似。網路閘道的不同執行個體不會同步處理，而且會根據相同執行個體上的資訊套用斷路器規則。
目前，後端斷路器只能設定一個規則。

範例

使用 Azure 入口網站、API 管理 REST API 或 Bicep 或 ARM 範本，在後端設定斷路器。在下列範例中，當有三個以上的狀態碼指出伺服器在 1 小時內發生錯誤時，在 APIM 執行個體 myAPIM 的 5xx 中的斷路器會跳掉。

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

在 Azure 入口網站中，移至您的 API 管理實例。
在左側功能表中，選取 [ API>後端> ] 您的後端。
在後端頁面中，選取 [ 設定>斷路器設定>] [新增]。
在 [ 建立新的斷路器] 頁面中，設定規則：
- 規則名稱：輸入規則的名稱，例如 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 範本中包含類似下面的 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 實作多個後端，並跨這些後端平衡負載要求時，APIM 會支援後端集區。集區是一些後端伺服器的集合，被用作負載平衡時視為單一實體。

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

將負載分散到多個後端，這可能會有個別的後端斷路器。
將負載從一組後端轉移到另一組後端以進行升級 (藍綠部署)。

注意

您可以在集區中包含最多 30 個後端。
由於 API 管理架構的分散式本質，後端負載平衡大致近似。網路閘道的不同執行個體不會同步處理，而且會根據相同執行個體上的資訊進行負載平衡。

負載平衡選項

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

負載平衡選項	說明
循環輪替	根據預設，請求會被平均分配到集區中的後端。
加權	權重會分配給集區中的後端，請求會根據每個後端的相對權重來進行分配。適用於藍綠部署等案例。
優先順序型	後端系統被組織成優先級群組。要求會先傳送至優先等級較高的群組；群組內的要求會平均分配，或根據指派的權重來分配。

注意

只有在高優先順序群組中的所有後端無法使用時，才會使用較低優先順序群組中的後端，因為斷路器規則已中斷。

會話意識

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

注意

負載平衡集區中的會話感知功能會首先釋出到 AI 閘道早期更新群組。

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

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

您可以使用 API 管理策略來幫助設定用於會話感知的 Cookie。例如，針對 Assistants API 案例（Azure AI Foundry Models 中的 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。

在 Azure 入口網站中，移至您的 API 管理實例。
在左側功能表中，選取 [ API>後端> ] 您的後端。
在 [後端] 頁面中，選取 [負載平衡器] 標籤。
選取 + 建立新集區。
在 [ 建立新的負載平衡集區 ] 頁面中，執行下列動作：
- 名稱：輸入集區的名稱，例如 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 範本中包含類似下列的 JSON 代碼段。將後端資源的type屬性設為Pool，並在集區中指定後端資源。