次の方法で共有

Websocket API のインポート

適用対象: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

API Management の WebSocket API ソリューションを使用すると、API パブリッシャーは、Azure ポータル、Azure CLI、Azure PowerShell、その他のAzure ツールを使用して、API Management に WebSocket API をすばやく追加できます。

WebSocket API は、API Management のアクセスの制御ポリシーを初期ハンドシェイク操作に適用することで保護できます。 また、Azure ポータルと開発者ポータルの両方で、API テスト コンソールを使用して WebSocket API をテストすることもできます。 既存の監視機能を基に構築された API Management により、WebSocket API の監視とトラブルシューティングを行うメトリックとログが得られます。

この記事では、次のことについて説明します。

  • WebSocket パススルー フローについて説明します。
  • API Management インスタンスに WebSocket API を追加します。
  • WebSocket API をテストします。
  • WebSocket API のメトリックとログを表示します。
  • WebSocket API の制限事項について説明します。

前提条件

  • 既存の API Management インスタンスがある。 まだない場合は、作成してください。
  • WebSocket API。
  • Azure CLI

WebSocket パススルー

API Management により WebSocket パススルーがサポートされています。

WebSocket パススルー フローの視覚的な図

WebSocket パススルー中、クライアント アプリケーションは API Management ゲートウェイとの WebSocket 接続を確立し、対応するバックエンド サービスとの接続を確立します。 次に API Management で、WebSocket クライアントとサーバーのメッセージがプロキシ処理されます。

  1. クライアント アプリケーションにより WebSocket ハンドシェイク要求がゲートウェイに送信され、onHandshake 操作が呼び出されます
  2. API Management ゲートウェイにより、構成済みのポリシーが適用され、WebSocket ハンドシェイク要求が対応するバックエンド サービスに送信されます。
  3. バックエンド サービスで、WebSocket への接続がアップグレードされます。
  4. ゲートウェイで、対応する WebSocket への接続がアップグレードされます。
  5. 接続のペアが確立されると、API Management によりクライアント アプリケーションとバックエンド サービスの間でメッセージが仲介されます。
  6. クライアント アプリケーションで、ゲートウェイにメッセージが送信されます。
  7. ゲートウェイで、メッセージがバックエンド サービスに転送されます。
  8. バックエンド サービスで、ゲートウェイにメッセージが送信されます。
  9. ゲートウェイで、メッセージがクライアント アプリケーションに転送されます。
  10. どちらかのサイドが切断されると、API Management により対応する接続が終了されます。

注

クライアントとバックエンドの接続は、1 対 1 のマッピングで構成されます。 同じ WebSocket セッションを複数のバックエンドに分散することはできません。

onHandshake 操作

WebSocket プロトコルごとに、クライアント アプリケーションでバックエンド サービスとの WebSocket 接続の確立が試行されると、最初に、オープニング ハンドシェイク要求が送信されます。 API Management 内の各 WebSocket API には、onHandshake 操作があります。 onHandshake は、変更不可で解除できない、自動的に作成されるシステム操作です。 onHandshake 操作を使用すると、API パブリッシャーでこれらのハンドシェイク要求がインターセプトされ、API Management ポリシーをそれらに適用できます。

onHandshake 画面の例

WebSocket API の追加

  • ポータル
    1. Azure ポータルで、API Management インスタンスに移動します。

  2. 左側のメニューで、[API][+ API の追加] を選択します。

  3. [Define a new API] (新しい API の定義) で、[WebSocket] を選択します。

  4. ダイアログ ボックスで [完全] を選択し、必要なフォーム フィールドを入力します。

    フィールド 説明
    [表示名] WebSocket API を表示するときに使用する名前。
    名前 WebSocket API の未加工の名前。 表示名を入力すると自動的に設定されます。
    WebSocket URL Websocket 名のベース URL。 例: ws://example.com/your-socket-name
    URL スキーム 既定値を受け入れます
    API URL サフィックス この API Management インスタンスでこの特定の API を識別するための URL サフィックスを追加します。 この API Management インスタンス内で一意である必要があります。
    製品 WebSocket API を製品に関連付け、発行します。
    ゲートウェイ WebSocket API を既存のゲートウェイに関連付けます。

  5. Create をクリックしてください。

WebSocket API をテストする

  1. ご自身の WebSocket API に移動します。

  2. WebSocket API 内で、onHandshake 操作を選択します。

  3. [テスト] タブを選択して、テスト コンソールにアクセスします。

  4. 必要に応じて、WebSocket ハンドシェイクに必要なクエリ文字列パラメーターを指定します。

    API テストの例

  5. [Connect]をクリックします。

  6. [出力] に接続状態を表示します。

  7. [ペイロード] に値を入力します。

  8. [ 送信] をクリックします。

  9. [出力] に受信メッセージを表示します。

  10. 前の手順を繰り返して、さまざまなペイロードをテストします。

  11. テストが完了したら、[切断] を選択します。

メトリックとログを表示する

標準の API Management と Azure Monitor 機能を使用して、WebSocket API を監視します。

  • Azure Monitorで API メトリックを表示する
  • 必要に応じて、診断設定を有効にして、WebSocket API 操作や WebSocket 接続ログを含む API Management ゲートウェイ ログを収集して表示します

たとえば、次のスクリーンショットは、 テーブルからのコード が含まれる最近の WebSocket API の応答を示したものです。 これらの結果では、TCP から WebSocket プロトコルへの要求の切り替えが正常に行われたことが示されています。

WebSocket API 要求のクエリ ログ

制限事項

次に示すのは、API Management での WebSocket サポートの現在の制限です。

  • WebSocket API は、従量課金レベルではまだサポートされていません。
  • WebSocket API では、メッセージに対して有効なバッファーの種類として Close、BinaryFragment、BinaryMessage、UTF8Fragment、UTF8Message がサポートされています。
  • 現時点、set ヘッダー ポリシーは、onHandshake 要求での ヘッダーを含む特定の既知のヘッダーの変更をサポートしていません。
  • WebSocket バックエンドとの TLS ハンドシェイク中に、サーバー証明書が信頼されていること、およびそのサブジェクト名がホスト名と一致していることが、API Management によって検証されます。 HTTP API では、API Management によって、証明書が信頼されていることは検証されますが、そのホスト名とサブジェクトが一致していることは検証されません。
  • WebSocket 接続を複数のバックエンドに分散または負荷分散することはできません。これは、確立されると、各接続がクライアントとバックエンドの間で 1 対 1 で維持されるためです。

WebSocket 接続の制限については、API Management の制限に関するページを参照してください。

サポートされていないポリシー

次のポリシーは onHandshake 操作でサポートされておらず、適用することはできません。

  • モック応答
  • キャッシュから取得
  • キャッシュに格納
  • クロスドメイン呼び出しを許可
  • CORS
  • JSONP
  • 要求メソッドを設定
  • 本文を設定
  • XML から JSON への変換
  • JSON から XML への変換
  • XSLT を使用した XML の変換
  • コンテンツの検証
  • パラメーターを検証する:
  • ヘッダーを検証する
  • 状態コードを検証する

注

より高いスコープ (グローバルまたは製品など) でポリシーを適用し、それらがポリシーを介して WebSocket API に継承された場合、実行時にスキップされます。

関連コンテンツ

  • API のインポートの制限事項
  • OpenAPI 仕様のインポート
  • SOAP API のインポート
  • SOAP API をインポートして REST に変換する
  • App Service API をインポートする
  • コンテナー アプリ API をインポートする
  • WebSocket API をインポートする
  • GraphQL API をインポートする
  • GraphQL スキーマをインポートし、フィールド リゾルバーを設定する
  • 関数アプリ API をインポートする
  • ロジック アプリ API をインポートする
  • Service Fabric サービスをインポートする
  • Microsoft Foundry API をインポートする
  • Azure OpenAI API
  • LLM API をインポートする
  • OData API をインポートする
  • REST API を MCP サーバーとしてエクスポートする
  • 既存の MCP サーバーを公開する
  • A2A エージェント API をインポートする
  • SAP OData メタデータをインポートする
  • gRPC API をインポートする
  • API の編集
  • Last updated on