Dokumentacja interfejsu API REST płaszczyzny danych usługi Azure Web PubSub

Jak pokazano na powyższym wykresie przepływu pracy, a także szczegółowy przepływ pracy opisany w elementach wewnętrznych, serwer aplikacji może wysyłać komunikaty do klientów lub zarządzać połączonymi klientami przy użyciu interfejsów API REST uwidocznionych przez usługę Web PubSub. W tym artykule szczegółowo opisano interfejsy API REST.

Korzystanie z interfejsu API REST

Nazwy grup i identyfikatory użytkowników w ścieżkach żądań

Operacje REST, które zawierają nazwę grupy lub identyfikator użytkownika w ścieżce żądania, mają ograniczenie dotyczące ukośników (/) w tych wartościach. Kodowanie ukośnika w URL może %2F nie rozwiązać ograniczenia: operacja może nie adresować zamierzonej grupy lub użytkownika. Na przykład klient połączony z ID tenant/alice użytkownika może nie zostać znaleziony przez żądanie REST, którego ścieżka zawiera /users/tenant%2Falice.

To ograniczenie dotyczy operacji wykorzystujących te parametry ścieżki, takich jak wysyłanie wiadomości, sprawdzanie istnienia grupy lub użytkownika, zamykanie połączeń oraz zarządzanie członkostwem w grupie. Metody serwera SDK, które wywołują te punkty końcowe REST, podlegają tym samym ograniczeniom. Jest to ograniczenie ścieżki żądań REST, a nie ogólne zakazy dotyczące / nazw grup Web PubSub czy identyfikatorów użytkowników.

Aby uniknąć tego ograniczenia, używaj nazw grup i identyfikatorów użytkowników bez / tych operacji REST. Jeśli identyfikatory Twojej aplikacji zawierają /, przypisuj je do unikalnych, bezukośniczych identyfikatorów i konsekwentnie używaj tych wartości w tokenach dostępu klienta, członkostwie w grupach oraz wywołaniach REST. Zmiana tylko wartości w żądaniu REST nie zmienia identyfikatora użytkownika ani nazwy grupy powiązanej z istniejącym połączeniem.

Uwierzytelnianie za pośrednictwem usługi Azure Web PubSub Service AccessKey

W każdym żądaniu HTTP do uwierzytelniania w usłudze Azure Web PubSub 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.

Powinieneś użyć AccessKey parametry połączenia instancji Azure Web PubSub Service, aby podpisać wygenerowany JWT.

Roszczenia

Poniżej roszczenia muszą być uwzględnione w JWT.

Przykładowy kod w języku JS:

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Użyj usługi Azure Key Vault, aby bezpiecznie zarządzać kluczami i obracać je oraz zabezpieczać połączenie za pomocą usługi WebPubSubServiceClient.

const bearerToken = jwt.sign({}, connectionString.accessKey, {
  audience: request.url,
  expiresIn: "1h",
  algorithm: "HS256",
});

Uwierzytelnianie za pośrednictwem tokenu entra firmy Microsoft

Podobnie jak w przypadku korzystania z AccessKeyprotokołu , do uwierzytelniania żądania HTTP jest również wymagany token internetowy JSON (JWT ).

Różnica polega na tym, że w tym scenariuszu JWT jest generowany przez Microsoft Entra ID.

Dowiedz się, jak wygenerować tokeny usługi Microsoft Entra

Używany zakres poświadczeń powinien mieć wartość https://webpubsub.azure.com/.default.

Możesz również użyć kontroli dostępu opartej na rolach (RBAC), aby autoryzować żądanie z serwera do usługi Azure Web PubSub Service.

Dowiedz się, jak dodawać przypisania ról

Interfejsy API