Azure SignalR Service 數據平面 REST API 參考
除了傳統用戶端/伺服器模式之外，Azure SignalR Service 還提供一組 REST API，協助您將即時功能整合到無伺服器架構中。
注意
Azure SignalR 服務僅支援使用 REST API 來管理透過 ASP.NET Core SignalR 連線的用戶端。 透過 ASP.NET SignalR 連線的用戶端會使用不同的資料通訊協定，目前不支援。
使用 Azure Functions 的典型無伺服器架構
下圖顯示搭配 Azure Functions 使用 Azure SignalR Service 的典型無伺服器架構。
- 函
negotiate式會傳回交涉回應，並將所有用戶端重新導向至 Azure SignalR Service。 - 函
broadcast式會呼叫 Azure SignalR 服務的 REST API。 Azure SignalR Service 會將訊息廣播至所有連線的用戶端。
在無伺服器架構中，用戶端會持續連線到 Azure SignalR Service。 因為沒有應用程式伺服器可處理流量，用戶端處於 LISTEN 模式。 在該模式中，用戶端可以接收訊息，但無法傳送訊息。 Azure SignalR Service 會中斷傳送訊息的任何用戶端連線，因為它是無效的作業。
您可以在此 GitHub 存放庫中找到搭配 Azure SignalR Service 與 Azure Functions 的完整範例。
實作交涉端點
您應該實作傳 negotiate 回重新導向交涉回應的函式，讓用戶端可以連線到服務。
典型的交涉回應具有下列格式：
{
"url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
"accessToken": "<a typical JWT token>"
}
此值accessToken是透過驗證一節中所述的相同演算法所產生。 唯一的差異在於 aud 宣告應該與 url相同。
您應該在 中 https://<hub_url>/negotiate 裝載交涉 API，以便您仍然可以使用 SignalR 用戶端來連線到中樞 URL。 深入瞭解如何在用戶端連線中將用戶端重新導向至 Azure SignalR Service。
REST API 版本
下表顯示所有支援的 REST API 版本。 它也會為每個 API 版本提供 Swagger 檔案。
| API 版本 | 狀態 | 連接埠 | 文件集 | 規格 |
|---|---|---|---|---|
20220601 |
最新 | 標準 | 發行項 | Swagger 檔案 |
1.0 |
穩定 | 標準 | 發行項 | Swagger 檔案 |
1.0-preview |
已淘汰 | 標準 | 發行項 | Swagger 檔案 |
下表列出可用的 API。
| API | 路徑 |
|---|---|
| 將訊息廣播至連線至目標中樞的所有用戶端 | POST /api/v1/hubs/{hub} |
| 將訊息廣播給所有用戶端屬於目標使用者 | POST /api/v1/hubs/{hub}/users/{id} |
| 將訊息傳送至特定連線 | POST /api/v1/hubs/{hub}/connections/{connectionId} |
| 檢查具有指定 connectionId 的連線是否存在 | GET /api/v1/hubs/{hub}/connections/{connectionId} |
| 關閉用戶端連線 | DELETE /api/v1/hubs/{hub}/connections/{connectionId} |
| 將訊息廣播至目標群組內的所有用戶端 | POST /api/v1/hubs/{hub}/groups/{group} |
| 檢查指定群組內是否有任何用戶端連線 | GET /api/v1/hubs/{hub}/groups/{group} |
| 檢查指定使用者是否有任何客戶端連線 | GET /api/v1/hubs/{hub}/users/{user} |
| 將連線新增至目標群組 | PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId} |
| 從目標群組移除連線 | DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId} |
| 檢查使用者是否存在於目標群組中 | GET /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| 將使用者新增至目標群組 | PUT /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| 從目標群組移除使用者 | DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user} |
| 從所有群組中移除使用者 | DELETE /api/v1/hubs/{hub}/users/{user}/groups |
使用 REST API
透過 Azure SignalR Service 中的 AccessKey 進行驗證
在每個 HTTP 要求中，需要具有 JSON Web 令牌 （JWT） 的授權標頭，才能向 Azure SignalR 服務進行驗證。
簽署演算法和簽章
HS256，即 HMAC-SHA256，用來做為簽署演算法。
AccessKey使用 Azure SignalR Service 實例 連接字串 中的值來簽署產生的 JWT。
宣告
下列宣告必須包含在 JWT 中。
| 宣告類型 | 是必要的 | 描述 |
|---|---|---|
aud |
true |
必須與 HTTP 要求 URL 相同，不包括尾端斜線和查詢參數。 例如，廣播要求的對象看起來應該像： https://example.service.signalr.net/api/v1/hubs/myhub。 |
exp |
true |
此令牌到期的 Epoch 時間。 |
透過 Microsoft Entra 令牌進行驗證
類似於透過 AccessKey進行驗證， JWT 必須使用 Microsoft Entra 令牌來驗證 HTTP 要求。
差異在於，在此案例中，Microsoft Entra ID 會產生 JWT。 如需詳細資訊，請參閱 瞭解如何產生Microsoft Entra 令牌。
使用的認證範圍應該是 https://signalr.azure.com/.default。
您也可以使用 角色型訪問控制 （RBAC） 來授權客戶端或伺服器的要求給 Azure SignalR 服務。 如需詳細資訊，請參閱 使用 Azure SignalR Service 的 Microsoft Entra ID 授權存取權。
用戶相關的 REST API
若要呼叫使用者相關的 REST API，每個用戶端都應該向 Azure SignalR 服務識別自己。 否則，Azure SignalR 服務無法從使用者標識碼找到目標連線。
連線到 Azure SignalR 服務時，您可以在每個用戶端的 JWT 中包含宣告，以達成客戶端識別 nameid 。 Azure SignalR Service 接著會使用宣告的值 nameid 作為每個用戶端連線的使用者標識碼。
範例
在此 GitHub 存放庫中，您可以找到完整的控制台應用程式，以示範如何在 Azure SignalR Service 中手動建置 REST API HTTP 要求。
您也可以使用 Microsoft.Azure.SignalR.Management 將訊息發佈至 Azure SignalR Service，方法是使用 的 IHubContext類似介面。 您可以在此 GitHub 存放庫中找到範例。 如需詳細資訊，請參閱 Azure SignalR Service Management SDK。
限制
REST API 要求目前有下列限制：
- 標頭大小上限為 16 KB。
- 本文大小上限為 1 MB。
如果您想要傳送大於 1 MB 的訊息，請使用服務管理 SDK 搭配 persistent 模式。