Sdílet prostřednictvím

Referenční informace k rozhraní REST API služby Azure SignalR Service

  • Článek

Kromě modelu klasického klienta nebo serveru poskytuje služba Azure SignalR sadu rozhraní REST API, která vám pomůžou integrovat funkce v reálném čase do architektury bez serveru.

Poznámka:

Služba Azure SignalR podporuje použití rozhraní REST API pouze ke správě klientů připojených prostřednictvím služby ASP.NET Core SignalR. Klienti připojení přes ASP.NET SignalR používají jiný datový protokol, který se v současné době nepodporuje.

Typická architektura bez serveru se službou Azure Functions

Následující diagram znázorňuje typickou architekturu bez serveru, která používá službu Azure SignalR se službou Azure Functions.

Diagram typické bezserverové architektury pro službu Azure SignalR

  • Funkce negotiate vrátí odpověď vyjednávání a přesměruje všechny klienty do služby Azure SignalR.
  • Funkce broadcast volá rozhraní REST API pro službu Azure SignalR. Služba Azure SignalR vysílá zprávu všem připojeným klientům.

V bezserverové architektuře mají klienti trvalé připojení ke službě Azure SignalR. Vzhledem k tomu, že neexistuje žádný aplikační server pro zpracování provozu, klienti jsou v LISTEN režimu. V takovém režimu můžou klienti přijímat zprávy, ale nemůžou posílat zprávy. Služba Azure SignalR odpojí všechny klienty, kteří odesílají zprávy, protože se jedná o neplatnou operaci.

Kompletní ukázku použití služby Azure SignalR s Azure Functions najdete v tomto úložišti GitHubu.

Implementace koncového bodu vyjednávání

Měli byste implementovat negotiate funkci, která vrací odpověď na vyjednávání přesměrování, aby se klienti mohli připojit ke službě.

Typická odpověď na vyjednávání má tento formát:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

Hodnota accessToken se generuje pomocí stejného algoritmu popsaného v části ověřování. Jediným rozdílem je, že aud deklarace identity by měla být stejná jako url.

Rozhraní API https://<hub_url>/negotiate pro vyjednávání byste měli hostovat, abyste se stále mohli pomocí klienta SignalR připojit k adrese URL centra. Přečtěte si další informace o přesměrování klientů do služby Azure SignalR v klientských připojeních.

Verze rozhraní REST API

Následující tabulka uvádí všechny podporované verze rozhraní REST API. Poskytuje také soubor Swagger pro každou verzi rozhraní API.

Verze rozhraní API Stav Port Dokumentace Specifikace
20220601 Nejpozdější Standard Článek Soubor Swagger
1.0 Stable Standard Článek Soubor Swagger
1.0-preview Zastaralé Standard Článek Soubor Swagger

Následující tabulka uvádí dostupná rozhraní API.

rozhraní API Cesta
Vysílání zprávy všem klientům připojeným k cílovému centru POST /api/v1/hubs/{hub}
Vysílání zprávy všem klientům patří cílovému uživateli POST /api/v1/hubs/{hub}/users/{id}
Odeslání zprávy ke konkrétnímu připojení POST /api/v1/hubs/{hub}/connections/{connectionId}
Zkontrolujte, jestli připojení s daným ID připojení existuje. GET /api/v1/hubs/{hub}/connections/{connectionId}
Zavření připojení klienta DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Vysílání zprávy všem klientům v cílové skupině POST /api/v1/hubs/{hub}/groups/{group}
Zkontrolujte, jestli v dané skupině nejsou nějaká klientská připojení. GET /api/v1/hubs/{hub}/groups/{group}
Zkontrolujte, jestli pro daného uživatele nejsou připojená nějaká připojení klientů. GET /api/v1/hubs/{hub}/users/{user}
Přidání připojení k cílové skupině PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Odebrání připojení z cílové skupiny DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Kontrola, jestli uživatel v cílové skupině existuje GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Přidání uživatele do cílové skupiny PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Odebrání uživatele z cílové skupiny DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Odebrání uživatele ze všech skupin DELETE /api/v1/hubs/{hub}/users/{user}/groups

S využitím REST API

Ověřování prostřednictvím přístupového klíče ve službě Azure SignalR

V každém požadavku HTTP se k ověření ve službě Azure SignalR vyžaduje autorizační hlavička s webovým tokenem JSON (JWT ).

Podpisový algoritmus a podpis

HS256, konkrétně HMAC-SHA256, se používá jako podpisový algoritmus.

AccessKey K podepsání vygenerovaného JWT použijte hodnotu v připojovací řetězec instance služby Azure SignalR Service.

Žádosti

Následující deklarace identity musí být zahrnuty do JWT.

Typ deklarace identity Je povinné Popis
aud true Musí být stejná jako adresa URL požadavku HTTP, nikoli koncové lomítko a parametry dotazu. Například cílová skupina požadavku vysílání by měla vypadat takto: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Epocha čas vypršení platnosti tohoto tokenu.

Ověřování prostřednictvím tokenu Microsoft Entra

Podobně jako ověřování prostřednictvím AccessKey, JWT se vyžaduje k ověření požadavku HTTP pomocí tokenu Microsoft Entra.

Rozdíl je v tom, že v tomto scénáři generuje ID Microsoft Entra JWT. Další informace najdete v tématu Informace o generování tokenů Microsoft Entra.

Použitý obor přihlašovacích údajů by měl být https://signalr.azure.com/.default.

K autorizaci požadavku z klienta nebo serveru do služby Azure SignalR můžete také použít řízení přístupu na základě role (RBAC ). Další informace naleznete v tématu Autorizace přístupu pomocí Microsoft Entra ID pro službu Azure SignalR.

Pokud chcete volat rozhraní REST API související s uživatelem, měli by se všichni klienti identifikovat ve službě Azure SignalR. Jinak služba Azure SignalR nemůže najít cílová připojení z ID uživatele.

Identifikaci klienta můžete dosáhnout zahrnutím nameid deklarace identity do JWT každého klienta, když se připojuje ke službě Azure SignalR. Služba Azure SignalR pak použije hodnotu nameid deklarace identity jako ID uživatele pro každé připojení klienta.

Vzorek

V tomto úložišti GitHubu najdete úplnou konzolovou aplikaci, která předvádí ruční sestavení požadavku HTTP rozhraní REST API ve službě Azure SignalR.

Pomocí microsoft.Azure.SignalR.Management můžete také publikovat zprávy do služby Azure SignalR pomocí podobných IHubContextrozhraní . Ukázky najdete v tomto úložišti GitHub. Další informace najdete v tématu Sada SDK pro správu služby Azure SignalR.

Omezení

Požadavky rozhraní REST API v současné době mají následující omezení:

  • Velikost záhlaví je maximálně 16 kB.
  • Velikost těla je maximálně 1 MB.

Pokud chcete odesílat zprávy větší než 1 MB, použijte sadu SDK pro správu služeb s režimem persistent .