Websocket API のインポート

2025-05-20

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

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

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

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

前提条件

既存の API Management インスタンスがある。まだない場合は、作成してください。
WebSocket API。
Azure CLI（Azure コマンドラインインターフェイス）

WebSocket パススルー

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

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

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

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

注

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

onHandshake 操作

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

onHandshake 画面の例

WebSocket API の追加

ポータル

1. Azure portal で、API Management インスタンスに移動します。
左側のメニューで、[API]>[+ API の追加] を選択します。
[Define a new API] (新しい API の定義) で、[WebSocket] を選択します。

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

フィールド	説明
表示名	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 を既存のゲートウェイに関連付けます。

[作成] をクリックします。

WebSocket API をテストする

ご自身の WebSocket API に移動します。
WebSocket API 内で、onHandshake 操作を選択します。
[テスト] タブを選択して、テストコンソールにアクセスします。
必要に応じて、WebSocket ハンドシェイクに必要なクエリ文字列パラメーターを指定します。
[接続] をクリックします。
[出力] に接続状態を表示します。
[ペイロード] に値を入力します。
[送信] をクリックします。
[出力] に受信メッセージを表示します。
前の手順を繰り返して、さまざまなペイロードをテストします。
テストが完了したら、 [切断] を選択します。

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

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

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

たとえば、次のスクリーンショットは、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 の変換
コンテンツの検証
パラメーターを検証する:
ヘッダーを検証する
状態コードを検証する

注

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