Websocket API のインポート

[アーティクル]
06/01/2023

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

JWT 検証など、既存のアクセス制御ポリシーを適用することで、WebSocket API をセキュリティで保護できます。 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

WebSocket パススルー

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

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

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

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

Note

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

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] を選択します。

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

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

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

WebSocket API をテストする

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

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

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 に継承された場合、実行時にスキップされます。

次のステップ

公開された API の変換と保護