適用於 Python 的 Azure Web PubSub 服務用戶端程式庫

發行項
04/10/2024

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

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

The overflow diagram shows the overflow of using the service client library.

使用此程式庫來：

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

必要條件

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

重要

Python 2.7 的 Azure SDK Python 套件支援已於 2022 年 1 月 1 日結束。如需詳細資訊，請參閱 Azure SDK Python 套件支援。

Install the package

使用此命令來安裝套件：

python -m pip install azure-messaging-webpubsubservice

建立及驗證 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>"))

或使用 Microsoft Entra ID：

pip 安裝 azure-identity。
在 Webpubsub 資源上啟用 Microsoft Entra 授權。

更新程式碼以使用 DefaultAzureCredential。

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

範例

以 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。

下一步

如需更多範例，請參閱適用於 Python 的 Azure Web PubSub 服務用戶端程式庫範例。

參與

此專案歡迎您參與並提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請參閱參與者授權合約。

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

此專案採用了 Microsoft 開放原始碼管理辦法。如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡開放原始碼管理小組。

共用方式為