快速入門：從主控台應用程式廣播即時訊息
Azure SignalR Service 能提供 REST API 以支援如廣播等的伺服器至用戶端通訊案例。 您可以選擇任何可進行 REST API 呼叫的程式設計語言。 您可以將訊息張貼到所有已連線的用戶端、依名稱指定的特定用戶端，或是某個用戶端群組。
在此快速入門中，您會了解如何以 C# 從命令列應用程式將訊息傳送至已連線的用戶端應用程式。
必要條件
此快速入門可以在 macOS、Windows 或 Linux 上執行。
- .NET Core SDK
- 您偏好的文字編輯器或程式碼編輯器。
如果您沒有 Azure 訂用帳戶，請在開始之前先建立 Azure 免費帳戶。
登入 Azure
使用 Azure 帳戶登入 Azure 入口網站。
在本節中，您會建立基本 Azure SignalR 執行個體，以用於您的應用程式。 下列步驟會使用 Azure 入口網站來建立新的執行個體，但您也可以使用 Azure CLI。 如需詳細資訊，請參閱 Azure SignalR Service CLI 參考中的 az signalr create 命令。
- 登入 Azure 入口網站。
- 在頁面的左側，選取 [+ 建立資源]。
- 在 [建立資源] 頁面上的 [搜尋服務和市集] 文字方塊中，輸入 signalr，然後從清單中選取 [SignalR Service]。
- 在 [SignalR Service] 頁面上，選取 [建立]。
- 在 [基本] 索引標籤上，您需要輸入新 SignalR Service 執行個體的重要資訊。 輸入下列值：
| 欄位 | 建議的值 | 描述 |
|---|---|---|
| 訂用帳戶 | 選擇您的訂用帳戶 | 選取您要用來建立新 SignalR Service 執行個體的訂用帳戶。 |
| 資源群組 | 建立名為 SignalRTestResources 的新資源群組 | 選取或建立 SignalR 資源的資源群組。 針對本教學課程建立新的資源群組，而不是使用現有的資源群組，會很有用。 若要在完成本教學課程之後釋出資源，請刪除資源群組。 刪除資源群組同時會刪除群組所屬的所有資源。 此動作無法復原。 刪除資源群組之前，請確定其不包含您想要保留的資源。 如需詳細資訊，請參閱 使用資源群組來管理您的 Azure 資源。 |
| 資源名稱 | testsignalr | 輸入要對 SignalR 資源使用的唯一資源名稱。 如果您的區域中已採用 testsignalr，請新增數字或字元，直到成為唯一的名稱為止。 名稱必須是 1 到 63 個字元的字串，而且只能包含數字、字母和連字號 ( -) 字元。 名稱的開頭或結尾不能是連字號字元，且連續連字號字元無效。 |
| 區域 | 選擇您的區域 | 選取新 SignalR Service 執行個體的適當區域。 Azure SignalR Service 目前不適用於所有區域。 如需詳細資訊，請參閱 Azure SignalR 區域可用性 |
| 定價層 | 選取 [變更]，然後選擇 [免費 (僅限開發/測試)]。 選擇 [選取] 來確認您選擇的定價層。 | Azure SignalR Service 有三個定價層：免費、標準和進階。 除非必要條件中另有說明，否則教學課程會使用 [免費] 層。 如需有關階層與定價之間功能差異的詳細資訊，請參閱 Azure SignalR Service 定價 |
| 服務模式 | 選擇適當的服務模式 | 當您在 Web 應用程式中裝載 SignalR 中樞邏輯並使用 SignalR Service 做為 Proxy 時，請使用 [預設值]。 當您使用 Azure Functions 之類的無伺服器技術來裝載 SignalR 中樞邏輯時，請使用 [無伺服器]。 [傳統] 模式僅適用於回溯相容性，不建議使用。 如需詳細資訊，請參閱 Azure SignalR Service 中的服務模式。 |
您不需要針對 SignalR 教學課程變更 [網路] 和 [標籤] 索引標籤上的設定。
- 選取 [基本] 索引標籤底部的 [檢閱 + 建立] 按鈕。
- 在 [檢閱 + 建立] 索引標籤上，檢閱這些值，然後選取 [建立]。 需要數分鐘才能完成部署。
- 部署完成後，請選取 [移至資源] 按鈕。
- 在 SignalR 資源頁面上，從左側功能表的 [設定] 底下選取 [金鑰]。
- 複製主索引鍵的 [連接字串]。 稍後在本教學課程中，您需要此連接字串來設定您的應用程式。
複製範例應用程式
在服務部署期間，請將程式碼準備就緒。 首先，從 GitHub 複製範例應用程式。 接下來，將 SignalR Service 連接字串設定為應用程式。 最後，在本機執行應用程式。
開啟 git 終端機視窗。 變更至您想要複製範例專案的資料夾。
執行下列命令來複製範例存放庫。 此命令會在您的電腦上建立範例應用程式副本。
git clone https://github.com/aspnet/AzureSignalR-samples.git
建置並執行範例
此範例為示範 Azure SignalR 服務之用途的主控台應用程式。 它提供兩個模式：
- 伺服器模式：使用簡單的命令來呼叫 Azure SignalR 服務 REST API。
- 用戶端模式：連線至 Azure SignalR 服務並接收來自伺服器的訊息。
您也可以了解如何產生存取權杖以向 Azure SignalR Service 進行驗證。
建置可執行檔
我們會使用 macOS osx.10.13-x64 作為範例。 您可以尋找參考以了解如何在其他平台上建置。
cd AzureSignalR-samples/samples/Serverless/
dotnet publish -c Release -r osx.10.13-x64
啟動用戶端
cd bin/Release/netcoreapp2.1/osx.10.13-x64/
Serverless client <ClientName> -c "<ConnectionString>" -h <HubName>
啟動伺服器
cd bin/Release/netcoreapp2.1/osx.10.13-x64/
Serverless server -c "<ConnectionString>" -h <HubName>
在不發行的情況下執行範例
您也可以執行下列命令來啟動伺服器或用戶端
# Start a server
dotnet run -- server -c "<ConnectionString>" -h <HubName>
# Start a client
dotnet run -- client <ClientName> -c "<ConnectionString>" -h <HubName>
使用使用者祕密來指定連接字串
您可以在範例的根目錄中執行 dotnet user-secrets set Azure:SignalR:ConnectionString "<ConnectionString>"。 在那之後，您便不再需要 -c "<ConnectionString>" 這個選項。
使用方式
在伺服器啟動之後，使用下列命令來傳送訊息：
send user <User Id>
send users <User List>
send group <Group Name>
send groups <Group List>
broadcast
您可以啟動具不同用戶端名稱的多個用戶端。
與非 Microsoft Services 整合
Azure SignalR Service 可讓非 Microsoft 服務與系統整合。
技術規格的定義
下表顯示目前所支援的所有 REST API 版本。 您也可以找到每個特定版本的定義檔
| 版本 | API 狀態 | 門 | 特定 |
|---|---|---|---|
1.0-preview |
可用的 | 5002 | Swagger |
1.0 |
可用的 | 標準 | Swagger |
下列清單提供每個特定版本的可用 API 清單。
| API | 1.0-preview | 1.0 |
|---|---|---|
| 向所有人廣播 | ✓ | ✓ |
| 廣播到群組 | ✓ | ✓ |
| 廣播到部分群組 | ✓ (已淘汰) | N / A |
| 傳送給使用者 | ✓ | ✓ |
| 傳送給部分使用者 | ✓ (已淘汰) | N / A |
| 將使用者新增至群組 | N / A |
✓ |
| 從群組中移除使用者 | N / A |
✓ |
| 檢查使用者是否存在 | N / A |
✓ |
| 從所有群組中移除使用者 | N / A |
✓ |
| 傳送至連線 | N / A |
✓ |
| 將連線新增至群組 | N / A |
✓ |
| 從群組移除連線 | N / A |
✓ |
| 關閉用戶端連線 | N / A |
✓ |
| 服務健康狀態 | N / A |
✓ |
廣播給所有人
| 版本 | API HTTP 方法 | 要求 URL | 要求本文 |
|---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name> |
{"target": "<method-name>", "arguments": [...]} |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name> |
{"target": "<method-name>", "arguments": [...]} |
廣播到群組
| 版本 | API HTTP 方法 | 要求 URL | 要求本文 |
|---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/group/<group-name> |
{"target": "<method-name>", "arguments": [...]} |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name> |
{"target": "<method-name>", "arguments": [...]} |
傳送給使用者
| 版本 | API HTTP 方法 | 要求 URL | 要求本文 |
|---|---|---|---|
1.0-preview |
POST |
https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/user/<user-id> |
{"target": "<method-name>", "arguments": [...]} |
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id> |
{"target": "<method-name>", "arguments": [...]} |
將使用者新增至群組
| 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
從群組中移除使用者
| 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
檢查群組中是否存在使用者
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id>/groups/<group-name> |
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
| 回應狀態碼 | 描述 |
|---|---|
200 |
已有此使用者 |
404 |
沒有此使用者 |
從所有群組中移除使用者
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id>/groups |
將訊息傳送至連線
| API 版本 | API HTTP 方法 | 要求 URL | 要求本文 |
|---|---|---|---|
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id> |
{ "target":"<method-name>", "arguments":[ ... ] } |
將連線新增至群組
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/connections/<connection-id> |
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>/groups/<group-name> |
從群組移除連線
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/connections/<connection-id> |
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>/groups/<group-name> |
關閉用戶端連線
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id> |
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>?reason=<close-reason> |
服務健康狀態
| API 版本 | API HTTP 方法 | 要求 URL |
|---|---|---|
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/health |
| 回應狀態碼 | 描述 |
|---|---|
200 |
服務狀態良好 |
5xx |
服務錯誤 |
清除資源
如果您將不繼續使用此應用程式，請使用下列步驟來刪除本快速入門所建立的全部資源，這樣才不會產生任何費用：
在 Azure 入口網站中選取最左側的 [資源群組]，然後選取您所建立的資源群組。 或者，您也可以使用搜尋方塊來依資源群組的名稱尋找它。
在開啟的視窗中選取資源群組，然後按一下 [刪除資源群組]。
在新視窗中輸入要刪除之資源群組的名稱，然後按一下 [刪除]。
下一步
在本快速入門中，您已了解如何使用 REST API 將即時訊息從 SignalR Service 廣播至用戶端。 接下來，請深入了解如何使用 SignalR Service 繫結 (以 REST API 為基礎所建置) 來開發和部署 Azure Functions。