Azure SignalR Service データ プレーン REST API リファレンス
従来のクライアント/サーバー パターンに加えて、Azure SignalR Service には、リアルタイム機能をサーバーレス アーキテクチャに統合するのに役立つ一連の REST API が用意されています。
Note
Azure SignalR Service で REST API を通じてサポートされるのは、ASP.NET Core SignalR を使用して接続されたクライアントを管理する場合のみです。 ASP.NET SignalR 経由で接続されたクライアントでは、現在サポートされていない別のデータ プロトコルを使用します。
Azure Functions を使用した一般的なサーバーレス アーキテクチャ
次の図は、Azure Functions で Azure SignalR Service を使用する一般的なサーバーレス アーキテクチャを示しています。
negotiate関数では、ネゴシエーション応答を返し、すべてのクライアントを Azure SignalR Service にリダイレクトします。broadcast関数は、Azure SignalR Service の REST API を呼び出します。 Azure SignalR Service では、接続されているすべてのクライアントにメッセージをブロードキャストします。
サーバーレス アーキテクチャでも、クライアントには Azure SignalR Service への永続的な接続が保持されます。 トラフィックを処理するアプリケーション サーバーがないため、クライアントは LISTEN モードになります。 そのモードでは、クライアントはメッセージを受信できるが、メッセージを送信することはできません。 Azure SignalR Service では、メッセージを送信するクライアントはすべて切断します。それが無効な操作であるためです。
Azure Functions で Azure SignalR Service を使用する場合の詳細なサンプルについては、この GitHub リポジトリを参照してください。
ネゴシエーション エンドポイントの実装
クライアントがサービスに接続できるようにするリダイレクト ネゴシエーション応答を返す negotiate 関数を実装する必要があります。
一般的なネゴシエーション応答は次の形式をとります。
{
"url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
"accessToken": "<a typical JWT token>"
}
認証のセクションで説明されているものと同じアルゴリズムを通じて accessToken 値が生成されます。 唯一の違いは、aud クレームが url と同じでなければならない点です。
SignalR クライアントを使用して引き続きハブ URL に接続できるように、https://<hub_url>/negotiate で negotiate API をホストする必要があります。 クライアントを Azure SignalR Service にリダイレクトする方法の詳細については、「クライアント接続」を参照してください。
REST API のバージョン
サポートされている REST API バージョンを次の表に示します。 また、各 API バージョンの Swagger ファイルも提供されます。
| API バージョン | Status | Port | ドキュメント | 仕様 |
|---|---|---|---|---|
20220601 |
最も遅い | Standard | 記事 | Swagger ファイル |
1.0 |
安定 | Standard | 記事 | Swagger ファイル |
1.0-preview |
廃止 | Standard | 記事 | Swagger ファイル |
次の表は使用できる API の一覧です。
| API | パス |
|---|---|
| ターゲット ハブに接続されているすべてのクライアントにメッセージをブロードキャストする | POST /api/v1/hubs/{hub} |
| ターゲット ユーザーに属するすべてのクライアントにメッセージをブロードキャストする | POST /api/v1/hubs/{hub}/users/{id} |
| 特定の接続にメッセージを送信する | POST /api/v1/hubs/{hub}/connections/{connectionId} |
| 指定された connectionId との接続が存在するかどうかを確認します | GET /api/v1/hubs/{hub}/connections/{connectionId} |
| クライアント接続を閉じます | DELETE /api/v1/hubs/{hub}/connections/{connectionId} |
| ターゲット グループ内のすべてのクライアントにメッセージをブロードキャストする | POST /api/v1/hubs/{hub}/groups/{group} |
| 特定のグループ内にクライアント接続があるかどうかを確認します | GET /api/v1/hubs/{hub}/groups/{group} |
| 特定のユーザーに接続されているクライアント接続があるかどうかを確認します | GET /api/v1/hubs/{hub}/users/{user} |
| ターゲット グループに接続を追加する | PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId} |
| ターゲット グループから接続を削除する | DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId} |
| ユーザーがターゲット グループに存在するかどうかを確認する | GET /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| ターゲット グループにユーザーを追加する | PUT /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| ターゲット グループからユーザーを削除する | DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| ユーザーをすべてのグループから削除する | DELETE /api/v1/hubs/{hub}/users/{user}/groups |
REST API を使用して
Azure SignalR Service で AccessKey を使用した認証
各 HTTP 要求での Azure SignalR Service を使用した認証には、JSON Web Token (JWT) を含む Authorization ヘッダーが必要です。
署名アルゴリズムとシグネチャ
HS256 (HMAC-SHA256) は署名アルゴリズムとして使用されます。
Azure SignalR Service インスタンスの接続文字列内の AccessKey 値を使用して、生成された JWT に署名します。
要求
次の要求は、JWT に含める必要があります。
| 要求の種類 | 必須 | 説明 |
|---|---|---|
aud |
true |
HTTP 要求 URL、末尾のスラッシュ、クエリ パラメーターが含まれていない場合と同じにする必要があります。 たとえば、ブロードキャスト要求の対象ユーザーは、https://example.service.signalr.net/api/v1/hubs/myhub のようになります。 |
exp |
true |
このトークンの有効期限が切れるエポック時間。 |
Microsoft Entra トークンを使用した認証
AccessKey を使用した認証と同様に、Microsoft Entra トークンを使用して HTTP 要求を認証するには JWT が必要です。
このシナリオでは、Microsoft Entra ID で JWT を生成する点が異なります。 詳細については、「Microsoft Entra トークンの生成方法」を参照してください。
また、ロールベースのアクセス制御 (RBAC) を使用して、自分のクライアントまたはサーバーから Azure SignalR Service への要求を承認することもできます。 詳細については、「Azure SignalR Service に Microsoft Entra ID を使用してアクセスを承認する」を参照してください。
ユーザー関連の REST API
ユーザー関連の REST API を呼び出すには、各クライアントが Azure SignalR Service に対して自らを識別する必要があります。 そうでないと、Azure SignalR Service では、ユーザー ID からのターゲット接続を見つけることができません。
各クライアントが Azure SignalR Service に接続するときに JWT に nameid クレームを含めることで、クライアントを識別できます。 それにより、Azure SignalR Service では nameid クレームの値を各クライアント接続のユーザー ID として使用します。
サンプル
この GitHub リポジトリでは、Azure SignalR Service で REST API HTTP 要求を手動でビルドする方法を示す完全なコンソール アプリを見つけることができます。
また、Microsoft.Azure.SignalR.Management を使用すると、IHubContext の同様のインターフェイスを使用してメッセージを Azure SignalR Service に発行することもできます。 サンプルはこの GitHub リポジトリにあります。 詳細については、「Azure SignalR サービス管理 SDK」を参照してください。
制限事項
現在、REST API 要求には次の制限があります。
- ヘッダー サイズは最大 16 KB です。
- 本文のサイズは最大 1 MB です。
1 MB を超えるメッセージを送信する場合は、persistent モードでサービス管理 SDK を使用します。