次の方法で共有

AMQP プロトコルを使用した Azure Web PubSub イベント リスナーの CloudEvents 拡張機能

  • [アーティクル]

Azure Web PubSub サービスは、クライアント イベントを CloudEvents として記述します。 CloudEvents は、サービス、プラットフォーム、システム間の相互運用性を提供するために、共通の形式でイベント データを記述するための仕様です。

サービスのイベント リスナーは、クライアント イベントをリッスンします。 Event Hubs は現在サポートされている唯一のイベント リスナー エンドポイントであり、そのプライマリ プロトコルは AMQP (Advanced Message Queuing Protocol) です。 Web PubSub サービスは、CloudEvents AMQP プロトコル バインディングを使用して CloudEvents を AMQP メッセージにマップします。

サービスからサーバーに送信されるデータは、常に CloudEvents binary 形式です。

Web PubSub CloudEvents の属性の拡張

この拡張機能では、Web PubSub によって生成されるすべてのイベントに使用される属性が定義されています。

次の表に、AMQP メッセージの標準プロパティ セクションに対応する属性を示します。

名前 説明 例
content-type メッセージの本文の RFC-2046 MIME の種類 application/json
message-id "{connection-id}/{an integer generated by service}" の形式で、Web PubSub サービス内のメッセージを一意に定義します。 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

次の表には、AMQP メッセージのアプリケーション プロパティ セクションに対応するすべての CloudEvents 属性が含まれています。 各属性名の先頭には cloudEvents: が付きます。

名前 説明 例
specversion クラウド イベント仕様バージョンは常に 1.0 です 1.0
source イベントの発生元のハブと接続 ID を "/hubs/{hub}/client/{connectionId}" の形式で示します。 /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id サービスによって生成された、同じクライアント接続からのイベントで一意の整数 1
awpsversion クラウド イベント Azure Web PubSub 仕様バージョンは常に 1.0 です 1.0
hub イベントの発生元のハブ名 chat
eventname イベントの名前 connected
type イベントの種類 azure.webpubsub.sys.connect
connectionid クライアント接続の ID 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time サービスがイベントを送信する時刻 ("yyyy-MM-ddTHH:mm:ssZ" の形式) 2021-01-01T00:00:00Z
userid* ユーザーの ID user1
subprotocol* サブプロトコル名 json.webpubsub.azure.v1
connectionstate* 接続の状態を定義します。 イベント ハンドラーの応答ヘッダーの値をリセットできます。 接続状態の詳細については、「Web PubSub CloudEvents 属性」を参照してください。 anystring

属性名の後の "*" は、値が null または空でない場合にのみ属性が存在することを示します。

イベント

このセクションでは、AMQP メッセージ本文と、特定のクライアント イベントの種類に依存する属性値を示します。 クライアント イベントの種類に依存しない属性値は省略されます。

システム connected イベント

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.connected
  • cloudEvents:eventname: connected

メッセージ本文は常に空の JSON です。

{}

システム disconnected イベント

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.disconnected
  • cloudEvents:eventname: disconnected

メッセージ本文には、クライアントが切断された理由が含まれています。

{"reason":"{Reason}"}

シンプル WebSocket クライアントに対するユーザー イベント message

  • content-type: バイナリ フレームの場合は application/octet-stream。テキスト フレームの場合は text/plain。
  • cloudEvents:type: azure.webpubsub.user.message

メッセージ本文は、クライアントが送信する内容です。

PubSub WebSocket クライアントに対するユーザー カスタム イベント {custom_event}

  • content-type: バイナリ フレームの場合は application/octet-stream。JSON フレームの場合は application/json。テキスト フレームの場合は text/plain。Protobuf フレームの場合は application/x-protobuf。
  • cloudEvents:type: azure.webpubsub.user.<event_name>

次のケースは、さまざまなデータ コンテンツ タイプと受信した AMQP メッセージ本文でイベントを送信する方法を示しています。

ケース 1: テキスト データを含むイベントを送信する:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "text",
    "data": "text data"
}

受信した AMQP メッセージ本文:

text data

ケース 2: JSON データを含むイベントを送信する:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "json",
    "data": {
        "hello": "world"
     }
}

受信した AMQP メッセージ本文:

{
    "hello": "world"
}

ケース 3: バイナリ データでイベントを送信する:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

受信した AMQP メッセージ本文:

<binary data>