Dokumentacja interfejsu API REST płaszczyzny danych usługi Azure SignalR Service
Oprócz klasycznego wzorca klienta/serwera usługa Azure SignalR Service udostępnia zestaw interfejsów API REST, które ułatwiają integrację funkcji czasu rzeczywistego z architekturą bezserwerową.
Uwaga
Usługa Azure SignalR Service obsługuje używanie interfejsów API REST tylko do zarządzania klientami połączonymi za pośrednictwem usługi ASP.NET Core SignalR. Klienci połączeni za pośrednictwem usługi ASP.NET SignalR używają innego protokołu danych, który nie jest obecnie obsługiwany.
Typowa architektura bezserwerowa w usłudze Azure Functions
Na poniższym diagramie przedstawiono typową architekturę bezserwerową korzystającą z usługi Azure SignalR Service z usługą Azure Functions.
- Funkcja
negotiate
zwraca odpowiedź na negocjacje i przekierowuje wszystkich klientów do usługi Azure SignalR Service. - Funkcja
broadcast
wywołuje interfejs API REST dla usługi Azure SignalR Service. Usługa Azure SignalR Service rozgłasza komunikat do wszystkich połączonych klientów.
W architekturze bezserwerowej klienci mają trwałe połączenia z usługą Azure SignalR Service. Ponieważ nie ma serwera aplikacji do obsługi ruchu, klienci są w LISTEN
trybie. W tym trybie klienci mogą odbierać komunikaty, ale nie mogą wysyłać komunikatów. Usługa Azure SignalR Service rozłącza dowolnego klienta, który wysyła komunikaty, ponieważ jest to nieprawidłowa operacja.
Pełny przykład użycia usługi Azure SignalR Service z usługą Azure Functions można znaleźć w tym repozytorium GitHub.
Implementowanie punktu końcowego negocjacji
Należy zaimplementować negotiate
funkcję zwracającą odpowiedź na negocjacje przekierowania, aby klienci mogli łączyć się z usługą.
Typowa odpowiedź negocjacyjna ma następujący format:
{
"url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
"accessToken": "<a typical JWT token>"
}
Wartość accessToken
jest generowana za pomocą tego samego algorytmu opisanego w sekcji uwierzytelniania. Jedyną różnicą jest to, że aud
oświadczenie powinno być takie samo jak url
.
Należy hostować interfejs API negocjacji w programie https://<hub_url>/negotiate
, aby nadal można było nawiązać połączenie z adresem URL centrum za pomocą klienta usługi SignalR. Przeczytaj więcej na temat przekierowywania klientów do usługi Azure SignalR Service w połączeniach klienckich.
Wersje interfejsu API REST
W poniższej tabeli przedstawiono wszystkie obsługiwane wersje interfejsu API REST. Udostępnia również plik struktury Swagger dla każdej wersji interfejsu API.
Wersja interfejsu API | Stan | Port | Dokumentacja | Specyfikacja |
---|---|---|---|---|
20220601 |
Najnowsze | Standardowa | Artykuł | Plik struktury Swagger |
1.0 |
Stable | Standardowa | Artykuł | Plik struktury Swagger |
1.0-preview |
Przestarzałe | Standardowa | Artykuł | Plik struktury Swagger |
W poniższej tabeli wymieniono dostępne interfejsy API.
Korzystanie z interfejsu API REST
Uwierzytelnianie za pomocą AccessKey w usłudze Azure SignalR Service
W każdym żądaniu HTTP do uwierzytelniania w usłudze Azure SignalR Service jest wymagany nagłówek autoryzacji z tokenem internetowym JSON (JWT ).
Algorytm podpisywania i podpis
HS256
, czyli HMAC-SHA256, jest używany jako algorytm podpisywania.
AccessKey
Użyj wartości w parametry połączenia wystąpienia usługi Azure SignalR Service, aby podpisać wygenerowany zestaw JWT.
Roszczenia
W zestawie JWT należy uwzględnić następujące oświadczenia.
Typ oświadczenia | Wymagany | opis |
---|---|---|
aud |
true |
Musi być taki sam jak adres URL żądania HTTP, a nie w tym końcowe ukośnik i parametry zapytania. Na przykład odbiorcy żądania emisji powinni wyglądać następująco: https://example.service.signalr.net/api/v1/hubs/myhub . |
exp |
true |
Czas epoki wygaśnięcia tego tokenu. |
Uwierzytelnianie za pośrednictwem tokenu entra firmy Microsoft
Podobnie jak w przypadku uwierzytelniania za pośrednictwem AccessKey
usługi , do uwierzytelniania żądania HTTP jest wymagane JWT przy użyciu tokenu Entra firmy Microsoft.
Różnica polega na tym, że w tym scenariuszu identyfikator Entra firmy Microsoft generuje JWT. Aby uzyskać więcej informacji, zobacz Dowiedz się, jak wygenerować tokeny entra firmy Microsoft.
Używany zakres poświadczeń powinien mieć wartość https://signalr.azure.com/.default
.
Możesz również użyć kontroli dostępu opartej na rolach (RBAC), aby autoryzować żądanie od klienta lub serwera do usługi Azure SignalR Service. Aby uzyskać więcej informacji, zobacz Autoryzowanie dostępu za pomocą identyfikatora Entra firmy Microsoft dla usługi Azure SignalR Service.
Interfejs API REST związany z użytkownikiem
Aby wywołać interfejs API REST związany z użytkownikiem, każdy z klientów powinien identyfikować się w usłudze Azure SignalR Service. W przeciwnym razie usługa Azure SignalR Service nie może odnaleźć połączeń docelowych z identyfikatora użytkownika.
Identyfikację klienta można osiągnąć, dołączając oświadczenie do zestawu JWT każdego klienta podczas nawiązywania połączenia z usługą nameid
Azure SignalR Service. Następnie usługa Azure SignalR Service używa wartości nameid
oświadczenia jako identyfikatora użytkownika dla każdego połączenia klienta.
Przykład
W tym repozytorium GitHub można znaleźć pełną aplikację konsolową, aby zademonstrować, jak ręcznie utworzyć żądanie HTTP interfejsu API REST w usłudze Azure SignalR Service.
Możesz również użyć usługi Microsoft.Azure.SignalR.Management do publikowania komunikatów w usłudze Azure SignalR Service przy użyciu podobnych interfejsów programu IHubContext
. Przykłady można znaleźć w tym repozytorium GitHub. Aby uzyskać więcej informacji, zobacz Zestaw SDK zarządzania usługą Azure SignalR Service.
Ograniczenia
Obecnie żądania interfejsu API REST mają następujące ograniczenia:
- Rozmiar nagłówka to maksymalnie 16 KB.
- Rozmiar treści wynosi maksymalnie 1 MB.
Jeśli chcesz wysyłać komunikaty większe niż 1 MB, użyj zestawu SDK zarządzania usługami z trybem persistent
.