使用 HTTP 通訊協定的 Azure Web PubSub 事件處理程式 CloudEvents 擴充功能

發行項
03/13/2024

Web PubSub 服務會使用 CloudEvents HTTP 通訊協定系結，將用戶端事件傳遞至上游 Webhook。

從 Web PubSub 服務傳送至伺服器的數據一律為 CloudEvents binary 格式。

Webhook 驗證
Web PubSub CloudEvents 屬性延伸模組
活動
- 封鎖事件
  - 系統 connect 事件
  - 使用者事件
- 解除封鎖事件
  - 系統 connected 事件
  - 系統 disconnected 事件

Webhook 驗證

Webhook 驗證遵循 CloudEvents。要求一律包含在 WebHook-Request-Origin: xxx.webpubsub.azure.com 標頭中。

如果傳遞目標只允許傳遞事件，它必須透過包含 WebHook-Allowed-Origin 標頭來回復要求，例如：

WebHook-Allowed-Origin: *

或：

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

目前不支援 WebHook-Request-Rate 和 WebHook-Request-Callback 。

Web PubSub CloudEvents 屬性擴充功能

另請注意，HTTP 規格現在正遵循類似的模式，不再建議擴充 HTTP 標頭前面加上 X- 。

此延伸模組會定義 Web PubSub 針對它產生的每個事件所使用的屬性。

屬性

名稱	類型	描述
`userId`	`string`	已驗證連線的使用者
`hub`	`string`	線上所屬的中樞
`connectionId`	`string`	connectionId 對於用戶端連線而言是唯一的
`eventName`	`string`	沒有前置詞的事件名稱
`subprotocol`	`string`	如果有任何專案，用戶端正在使用的子程式
`connectionState`	`string`	定義連線的狀態。您可以使用相同的回應標頭來重設狀態的值。不允許多個 `connectionState` 標頭。如果base64包含複雜字元，請在其中編碼字串值， `base64(jsonString)` 例如，使用這個屬性傳遞複雜物件。
`signature`	`string`	上游 Webhook 的簽章，用來驗證傳入要求是否來自預期的來源。服務會使用主要存取金鑰和次要存取金鑰作為 `HMAC` 金鑰來計算值： `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`。上游應該先檢查要求是否有效，再進行處理。

事件

事件有兩種類型。其中一個是封鎖服務等候事件回應繼續的事件。其中一個是 解除封鎖 服務在處理下一則訊息之前，不會等待這類事件的回應。

封鎖事件
- 系統 connect 事件
- 使用者事件
解除封鎖事件
- 系統 connected 事件
- 系統 disconnected 事件

系統 `connect` 事件

ce-type: azure.webpubsub.sys.connect
Content-Type: application/json

要求格式：

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

成功回應格式：

標頭 ce-connectionState：如果此標頭存在，此聯機的連接狀態將會更新為標頭的值。只有封鎖事件可以更新連線狀態。下列範例會使用base64編碼的 JSON 字串來儲存連線的複雜狀態。
狀態代碼：
- 204：成功，不含內容。
- 200：成功，內容應該是 JSON 格式，允許下列屬性：
  - subprotocols
    
    事件會 connect 從用戶端將子程式與驗證資訊轉送至上游。 Web PubSub 服務會使用狀態代碼來判斷要求是否會升級至 WebSocket 通訊協定。
    
    如果要求包含 subprotocols 屬性，伺服器應該會傳回它支援的一個子程式。如果伺服器不想使用任何子程式，則不應該在響應中傳送 subprotocol 屬性。傳送空白標頭無效。
  - userId: {auth-ed user ID}
    
    當服務允許匿名連線時， connect 事件會負責告訴服務用戶端連線的使用者標識碼。如果服務存在，就會從響應承載 userId 讀取使用者標識碼。如果使用者標識碼無法從要求宣告或 connect 事件響應承載讀取，則會卸除連線。
  - groups: {groups to join}
    
    屬性提供方便的方式，讓使用者將此連線新增至一或多個群組。如此一來，就不需要有另一個呼叫，才能將此聯機新增至某些群組。
  - roles: {roles the client has}
    
    屬性提供上游 Webhook 授權用戶端的方式。有不同的角色可授與 PubSub WebSocket 用戶端的初始許可權。有關許可權的詳細數據，請參閱客戶端許可權。

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

錯誤回應格式：

4xx：錯誤，來自上游的回應會當做用戶端要求的回應傳回。

HTTP/1.1 401 Unauthorized

系統 `connected` 事件

當用戶端完成 WebSocket 交握並成功連線時，服務會呼叫上游。

ce-type: azure.webpubsub.sys.connected
Content-Type: application/json
ce-connectionState: eyJrZXkiOiJhIn0=

要求本文是空的 JSON。

要求格式：

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

回應格式：

2xx：成功回應。

connected 是異步事件，當響應狀態代碼未成功時，服務會記錄錯誤。

HTTP/1.1 200 OK

系統 `disconnected` 事件

disconnected如果 connect 事件傳回2xx狀態代碼，用戶端要求完成時，一律會觸發事件。

ce-type: azure.webpubsub.sys.disconnected
Content-Type: application/json

要求格式：

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

reason

reason描述客戶端中斷連線的原因。

回應格式：

2xx：成功回應。

disconnected 是異步事件，當響應狀態代碼未成功時，服務會記錄錯誤。

HTTP/1.1 200 OK

簡單 WebSocket 用戶端的使用者事件`message`

服務會針對每個 WebSocket 訊息框架叫用事件處理程式上游。

ce-type: azure.webpubsub.user.message
Content-Type：application/octet-stream (適用於二進位框架)；text/plain (適用於文字框架)；

UserPayload 是用戶端傳送的內容。

要求格式：

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

成功回應格式

狀態代碼
- 204：成功，不含內容。
- 200：成功，的格式 UserResponsePayload 取決於 Content-Type 回應的。
Content-Type：application/octet-stream (適用於二進位框架)；text/plain (適用於文字框架)；
標頭 Content-Type： application/octet-stream 二進製圖文框; text/plain 文字圖文框;
標頭 ce-connectionState：如果此標頭存在，此聯機的連接狀態將會更新為標頭的值。只有封鎖事件可以更新連線狀態。下列範例會使用base64編碼的 JSON 字串來儲存連線的複雜狀態。

Content-Type當是 application/octet-stream時，服務會使用 binary WebSocket 畫面傳送UserResponsePayload至用戶端。 Content-Type當是 text/plain時，服務會使用 text WebSocket 畫面傳送UserResponsePayload至用戶端。

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

錯誤回應格式

當狀態代碼未成功時，它會被視為錯誤回應。如果回應狀態代碼不成功，message則會卸除連線。

PubSub WebSocket 用戶端的使用者自訂事件 `{custom_event}`

服務會針對每個有效的自定義事件訊息呼叫事件處理程式 Webhook。

案例 1：使用文字資料傳送事件：

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

上游事件處理程式接收的內容如下，Content-TypeCloudEvents HTTP 要求的text/plaindataType=text

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

案例 2：使用 JSON 資料傳送事件：

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

上游事件處理程式接收的內容如下，Content-TypeCloudEvents HTTP 要求的application/jsondataType=json

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

案例 3：使用二進位資料傳送事件：

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

上游事件處理程式接收的內容如下，Content-TypeCloudEvents HTTP 要求的application/octet-streamdataType=binary

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

成功回應格式

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

狀態代碼
- 204：成功，不含內容。
- 200：成功，傳送至 PubSub WebSocket 用戶端的數據取決於 ;Content-Type
標頭 ce-connectionState：如果此標頭存在，此聯機的連接狀態將會更新為標頭的值。只有封鎖事件可以更新連線狀態。下列範例會使用base64編碼的 JSON 字串來儲存連線的複雜狀態。
當 Header Content-Type 為 application/octet-stream時，服務會使用 dataType 和承載base64編碼一樣binary傳UserResponsePayload回用戶端。範例回應：
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Content-Type當是 text/plain時，服務會使用 dataType 和承載字串一樣text傳送UserResponsePayload至用戶端。
Content-Type當為 application/json時，服務會使用=dataTypejson 搭配data值令牌作為響應承載主體傳送UserResponsePayload至用戶端。

錯誤回應格式

當狀態代碼未成功時，它會被視為錯誤回應。如果回應狀態代碼不成功，{custom_event}則會卸除連線。

下一步

使用這些資源開始建置您自己的應用程式：

教學課程：在 Azure Web PubSub 中發佈和訂閱訊息

教學課程：使用 Azure Web PubSub 建立簡單的聊天室

教學課程：針對用戶端串流使用服務支援的子程式

教學課程：使用 Azure Functions 和 Web PubSub 建置無伺服器聊天

教學課程：設定事件接聽程式

播放實時示範

探索更多 Azure Web PubSub 範例

共用方式為

使用 HTTP 通訊協定的 Azure Web PubSub 事件處理程式 CloudEvents 擴充功能

Webhook 驗證

Web PubSub CloudEvents 屬性擴充功能

屬性

事件

系統 `connect` 事件

要求格式：

成功回應格式：

錯誤回應格式：

系統 `connected` 事件

要求格式：

回應格式：

系統 `disconnected` 事件

要求格式：

回應格式：

簡單 WebSocket 用戶端的使用者事件`message`

要求格式：

成功回應格式

錯誤回應格式

PubSub WebSocket 用戶端的使用者自訂事件 `{custom_event}`

案例 1：使用文字資料傳送事件：

案例 2：使用 JSON 資料傳送事件：

案例 3：使用二進位資料傳送事件：

成功回應格式

錯誤回應格式

下一步

意見反應

其他資源

共用方式為

使用 HTTP 通訊協定的 Azure Web PubSub 事件處理程式 CloudEvents 擴充功能

Webhook 驗證

Web PubSub CloudEvents 屬性擴充功能

屬性

事件

系統 connect 事件

要求格式：

成功回應格式：

錯誤回應格式：

系統 connected 事件

要求格式：

回應格式：

系統 disconnected 事件

要求格式：

回應格式：

簡單 WebSocket 用戶端的使用者事件message

要求格式：

成功回應格式

錯誤回應格式

PubSub WebSocket 用戶端的使用者自訂事件 {custom_event}

案例 1：使用文字資料傳送事件：

案例 2：使用 JSON 資料傳送事件：

案例 3：使用二進位資料傳送事件：

成功回應格式

錯誤回應格式

下一步

意見反應

其他資源

系統 `connect` 事件

系統 `connected` 事件

系統 `disconnected` 事件

簡單 WebSocket 用戶端的使用者事件`message`

PubSub WebSocket 用戶端的使用者自訂事件 `{custom_event}`