Azure Web PubSub サービス データ プレーン REST API リファレンス

Web PubSub サービス ワークフローを示す図。

上のワークフロー グラフ、および内部で説明されている詳細なワークフローが示すように、アプリ サーバーによって、メッセージがクライアントに送信されたり、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 操作 接続を管理して、それにメッセージを送信する操作を行います。