分享方式：

使用 AMQP 通訊協定的 Azure Web PubSub 事件接聽程式 CloudEvents 延伸模組

  • 文章

Azure Web PubSub 服務會將用戶端事件描述為 CloudEvents。 CloudEvents 是用於描述常見格式的事件資料，以提供跨服務、跨平台和跨系統互通性的規格。

服務的事件接聽程式會接聽用戶端事件。 事件中樞目前是唯一支援的事件接聽程式端點，其主要通訊協定是 AMQP (進階訊息佇列通訊協定)。 Web PubSub 服務會使用 CloudEvents AMQP 通訊協定繫結，將 CloudEvents 對應至 AMQP 訊息。

從服務傳送到伺服器的資料一律採用 CloudEvents binary 格式。

Web PubSub CloudEvents 屬性擴充功能

此擴充功能會定義 Web PubSub 針對其產生的每個事件所使用的屬性。

下表包含與 AMQP 訊息的標準屬性區段對應的屬性。

名稱 描述: 範例
content-type 訊息本文的 RFC-2046 MIME 類型 application/json
message-id 可在 Web PubSub 服務中唯一定義訊息，格式為「{連線識別碼}/{服務產生的整數}」 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

下表包含與 AMQP 訊息的應用程式屬性區段對應的所有 CloudEvents 屬性。 每個屬性名稱前面都會加上 cloudEvents:。

名稱 描述: 範例
specversion 雲端事件規格版本一律為 1.0 1.0
source 指出事件來源的中樞和連線識別碼，格式為「/hubs/{中樞}/client/{連線識別碼}」 /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id 服務產生的整數，在相同用戶端連線的事件中是唯一的值 1
awpsversion 雲端事件 Azure Web PubSub 規格版本一律為 1.0 1.0
hub 事件來源的中樞名稱 聊天
eventname 事件的名稱 已連接
type 事件類型 azure.webpubsub.sys.connect
connectionid 用戶端連線的識別碼 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time 服務傳送事件的時間，格式為「yyyy-MM-ddTHH:mm:ssZ」 2021-01-01T00:00:00Z
userid* 使用者的識別碼 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 (適用於二進位框架)；application/json (適用於 JSON 框架)；text/plain (適用於文字框架)；application/x-protobuf (適用於 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>