次の方法で共有


Websocket API のインポート

適用対象: 開発者 | Basic | Basic v2 | Standard | Standard v2 | Premium

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

Note

現在、この機能はワークスペースでは使用できません。

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

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

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

前提条件

WebSocket パススルー

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

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

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

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

Note

クライアント側とバックエンド側の接続は、一対一のマッピングで構成されます。

onHandshake 操作

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

onHandshake 画面の例

WebSocket API の追加

    1. Azure portal で、API Management インスタンスに移動します。
  1. 左側のメニューで、[API]>[+ API の追加] を選択します。

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

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

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

WebSocket API をテストする

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

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

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

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

    API テストの例

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

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

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

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

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

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

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

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

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

  • Azure Monitor の API メトリックを表示する
  • 必要に応じて、診断設定を有効にし、API Management のゲートウェイ ログを収集して表示します。これには、WebSocket API の操作が含まれます

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

WebSocket API 要求のクエリ ログ

制限事項

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

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

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

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

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

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

Note

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

次のステップ