Udostępnij za pośrednictwem

Dokumentacja interfejsu API REST płaszczyzny danych usługi Azure SignalR Service

  • Artykuł

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.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • 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 Status Port Dokumentacja Specyfikacja
20220601 Najnowsze Standardowy Artykuł Plik struktury Swagger
1.0 Stable Standardowy Artykuł Plik struktury Swagger
1.0-preview Przestarzałe Standardowy Artykuł Plik struktury Swagger

W poniższej tabeli wymieniono dostępne interfejsy API.

Interfejs API Ścieżka
Emisja komunikatu do wszystkich klientów połączonych z koncentratorem docelowym POST /api/v1/hubs/{hub}
Emisja komunikatu do wszystkich klientów należy do użytkownika docelowego POST /api/v1/hubs/{hub}/users/{id}
Wysyłanie komunikatu do określonego połączenia POST /api/v1/hubs/{hub}/connections/{connectionId}
Sprawdź, czy istnieje połączenie z danym identyfikatorem connectionId GET /api/v1/hubs/{hub}/connections/{connectionId}
Zamykanie połączenia klienta DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Emisja komunikatu do wszystkich klientów w grupie docelowej POST /api/v1/hubs/{hub}/groups/{group}
Sprawdź, czy w danej grupie istnieją jakiekolwiek połączenia klienckie GET /api/v1/hubs/{hub}/groups/{group}
Sprawdź, czy istnieją połączenia klienta połączone dla danego użytkownika GET /api/v1/hubs/{hub}/users/{user}
Dodawanie połączenia z grupą docelową PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Usuwanie połączenia z grupy docelowej DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Sprawdzanie, czy użytkownik istnieje w grupie docelowej GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Dodawanie użytkownika do grupy docelowej PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Usuwanie użytkownika z grupy docelowej DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Usuwanie użytkownika ze wszystkich grup DELETE /api/v1/hubs/{hub}/users/{user}/groups

Korzystanie z interfejsu API REST

Uwierzytelnianie za pomocą klawisza 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 AccessKeyusł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.

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.

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 .