API Management のバックエンド

2025-06-09

適用対象: すべての API Management レベル

API Management の "バックエンド" (つまり "API バックエンド") は、フロントエンド API とその操作を実装する HTTP サービスです。

特定の API をインポートすると、API Management によって API バックエンドが自動的に構成されます。たとえば、以下をインポートするときに、API Management によってバックエンド Web サービスが構成されます。

OpenAPI の仕様。
SOAP API。
Azure OpenAI API、HTTP によってトリガーされる Azure Function App、ロジックアプリなどの Azure リソース。

API Management が API バックエンドとしての使用をサポートする Azure リソースは他にもあります。その例を次に示します。

Service Fabric クラスター。
カスタムサービス。

バックエンドの利点

API Management ではバックエンドエンティティがサポートされているため、API のバックエンドサービスを管理できます。バックエンドエンティティは、バックエンドサービスに関する情報をカプセル化し、API 間での再利用性を促進し、ガバナンスを強化します。

次の 1 つ以上のバックエンドを使用します。

バックエンドサービスへの要求の資格情報を承認する
ヘッダーまたはクエリパラメーターの認証用に名前付きの値が構成されている場合に、API Management の機能を利用して Azure Key Vault でシークレットを維持できます。
サーキットブレーカールールを定義し、バックエンドを過剰な要求から保護します。
複数のバックエンドへのルート要求または負荷分散要求

バックエンドエンティティの構成と管理は、Azure portal で、または Azure API やツールを使用して行います。

バックエンドを作成する

バックエンドは、Azure portal で作成することも、Azure API またはツールを使用して作成することもできます。

ポータルでバックエンドを作成するには:

ポータルにサインインし、API Management インスタンスに移動します。
左側のメニューで、 API>Backends>+ 新しいバックエンドの作成を選択します。
[ バックエンド ] ページで、次の操作を行います。
1. バックエンドの名前と オプションの説明を入力します。
2. バックエンドホスティングの種類 (たとえば、関数アプリやロジックアプリなどの Azure リソースの Azure リソース、カスタムサービスのカスタム URL、Service Fabric クラスターなど) を選択します。
3. [ランタイム URL] に、API 要求の転送先となるバックエンドサービスの URL を入力します。
4. [ 詳細設定] で、必要に応じてバックエンドの証明書チェーンまたは証明書名の検証を無効にします。
5. [ このバックエンドサービスをバックエンドプールに追加する] で、必要に応じてバックエンドの負荷分散プールを選択または作成します。
6. [ サーキットブレーカー規則] で、必要に応じてバックエンドのサーキットブレーカーを構成します。
7. [ 承認資格情報] で、必要に応じて、バックエンドへのアクセスを承認するように資格情報を構成します。オプションには、要求ヘッダー、クエリパラメーター、クライアント証明書、または API Management インスタンスで構成されたシステム割り当てマネージド ID またはユーザー割り当てマネージド ID が含まれます。
8. を選択してを作成します。

バックエンドを作成したら、いつでもバックエンド設定を更新できます。たとえば、サーキットブレーカー規則を追加したり、ランタイム URL を変更したり、承認資格情報を追加したりします。

承認資格情報のマネージド ID を構成する

API Management インスタンスで構成されたシステム割り当てマネージド ID またはユーザー割り当てマネージド ID を使用して、バックエンドサービスへのアクセスを承認できます。承認資格情報のマネージド ID を構成するには、次の操作を行います。

バックエンド構成の [承認資格情報 ] セクションで、[ マネージド ID ] タブを選択し、[ 有効] を選択します。
[クライアント ID] で、インスタンスで構成されているシステム割り当て ID またはユーザー割り当て ID のいずれかを選択します。
リソース ID に、ターゲットの Azure サービスまたはバックエンドを表す独自の Microsoft Entra アプリケーションのアプリケーション ID を入力します。例: Azure OpenAI サービスの https://cognitiveservices.azure.com 。

その他の例については、認証マネージド ID ポリシーのリファレンスを参照してください。
を選択してを作成します。

注記

また、バックエンドサービスにアクセスするための適切なアクセス許可または RBAC ロールをマネージド ID に割り当てます。たとえば、バックエンドが Azure OpenAI サービスである場合は、マネージド ID に 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 Management インスタンスでは、バックエンドサービス名が 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 Management ではバックエンドリソースのサーキットブレーカープロパティが公開されており、多すぎる要求でバックエンドサービスが過負荷になるのを防ぐことができます。

サーキットブレーカープロパティを使って、サーキットブレーカーをトリップするルールを定義します。たとえば、定義した期間中の障害状態の数や割合、障害を示す状態コードの範囲などです。
サーキットブレーカーがトリップすると、API Management により、定義された期間バックエンドサービスへの要求の送信が停止され、クライアントに 503 サービス利用不可応答が返されます。
構成されたトリップ期間が経過すると、サーキットはリセットされ、バックエンドに対してトラフィックが再開されます。

バックエンドのサーキットブレーカーは、バックエンドが過負荷状態から復旧できるようにするためのサーキットブレーカーパターンの実装です。これにより、API Management ゲートウェイとバックエンドサービスを保護するために実装できる一般的なレート制限ポリシーとコンカレンシー制限ポリシーが強化されます。

注記

現時点では、バックエンドサーキットブレーカーは API Management の従量課金レベルではサポートされていません。
API Management アーキテクチャは分散型性質を持つため、サーキットブレーカーのトリップルールはおおよそのものです。ゲートウェイの異なるインスタンスは同期せず、同じインスタンスの情報に基づいてサーキットブレーカールールを適用します。
現在、バックエンドサーキットブレーカーに構成できるルールは 1 つだけです。

例

Azure portal、API Management REST API、または Bicep または ARM テンプレートを使用して、バックエンドでサーキットブレーカーを構成します。次の例では、1 時間にサーバーエラーを示す状態コードが 3 つ以上ある場合に API Management インスタンス myAPIM の 5xx でサーキットブレーカーがトリップします。

この例のサーキットブレーカーは、1 時間後にリセットされます。応答に Retry-After ヘッダーが存在する場合、サーキットブレーカーは値を受け入れ、指定された時間待機してからバックエンドに要求を再度送信します。

Azure portal で、API Management インスタンスに移動します。
左側のメニューで、[API]>[バックエンド]> を選択し、バックエンドを選択します。
バックエンドページで、設定>Circuit ブレーカーの設定>新規追加を選択します。
[ 新しいサーキットブレーカーの作成 ] ページで、次の規則を構成します。
- ルール名: 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 テンプレートに次のような 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 Management ではバックエンド "プール" がサポートされます。プールは、負荷分散のための単一のエンティティとして扱われるバックエンドのコレクションです。

バックエンドプールは、次のような場合に使用します。

個々のバックエンドのサーキットブレーカーを持つことができる複数のバックエンドに負荷を分散させます。
アップグレードのために、あるバックエンドのセットから別のバックエンドに負荷をシフトします (ブルーグリーンデプロイ)。

注記

プールには最大 30 個のバックエンドを含めることができます。
API Management アーキテクチャは分散型の性質を持つため、バックエンドの負荷分散はおおよそのものです。ゲートウェイの異なるインスタンスは同期せず、同じインスタンスの情報に基づいて負荷分散を適用します。

負荷分散のオプション

API Management では、バックエンドプールに対して次の負荷分散オプションがサポートされています。

負荷分散オプション	説明
ラウンドロビン	要求は、既定でプール内のバックエンド間で均等に分散されます。
重み付けの	重みはプール内のバックエンドに割り当てられ、要求は各バックエンドの相対的な重みに基づいて分散されます。ブルーグリーンデプロイなどのシナリオに役立ちます。
優先度ベース	バックエンドは優先度グループに編成されます。要求は、優先順位の高いグループに最初に送信されます。グループ内では、要求は均等に、または割り当てられた重みに従って分散されます。

注記

サーキットブレーカールールがトリップされているため、優先度の高いグループ内のすべてのバックエンドが使用できない場合にのみ、優先度の低いグループのバックエンドが使用されます。

セッションの認識

上記のいずれかの負荷分散オプションを使用して、必要に応じて セッション認識 (セッションアフィニティ) を有効にして、セッション中に特定のユーザーからのすべての要求がプール内の同じバックエンドに送信されるようにします。 API Management は、セッション状態を維持するためにセッション ID Cookie を設定します。このオプションは、たとえば、AI チャットアシスタントや他の会話エージェントなどのバックエンドを使用して、同じセッションからの要求を同じエンドポイントにルーティングするシナリオで役立ちます。

注記

負荷分散されたプールでのセッション認識は、まず AI Gateway 早期更新グループにリリースされています。

セッション認識のための Cookie の管理

セッション認識を使用する場合、クライアントは Cookie を適切に処理する必要があります。クライアントは、 Set-Cookie ヘッダー値を格納し、セッション状態を維持するために後続の要求と共に送信する必要があります。

API Management ポリシーを使用して、セッション認識用の 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 Management REST API、または Bicep または ARM テンプレートを使用して、バックエンドプールを構成します。次の例では、API Management インスタンス myAPIM のバックエンド myBackendPool がバックエンドプールで構成されています。プール内のバックエンドの例は、backend-1 と backend-2 という名前が付けられています。両方のバックエンドが最も優先度の高いグループに含まれています。グループ内では、 backend-1 の方が backend-2 よりも重みが大きくなります。

Azure portal で、API Management インスタンスに移動します。
左側のメニューで、[API]>[バックエンド]> を選択し、バックエンドを選択します。
[バックエンド] ページで、[ ロードバランサー ] タブを選択します。
[ + 新しいプールの作成] を選択します。
[ 新しい負荷分散プールの作成 ] ページで、次の操作を行います。
- 名前: myBackendPool などのプールの名前を入力します。
- 説明: 必要に応じて説明を入力します。
- プールにバックエンドを追加する: プールに追加するバックエンドを 1 つ以上選択します。
- バックエンドの重みと優先順位: プール内の各バックエンドの重みと優先度を構成するには、[ 重みと優先度のカスタマイズ ] を選択します。たとえば、backend-1 と backend-2 という名前の 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 に設定し、プール内のバックエンドを指定します。

{
  "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" 
        } 
      } 
    }
  }
}

制限事項

Developer レベルと Premium レベルの場合、ゲートウェイのエンドポイントの URL とバックエンドの URL が同じであるときに、内部仮想ネットワークにデプロイされた API Management インスタンスから HTTP 500 BackendConnectionFailure エラーがスローされることがあります。この制限に遭遇した場合は、テクニカルコミュニティブログの内部仮想ネットワークモードにおける自己連鎖 API Management 要求の制限に関する記事の手順に従ってください。
現在、バックエンドサーキットブレーカーに構成できるルールは 1 つだけです。

ブログ: Azure OpenAI Service での Azure API Management のサーキットブレーカーと負荷分散の使用
Azure portal を使用して Service Fabric バックエンドを設定します。
クイックスタート: OpenAI 要求の負荷分散に Bicep を使用して Azure API Management にバックエンドプールを作成する
サーキットブレーカーがトリップまたはリセットされたときにゲートウェイによって生成される Event Grid イベントに関する情報については「Event Grid ソースとしての Azure API Management」を参照してください。バックエンドの問題がエスカレートする前に、これらのイベントを使用してアクションを実行します。