教學課程:使用 WebSocket API 和 Azure Web PubSub 服務 SDK 發佈和訂閱訊息
本文內容
Azure Web PubSub 服務可協助您輕鬆地建置即時 Web 傳訊應用程式。 在本教學課程中,您將瞭解如何使用 WebSocket API 訂閱服務,並使用 Web PubSub 服務 SDK 發佈訊息。
在本教學課程中,您會了解如何:
建立 Web PubSub 服務實例
產生建立 WebSocket 連線的完整 URL
建立 Web PubSub 訂閱者用戶端,以使用標準 WebSocket 通訊協定接收訊息
使用 Web PubSub 服務 SDK 建立 Web PubSub 發行者用戶端來發布訊息
必要條件
您可以使用 Windows cmd.exe 命令殼層,而不是 Bash 殼層來執行本教學課程中的命令。
如果在本機電腦上建立專案,您必須安裝所使用語言的相依性:
準備您的環境
適用於本機開發的 Azure CLI 設定
請遵循下列步驟來設定 Azure CLI 和您的項目環境。
開啟命令殼層。
升級至最新版的 Azure CLI。
az upgrade
安裝適用於 Web PubSub 的 Azure CLI 擴充功能。
az extension add --name webpubsub
登入 Azure CLI。 在提示之後,輸入您的 Azure 認證。
az login
建立資源群組
資源群組是在其中部署與管理 Azure 資源的邏輯容器。 使用 az group create 命令,在位置中eastus
建立名為 myResourceGroup
的資源群組。
az group create --name myResourceGroup --location EastUS
1.建立 Azure Web PubSub 實例
建立 Web PubSub 執行個體
使用 Azure CLI az webpubsub create 命令,在您所建立的資源群組中建立 Web PubSub。 下列命令會在 中的EastUS
資源群組myResourceGroup
下建立免費的 Web PubSub 資源:
每個 Web PubSub 資源都必須有唯一的名稱。 使用下列命令中的 Web PubSub 實例名稱取代 <your-unique-resource-name> 。
az webpubsub create --resource-group myResourceGroup --name <your-unique-resource-name> --location EastUS --sku Free_F1
此命令的輸出會顯示新建立之資源的屬性。 記下下列兩個屬性:
name :您在上述參數中 --name
提供的 Web PubSub 名稱。
hostName :在此範例中,主機名為 <your-unique-resource-name>.webpubsub.azure.com/
。
此時,您的 Azure 帳戶是唯一有權在此新資源上執行任何作業的帳戶。
取得連接字串
重要
連接字串 包含應用程式存取 Azure Web PubSub 服務所需的授權資訊。 連接字串內的存取金鑰類似於您服務的根密碼。 在生產環境中,請務必小心保護您的存取密鑰。 使用 Azure 金鑰保存庫 安全地管理和輪替密鑰。 請避免將存取金鑰散發給其他使用者、進行硬式編碼,或將密鑰儲存到其他使用者可存取的純文本中的任何位置。 如果您認為金鑰可能遭到入侵,請輪替您的金鑰。
使用 Azure CLI az webpubsub key 命令來取得服務的 連線 ionString 。 將 <your-unique-resource-name>
佔位元取代為您的 Azure Web PubSub 實例名稱。
az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv
複製 連接字串 以供稍後使用。
建立訂閱者用戶端
用戶端會使用 JSON Web 令牌 (JWT) 驗證,透過標準 WebSocket 通訊協定連線到 Azure Web PubSub 服務。 服務 SDK 提供協助程式方法來產生令牌。 在本教學課程中,訂閱者會直接從 連線 ionString 產生令牌。 在實際的應用程式中,伺服器端應用程式通常會處理驗證/授權工作流程。 若要進一步瞭解工作流程,請參閱建置聊天應用程式教學課程 。
首先,為此專案建立名為 subscriber
的項目目錄,並安裝必要的相依性:
套件 Websocket.Client 是支援 WebSocket 連線的第三方套件。 您可以使用任何支援 WebSocket 的 API/連結庫。
SDK 套件 Azure.Messaging.WebPubSub
有助於產生 JWT 令牌。
mkdir subscriber
cd subscriber
dotnet new console
dotnet add package Websocket.Client --version 4.3.30
dotnet add package Azure.Messaging.WebPubSub --version 1.0.0
將中的 Program.cs
程式代碼取代為將連線至服務的下列程式代碼:
using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;
using Websocket.Client;
namespace subscriber
{
class Program
{
static async Task Main(string[] args)
{
if (args.Length != 2)
{
Console.WriteLine("Usage: subscriber <connectionString> <hub>");
return;
}
var connectionString = args[0];
var hub = args[1];
// Either generate the URL or fetch it from server or fetch a temp one from the portal
var serviceClient = new WebPubSubServiceClient(connectionString, hub);
var url = serviceClient.GetClientAccessUri();
using (var client = new WebsocketClient(url))
{
// Disable the auto disconnect and reconnect because the sample would like the client to stay online even no data comes in
client.ReconnectTimeout = null;
client.MessageReceived.Subscribe(msg => Console.WriteLine($"Message received: {msg}"));
await client.Start();
Console.WriteLine("Connected.");
Console.Read();
}
}
}
}
此程式代碼會建立 WebSocket 連線,連線到 Web PubSub 中的中樞。 中樞是 Web PubSub 中的邏輯單元,您可以在其中將訊息發佈至用戶端群組。 重要概念 包含 Web PubSub 中所用詞彙的詳細說明。
Web PubSub 服務會使用 JSON Web 令牌 (JWT) 驗證。 範例程式代碼會在 WebPubSubServiceClient.GetClientAccessUri()
Web PubSub SDK 中使用 ,以產生包含具有有效存取令牌之完整 URL 的服務 URL。
建立連線之後,您的用戶端會透過 WebSocket 連線接收訊息。 用戶端會使用 client.MessageReceived.Subscribe(msg => ...));
來接聽傳入訊息。
若要啟動訂閱者,請執行下列命令,將 <Web-PubSub-connection-string>
取代為您稍早複製的 連接字串:
dotnet run <Web-PubSub-connection-string> "myHub1"
首先,建立名為 subscriber
的項目目錄,並安裝必要的相依性:
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
使用 WebSocket API 連線到 Web PubSub 服務。 以下列程式碼建立 subscribe.js
檔案:
const WebSocket = require('ws');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
async function main() {
const hub = "pubsub";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
let token = await service.getClientAccessToken();
let ws = new WebSocket(token.url);
ws.on('open', () => console.log('connected'));
ws.on('message', data => console.log('Message received: %s', data));
}
main();
此程式代碼會建立 WebSocket 連線,連線到 Web PubSub 中的中樞。 中樞是 Web PubSub 中的邏輯單元,您可以在其中將訊息發佈至用戶端群組。 重要概念 包含 Web PubSub 中所用詞彙的詳細說明。
Web PubSub 服務會使用 JSON Web 令牌 (JWT) 驗證。 範例程式代碼會在 WebPubSubServiceClient.GetClientAccessUri()
Web PubSub SDK 中使用 ,以產生包含具有有效存取令牌之完整 URL 的服務 URL。
建立連線之後,您的用戶端會透過 WebSocket 連線接收訊息。 用戶端會使用 client.MessageReceived.Subscribe(msg => ...));
來接聽傳入訊息。
執行下列命令,將 <Web-PubSub-connection-string>
取代為您稍早複製的 連接字串。 如果您使用 Windows 命令殼層,您可以使用 set
而非 export
。
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
首先,建立名為 subscriber
的項目目錄,並安裝必要的相依性:
mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate
pip install azure-messaging-webpubsubservice
pip install websockets
使用 WebSocket API 連線到 Web PubSub 服務。 以下列程式碼建立 subscribe.py
檔案:
import asyncio
import sys
import websockets
from azure.messaging.webpubsubservice import WebPubSubServiceClient
async def connect(url):
async with websockets.connect(url) as ws:
print('connected')
while True:
print('Received message: ' + await ws.recv())
if __name__ == '__main__':
if len(sys.argv) != 3:
print('Usage: python subscribe.py <connection-string> <hub-name>')
exit(1)
connection_string = sys.argv[1]
hub_name = sys.argv[2]
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
token = service.get_client_access_token()
try:
asyncio.get_event_loop().run_until_complete(connect(token['url']))
except KeyboardInterrupt:
pass
此程式代碼會建立 WebSocket 連線,連線到 Web PubSub 中的中樞。 中樞是 Web PubSub 中的邏輯單元,您可以在其中將訊息發佈至用戶端群組。 重要概念 包含 Web PubSub 中所用詞彙的詳細說明。
Web PubSub 服務會使用 JSON Web 令牌 (JWT) 驗證。 範例程式代碼會在 WebPubSubServiceClient.GetClientAccessUri()
Web PubSub SDK 中使用 ,以產生包含具有有效存取令牌之完整 URL 的服務 URL。
建立連線之後,您的用戶端會透過 WebSocket 連線接收訊息。 使用 await ws.recv()
來接聽傳入訊息。
執行下列命令,將 <Web-PubSub-connection-string>
取代為您稍早複製的 連接字串:
python subscribe.py <Web-PubSub-connection-string> "myHub1"
首先,為本教學課程建立名為 pubsub
的項目目錄。
mkdir pubsub
cd pubsub
在 pubsub
目錄中,使用 Maven 建立名為 webpubsub-quickstart-subscriber
的新控制台應用程式,然後移至 webpubsub-quickstart-subscriber 目錄:
mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-subscriber --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-subscriber
將 WebSocket 和 Azure Web PubSub SDK 新增至 dependencies
中的 pom.xml
節點:
azure-messaging-webpubsub
:適用於 Java 的 Web PubSub 服務 SDK
Java-WebSocket
:適用於 Java 的 WebSocket 用戶端 SDK
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-messaging-webpubsub</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>org.java-websocket</groupId>
<artifactId>Java-WebSocket</artifactId>
<version>1.5.1</version>
</dependency>
在 Web PubSub 中,您可以連線到服務,並透過 WebSocket 連線訂閱訊息。 WebSocket 是一個全雙工通道,可讓服務即時將訊息推送至您的用戶端。 您可以使用任何支援 WebSocket 的 API 或連結庫。 在此範例中,我們使用套件 Java-WebSocket 。
移至 /src/main/java/com/webpubsub/quickstart 目錄。
編輯以下欄程序代碼取代App.java檔案的內容 :
package com.webpubsub.quickstart;
import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App
{
public static void main( String[] args ) throws IOException, URISyntaxException
{
if (args.length != 2) {
System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
return;
}
WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
.connectionString(args[0])
.hub(args[1])
.buildClient();
WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());
WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
@Override
public void onMessage(String message) {
System.out.println(String.format("Message received: %s", message));
}
@Override
public void onClose(int arg0, String arg1, boolean arg2) {
// TODO Auto-generated method stub
}
@Override
public void onError(Exception arg0) {
// TODO Auto-generated method stub
}
@Override
public void onOpen(ServerHandshake arg0) {
// TODO Auto-generated method stub
}
};
webSocketClient.connect();
System.in.read();
}
}
此程式代碼會建立連線至 Azure Web PubSub 中樞的 WebSocket 連線。 中樞是 Azure Web PubSub 中的邏輯單元,您可以在其中將訊息發佈至用戶端群組。 重要概念 包含 Azure Web PubSub 中所用詞彙的詳細說明。
Web PubSub 服務會使用 JSON Web 令牌 (JWT) 驗證。 範例程式代碼會在 WebPubSubServiceClient.GetClientAccessUri()
Web PubSub SDK 中使用 ,以產生包含具有有效存取令牌之完整 URL 的服務 URL。
建立連線之後,您的用戶端會透過 WebSocket 連線接收訊息。 使用 onMessage(String message)
來接聽傳入訊息。
若要啟動訂閱者應用程式,請移至 webpubsub-quickstart-subscriber 目錄,然後執行下列命令。 將取代<Web-PubSub-connection-string>
為您稍早複製的 連接字串。
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
2.使用服務 SDK 發佈訊息
使用 Azure Web PubSub SDK 建立發行者,將訊息發佈至連線的用戶端。 針對此專案,您必須開啟另一個命令殼層。
首先,建立名為 publisher
的項目目錄,並安裝必要的相依性:
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
Program.cs
更新 檔案以使用 WebPubSubServiceClient
類別,並將訊息傳送至用戶端。
using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;
namespace publisher
{
class Program
{
static async Task Main(string[] args)
{
if (args.Length != 3) {
Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
return;
}
var connectionString = args[0];
var hub = args[1];
var message = args[2];
// Either generate the token or fetch it from server or fetch a temp one from the portal
var serviceClient = new WebPubSubServiceClient(connectionString, hub);
await serviceClient.SendToAllAsync(message);
}
}
}
呼叫 SendToAllAsync()
只會將訊息傳送至中樞中的所有已連線用戶端。
執行下列命令來傳送訊息。 將取代<Web-PubSub-connection-string>
為您稍早複製的 連接字串。
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
檢查訂閱者的命令殼層,以查看它是否收到訊息:
Message received: Hello World
首先,建立名為 publisher
的項目目錄,並安裝必要的相依性:
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
使用 Azure Web PubSub SDK 將訊息發佈至服務。 使用下列程式代碼建立 publish.js
檔案:
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hub = "pubsub";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });
呼叫 service.sendToAll()
只會將訊息傳送至中樞中的所有已連線用戶端。
若要傳送訊息,請執行下列命令,並將 <Web-PubSub-connection-string>
取代為您稍早複製的 連接字串。 如果您使用 Windows 命令殼層,您可以使用 set
而非 export
。
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
您可以看到訂閱者收到訊息:
Message received: Hello World
首先,建立名為 publisher
的項目目錄,並安裝必要的相依性:
mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate
pip install azure-messaging-webpubsubservice
使用 Azure Web PubSub SDK 將訊息發佈至服務。 使用下列程式代碼建立 publish.py
檔案:
import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient
if __name__ == '__main__':
if len(sys.argv) != 4:
print('Usage: python publish.py <connection-string> <hub-name> <message>')
exit(1)
connection_string = sys.argv[1]
hub_name = sys.argv[2]
message = sys.argv[3]
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
res = service.send_to_all(message, content_type='text/plain')
print(res)
將 send_to_all()
訊息傳送至中樞中的所有已連線用戶端。
若要傳送訊息,請執行下列命令,將 <Web-PubSub-connection-string>
取代為您稍早複製的 連接字串。
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
檢查上一個命令殼層,讓訂閱者收到訊息:
Received message: Hello World
移至 pubsub
目錄。 使用 Maven 建立發行者控制台應用程式 webpubsub-quickstart-publisher
,並移至 webpubsub-quickstart-publisher 目錄:
mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-publisher --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-publisher
將 Azure Web PubSub SDK 相依性新增至 的 dependencies
節點 pom.xml
:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-messaging-webpubsub</artifactId>
<version>1.0.0</version>
</dependency>
使用 Azure Web PubSub SDK 將訊息發佈至服務。 移至 /src/main/java/com/webpubsub/quickstart 目錄,在您的編輯器中開啟 App.java 檔案,並以下列程式代碼取代內容:
package com.webpubsub.quickstart;
import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;
/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App
{
public static void main( String[] args )
{
if (args.length != 3) {
System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
return;
}
WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
.connectionString(args[0])
.hub(args[1])
.buildClient();
service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
}
}
呼叫會將 sendToAll()
訊息傳送至中樞中的所有已連線用戶端。
若要傳送訊息,請移至 webpubsub-quickstart-publisher 目錄,並使用下列命令執行專案。 <Web-PubSub-connection-string>
將取代為您稍早複製的 連接字串。
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"
您可以看到訂閱者收到訊息:
Message received: Hello World
清理
您可以刪除包含這些資源的資源群組,以刪除在本快速入門中建立的資源。
az group delete --name myResourceGroup --yes
如果您不打算繼續使用 Azure Cloud Shell,您可以刪除包含相關聯記憶體帳戶的資源群組,以避免累積成本。 資源群組的名稱為 cloud-shell-storage-<your-region>
。 執行下列命令,將 取代 <CloudShellResourceGroup>
為 Cloud Shell 組名。
az group delete --name <CloudShellResourceGroup> --yes
警告
刪除資源群組將會刪除所有資源,包括在本教學課程範圍之外建立的資源。
下一步
本教學課程提供如何連線至 Web PubSub 服務,並將訊息發佈至連線用戶端的基本概念。
請參閱其他教學課程,進一步探討如何使用服務。