上のワークフロー グラフ、および内部で説明されている詳細なワークフローが示すように、アプリ サーバーによって、メッセージがクライアントに送信されたり、Web PubSub Service によって公開された REST API を使用する接続済みクライアントが管理されたりします。 この記事では、REST API について詳しく説明します。
重要
この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。
接続文字列には、アプリケーションがAzure Web PubSubサービスにアクセスするために必要な認可情報が含まれています。 接続文字列のアクセスキーはサービスのルートパスワードのように機能します。 運用環境では、常にアクセス キーを保護してください。 Azure Key Vault を使ってキーの管理とローテーションを安全に行い、WebPubSubServiceClient を使って接続をセキュリティ保護します。
アクセス キーを他のユーザーに配布したり、ハードコーディングしたり、他のユーザーがアクセスできるプレーンテキストで保存したりしないでください。 キーが侵害された可能性があると思われる場合は、キーをローテーションしてください。
REST API の使用
リクエストパス内のグループ名とユーザーID
リクエストパスにグループ名やユーザーIDを含むREST操作には、これらの値に前斜線(/)が含まれる制限があります。
%2FとしてスラッシュをURLエンコードしても制限は解決しないかもしれません。つまり、操作が意図したグループやユーザーをアドレスできない可能性があります。 例えば、ユーザーID tenant/alice に接続されたクライアントが、 /users/tenant%2Faliceを含むパスを持つRESTリクエストでは見つからない場合があります。
この制限は、メッセージの送信、グループやユーザーの存在確認、接続の閉鎖、グループメンバーシップの管理など、これらのパスパラメータを使用する操作に適用されます。 これらのRESTエンドポイントを呼び出すサーバーSDKメソッドも同様の制限を受けます。 これはREST リクエストパスの制限であり、Web PubSubのグループ名やユーザーIDに / を一般的に禁止するものではありません。
制限を避けるために、アプリケーションがこれらのREST操作を必要とする場合は / せずにグループ名とユーザーIDを使いましょう。 アプリケーションの識別子に /が含まれている場合は、それらを一意でスラッシュフリーの識別子にマッピングし、クライアントアクセストークン、グループメンバーシップ、RESTコールでその割り当て値を一貫して使用してください。 RESTリクエストの値だけを変更しても、既存の接続に関連付けられたユーザーIDやグループ名は変わりません。
Note
送信操作からの 202 Accepted 応答は、そのリクエストが処理のために受け入れられたことを示します。 目的のユーザーやグループへの配達を確認しません。
Azure Web PubSub Service AccessKey を使用した認証
各 HTTP 要求での Azure Web PubSub Service を使用した認証には、JSON Web トークン (JWT) を含む Authorization ヘッダーが必要です。
署名アルゴリズムとシグネチャ
HS256 (HMAC-SHA256) は署名アルゴリズムとして使用されます。
生成されたJWTに署名するには、サービスインスタンスの接続文字列 Azure Web PubSubAccessKeyを使うべきです。
要求
以下の請求項はJWTに含める必要があります。
| 要求の種類 | 必須 | 説明 |
|---|---|---|
aud |
true | HTTP 要求の URL と同じにする必要があります。 たとえば、ブロードキャスト要求の対象ユーザーは、https://example.webpubsub.azure.com/api/hubs/myhub/:send?api-version=2022-11-01 のようになります。 |
exp |
true | このトークンの有効期限が切れるエポック時間。 |
JS の擬似コード:
この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。 運用環境では、常にアクセス キーを保護してください。 Azure Key Vault を使ってキーの管理とローテーションを安全に行い、WebPubSubServiceClient を使って接続をセキュリティ保護します。
const bearerToken = jwt.sign({}, connectionString.accessKey, {
audience: request.url,
expiresIn: "1h",
algorithm: "HS256",
});
Microsoft Entra トークンによって認証する
AccessKey を使用する場合と同様に、HTTP 要求の認証には、JSON Web トークン (JWT) も必要です。
このシナリオでは、JWTはMicrosoft Entra IDによって生成されます。
Microsoft Entra トークンの生成方法を確認する
使用する資格情報スコープは https://webpubsub.azure.com/.default にする必要があります。
また、ロールベースのアクセス制御 (RBAC) を使用して、自分のサーバーから Azure Web PubSub Service への要求を承認することもできます。
API
| 操作グループ | 説明 |
|---|---|
| サービスの状態 | サービスの状態を確認する操作を行います |
| REST 操作 | 接続を管理して、それにメッセージを送信する操作を行います。 |