適用于 Python 的 Azure Web PubSub 服務用戶端程式庫 - 1.0.1 版

發行項
04/05/2023

Azure Web PubSub Service 是一項 Azure 受控服務，可協助開發人員輕鬆建置具有即時功能和發佈訂閱模式的 Web 應用程式。任何需要伺服器與用戶端之間或用戶端之間即時發佈-訂閱傳訊的案例都可以使用 Azure Web PubSub 服務。通常需要從伺服器輪詢或提交 HTTP 要求的傳統即時功能也可以使用 Azure Web PubSub 服務。

您可以在應用程式伺服器端使用此程式庫來管理 WebSocket 用戶端連線，如下圖所示：

使用此程式庫來：

將訊息傳送至中樞和群組。
將訊息傳送給特定使用者和連線。
將使用者和連線組織成群組。
關閉連線
授與、撤銷和檢查現有連線的許可權

| 原始程式碼套件 (Pypi) | API 參考檔 | 產品檔

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

需要 Python 3.6 或更新版本才能使用此套件。
您需要 Azure 訂用帳戶和 Azure WebPubSub 服務實例，才能使用此套件。
現有的 Azure Web PubSub 服務實例。

1.安裝套件

python -m pip install azure-messaging-webpubsubservice

2.建立及驗證 WebPubSubServiceClient

您可以使用連接字串來驗證 WebPubSubServiceClient ：

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string(connection_string='<connection_string>', hub='hub')

或使用服務端點和存取金鑰：

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.core.credentials import AzureKeyCredential

>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=AzureKeyCredential("<access_key>"))

或使用 Azure Active Directory：

pip 安裝 azure-identity
請遵循檔在 Webpubsub 資源上啟用 AAD 驗證

更新程式碼以使用 DefaultAzureCredential

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.identity import DefaultAzureCredential
>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=DefaultAzureCredential())

重要概念

連線

連線也稱為用戶端或用戶端連線，代表連線到 Web PubSub 服務的個別 WebSocket 連線。成功連線時，Web PubSub 服務會指派唯一連線識別碼給此連線。

集線器

中樞是一組用戶端連線的邏輯概念。通常您會針對一個用途使用一個中樞，例如聊天中樞或通知中樞。建立用戶端連線時，它會連線到中樞，並在其存留期間屬於該中樞。不同的應用程式可以使用不同的中樞名稱來共用一個 Azure Web PubSub 服務。

群組

群組是中樞連線的子集。您可以隨時將用戶端連線新增至群組，或從群組中移除用戶端連線。例如，當用戶端加入聊天室，或用戶端離開聊天室時，可以將此聊天室視為群組。用戶端可以加入多個群組，而群組可以包含多個用戶端。

User

Web PubSub 的連線可以屬於一個使用者。例如，當使用者跨多個裝置或多個瀏覽器索引標籤連線單一使用者時，可能會有多個連線。

訊息

當用戶端連線時，它可以透過 WebSocket 連線，將訊息傳送至上游應用程式，或從上游應用程式接收訊息。

範例

以 JSON 格式廣播訊息

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = {
        'from': 'user1',
        'data': 'Hello world'
    })

WebSocket 用戶端將會收到 JSON 序列化文字： {"from": "user1", "data": "Hello world"} 。

純文字格式廣播訊息

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = 'Hello world', content_type='text/plain')

WebSocket 用戶端將會收到文字： Hello world 。

以二進位格式廣播訊息

>>> import io
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub')
>>> service.send_to_all(message=io.StringIO('Hello World'), content_type='application/octet-stream')

WebSocket 用戶端將會收到二進位文字： b'Hello world' 。

疑難排解

記錄

此 SDK 使用 Python 標準記錄程式庫。您可以將記錄列印出偵錯資訊設定為 stdout 或您想要的任何位置。

import sys
import logging
from azure.identity import DefaultAzureCredential
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "<endpoint>"
credential = DefaultAzureCredential()

# This WebPubSubServiceClient will log detailed information about its HTTP sessions, at DEBUG level
service = WebPubSubServiceClient(endpoint=endpoint, hub='hub', credential=credential, logging_enable=True)

同樣地， logging_enable 即使未針對 WebPubSubServiceClient 啟用，也可以啟用單一呼叫的詳細記錄：

result = service.send_to_all(..., logging_enable=True)

Http 要求和回應詳細資料會使用此記錄設定列印至 stdout。

下一步

請在這裡查看更多範例。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題，或連絡 opencode@microsoft.com 任何其他問題或意見。

共用方式為