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 の制限事項について説明します。

前提条件

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

WebSocket パススルー

API Management により 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 ポリシーをそれらに適用できます。

WebSocket API の追加

ポータル

1. 1. Azure portal で、API Management インスタンスに移動します。

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

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

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

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

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

WebSocket API をテストする

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

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

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

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

   

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 プロトコルへの要求の切り替えが正常に行われたことが示されています。

制限事項

以下に示すのは、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 のインポートの制限事項
• OpenAPI 仕様のインポート
• SOAP API のインポート
• SOAP API のインポートと REST への変換
• App Service API をインポートする
• コンテナー アプリ API をインポートする
• Websocket API のインポート
• GraphQL API のインポート
• GraphQL スキーマをインポートし、フィールド リゾルバーを設定する
• Azure 関数アプリをインポートする
• Azure ロジック アプリをインポートする
• Service Fabric サービスをインポートする
• Azure OpenAI API をインポートする
• OData API をインポートする
• SAP OData メタデータをインポートする
• gRPC API をインポートする
• API の編集

次のステップ

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