Azure SignalR Service 資料平面 REST API 參考

文章
10/24/2023

除了傳統用戶端/伺服器模式之外，Azure SignalR Service 還提供一組 REST API，協助您將即時功能整合到無伺服器架構中。

注意

Azure SignalR 服務僅支援使用 REST API 來管理透過 ASP.NET Core SignalR 連線的用戶端。透過 ASP.NET SignalR 連線的用戶端會使用不同的資料通訊協定，目前不支援。

使用 Azure Functions 的典型無伺服器架構

下圖顯示搭配 Azure Functions 使用 Azure SignalR Service 的典型無伺服器架構。

Diagram of a typical serverless architecture for 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 版本	狀態	Port	文件	規格
`20220601`	最新	標準	發行項	Swagger 檔案
`1.0`	穩定	標準	發行項	Swagger 檔案
`1.0-preview`	Obsolete	標準	發行項	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 權杖。

您也可以使用 角色型存取控制（RBAC） 來授權用戶端或伺服器的要求給 Azure SignalR 服務。如需詳細資訊，請參閱使用適用于 Azure SignalR 服務的 Microsoft Entra ID 授權存取權。

若要呼叫使用者相關的 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 服務，方法是使用的 IHubContext 類似介面。您可以在此 GitHub 存放庫中找到範例。如需詳細資訊，請參閱 Azure SignalR Service Management SDK 。

限制

REST API 要求目前有下列限制：

標頭大小上限為 16 KB。
本文大小上限為 1 MB。

如果您想要傳送大於 1 MB 的訊息，請使用服務管理 SDK 搭配 persistent 模式。

分享方式：