Programowanie i konfigurowanie w usłudze Azure Functions za pomocą usługi Azure SignalR Service
Artykuł
Aplikacje usługi Azure Functions mogą używać powiązań usługi Azure SignalR Service do dodawania możliwości w czasie rzeczywistym. Aplikacje klienckie używają zestawów SDK klienta dostępnych w kilku językach do nawiązywania połączenia z usługą Azure SignalR Service i odbierania komunikatów w czasie rzeczywistym.
W tym artykule opisano pojęcia dotyczące tworzenia i konfigurowania aplikacji funkcji platformy Azure zintegrowanej z usługą SignalR Service.
Ważne
Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych.
Parametry połączenia zawiera informacje o autoryzacji wymagane do uzyskania dostępu do usługi Azure SignalR Service przez aplikację. Klucz dostępu wewnątrz parametry połączenia jest podobny do hasła głównego usługi. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich oraz zabezpieczanie parametry połączenia przy użyciu identyfikatora Entra firmy Microsoft i autoryzowania dostępu za pomocą identyfikatora Entra firmy Microsoft.
Unikaj dystrybuowania kluczy dostępu do innych użytkowników, kodowania ich lub zapisywania ich w dowolnym miejscu w postaci zwykłego tekstu, który jest dostępny dla innych użytkowników. Obracanie kluczy, jeśli uważasz, że mogły one zostać naruszone.
Konfiguracja usługi SignalR Service
Usługę Azure SignalR Service można skonfigurować w różnych trybach. W przypadku korzystania z usługi Azure Functions usługa musi być skonfigurowana w trybie bezserwerowym .
W witrynie Azure Portal znajdź stronę Ustawienia zasobu usługi SignalR Service. Ustaw tryb usługi na bezserwerowy.
Opracowywanie usługi Azure Functions
Bezserwerowa aplikacja w czasie rzeczywistym utworzona za pomocą usług Azure Functions i Azure SignalR Service wymaga co najmniej dwóch funkcji platformy Azure:
Funkcja wywoływana negotiate przez klienta w celu uzyskania prawidłowego tokenu dostępu usługi SignalR Service i adresu URL punktu końcowego.
Co najmniej jedna funkcja, która obsługuje komunikaty wysyłane z usługi SignalR Service do klientów.
Funkcja negocjacji
Aplikacja kliencka wymaga prawidłowego tokenu dostępu w celu nawiązania połączenia z usługą Azure SignalR Service. Token dostępu może być anonimowy lub uwierzytelniony w identyfikatorze użytkownika. Aplikacje usługi SignalR Service bezserwerowe wymagają punktu końcowego HTTP o nazwie negotiate w celu uzyskania tokenu i innych informacji o połączeniu, takich jak adres URL punktu końcowego usługi SignalR Service.
Użyj funkcji platformy Azure wyzwalanej przez protokół HTTP i powiązania wejściowego SignalRConnectionInfo , aby wygenerować obiekt informacji o połączeniu. Funkcja musi mieć trasę HTTP kończącą się na ./negotiate
W przypadku modelu opartego na klasach w języku C#nie potrzebujesz SignalRConnectionInfo powiązania danych wejściowych i możesz znacznie łatwiej dodawać oświadczenia niestandardowe. Aby uzyskać więcej informacji, zobacz Środowisko negocjacji w modelu opartym na klasach.
Aby uzyskać więcej informacji na temat negotiate funkcji, zobacz Programowanie w usłudze Azure Functions.
Obsługa komunikatów wysyłanych z usługi SignalR Service
SignalRTrigger Użyj powiązania do obsługi komunikatów wysyłanych z usługi SignalR Service. Powiadomienia można otrzymywać, gdy klienci wysyłają komunikaty lub klienci są połączeni lub rozłączeni.
Aby uzyskać więcej informacji, zobacz dokumentację powiązania wyzwalacza usługi SignalR Service.
Należy również skonfigurować punkt końcowy funkcji jako nadrzędny punkt końcowy, aby usługa wyzwalała funkcję w przypadku wystąpienia komunikatu od klienta. Aby uzyskać więcej informacji na temat konfigurowania nadrzędnych punktów końcowych, zobacz Upstream endpoints (Nadrzędne punkty końcowe).
Uwaga
Usługa SignalR Service nie obsługuje komunikatu StreamInvocation z klienta w trybie bezserwerowym.
Wysyłanie komunikatów i zarządzanie członkostwem w grupie
Użyj powiązania wyjściowego SignalR , aby wysyłać komunikaty do klientów połączonych z usługą Azure SignalR Service. Komunikaty można emitować do wszystkich klientów lub wysyłać je do podzbioru klientów. Na przykład wysyłaj komunikaty tylko do klientów uwierzytelnionych przy użyciu określonego identyfikatora użytkownika lub tylko do określonej grupy.
Użytkownicy mogą być dodawani do co najmniej jednej grupy. Możesz również użyć powiązania danych wyjściowych SignalR , aby dodać lub usunąć użytkowników do/z grup.
Usługa SignalR ma koncepcję koncentratorów. Każde połączenie klienta i każdy komunikat wysyłany z usługi Azure Functions ma zakres do określonego centrum. Koncentratory mogą służyć jako sposób oddzielania połączeń i komunikatów do logicznych przestrzeni nazw.
Model oparty na klasach
Model oparty na klasach jest przeznaczony dla języka C#.
Model oparty na klasach zapewnia lepsze środowisko programowania, które może zastąpić powiązania wejściowe i wyjściowe usługi SignalR następującymi funkcjami:
Bardziej elastyczne negocjacje, wysyłanie komunikatów i zarządzanie środowiskami grup.
Obsługiwane są więcej funkcji zarządzania, w tym zamykanie połączeń, sprawdzanie, czy istnieje połączenie, użytkownik lub grupa.
Silnie typizowane centrum
Ujednolicona nazwa centrum i ustawienie parametry połączenia w jednym miejscu.
Poniższy kod przedstawia sposób pisania powiązań usługi SignalR w modelu opartym na klasach:
Najpierw zdefiniuj centrum pochodzące z klasy ServerlessHub:
W pliku Program.cs zarejestruj centrum bezserwerowe:
cs
var host = new HostBuilder()
.ConfigureFunctionsWorkerDefaults(b => b.Services
.AddServerlessHub<Functions>())
.Build();
Doświadczenie negocjacji w modelu opartym na klasach
Zamiast używać powiązania [SignalRConnectionInfoInput]wejściowego usługi SignalR, negocjacje w modelu opartym na klasach mogą być bardziej elastyczne. Klasa ServerlessHub podstawowa ma metodę NegotiateAsync, która umożliwia użytkownikom dostosowywanie opcji negocjacji, takich jak userId, claimsitp.
Wysyłanie komunikatów i zarządzanie środowiskiem w modelu opartym na klasach
Możesz wysyłać komunikaty, zarządzać grupami lub zarządzać klientami, korzystając z elementów członkowskich dostarczonych przez klasę ServerlessHubbazową .
ServerlessHub.Clients do wysyłania komunikatów do klientów.
ServerlessHub.Groups do zarządzania połączeniami z grupami, takimi jak dodawanie połączeń do grup, usuwanie połączeń z grup.
ServerlessHub.UserGroups do zarządzania użytkownikami przy użyciu grup, takich jak dodawanie użytkowników do grup, usuwanie użytkowników z grup.
ServerlessHub.ClientManager do sprawdzania istnienia połączeń, zamykania połączeń itp.
Centrum silnie typizowane
Silnie typizowane centrum umożliwia używanie silnie typiowanych metod podczas wysyłania komunikatów do klientów. Aby użyć silnie typizowanego centrum w modelu opartym na klasach, wyodrębnij metody klienta do interfejsu Ti utwórz klasę centrum pochodzącą z ServerlessHub<T>klasy .
Poniższy kod jest przykładem interfejsu dla metod klienta.
Umożliwia dostosowanie miejsca, w którym znajduje się parametry połączenia dla koncentratora bezserwerowego. Jeśli jest nieobecny, zostanie użyta wartość AzureSignalRConnectionString domyślna.
Ważne
Wyzwalacze usługi SignalR i koncentratory bezserwerowe są niezależne. W związku z tym nazwa klasy bezserwerowego centrum i SignalRConnection atrybutu nie zmienia ustawień wyzwalaczy usługi SignalR, mimo że używasz wyzwalaczy SignalR wewnątrz bezserwerowego koncentratora.
Model oparty na klasach zapewnia spójne środowisko programowania po stronie serwera SignalR z następującymi funkcjami:
Mniej pracy konfiguracji: nazwa klasy jest używana jako HubName, nazwa metody jest używana jako Event, a Category parametr jest automatycznie ustalany zgodnie z nazwą metody.
Automatyczne powiązanie parametrów: ParameterNames i atrybut [SignalRParameter] nie są potrzebne. Parametry są automatycznie powiązane z argumentami metod funkcji platformy Azure w kolejności.
Wygodne środowisko danych wyjściowych i negocjacji.
Wszystkie funkcje, które chcą używać modelu opartego na klasach, muszą być metodą klasy dziedziczonej po bezserwerowej usłudzeHub. Nazwa HubName1 klasy w przykładzie to nazwa centrum.
Definiowanie metody koncentratora
Wszystkie metody piasty muszą mieć argument InvocationContext dekorowany przez [SignalRTrigger] atrybut i używać konstruktora bez parametrów.
Następnie nazwa metody jest traktowana jako zdarzenie parametru.
Domyślnie z category=messages wyjątkiem nazwy metody jest jedną z następujących nazw:
OnConnected: traktowane jako category=connections, event=connected
OnDisconnected: traktowane jako category=connections, event=disconnected
Środowisko powiązania parametrów
W modelu opartym na klasie jest niepotrzebny, [SignalRParameter] ponieważ wszystkie argumenty są domyślnie oznaczone jako [SignalRParameter] z wyjątkiem jednej z następujących sytuacji:
Argument jest ozdobiony atrybutem powiązania
Typ argumentu to ILogger lub CancellationToken
Argument jest ozdobiony atrybutem [SignalRIgnore]
Doświadczenie negocjacji w modelu opartym na klasach
Zamiast używać powiązania [SignalR]wejściowego usługi SignalR, negocjacje w modelu opartym na klasach mogą być bardziej elastyczne. Klasa ServerlessHub bazowa ma metodę:
Ta funkcja umożliwia użytkownikowi dostosowywanie userId lub claims wykonywanie funkcji.
Korzystanie z polecenia SignalRFilterAttribute
Użytkownik może dziedziczyć i implementować klasę SignalRFilterAttributeabstrakcyjną . Jeśli wyjątki są zgłaszane w programie FilterAsync, 403 Forbidden zostaną wysłane z powrotem do klientów.
W poniższym przykładzie pokazano, jak zaimplementować filtr klienta, który zezwala admin tylko na wywołanie metody broadcast.
Aplikacje klienckie usługi SignalR mogą używać zestawu SDK klienta SignalR w jednym z kilku języków, aby łatwo łączyć się z usługą Azure SignalR Service i odbierać komunikaty z usługi Azure SignalR Service.
Konfigurowanie połączenia klienta
Aby nawiązać połączenie z usługą SignalR Service, klient musi wykonać pomyślne negocjacje połączenia, które składają się z następujących kroków:
Prześlij żądanie do punktu końcowego HTTP omówionego powyżej, negotiate aby uzyskać prawidłowe informacje o połączeniu
Nawiązywanie połączenia z usługą SignalR Service przy użyciu adresu URL punktu końcowego usługi i tokenu dostępu uzyskanego z punktu końcowego negotiate
Zestawy SDK klienta usługi SignalR zawierają już logikę wymaganą do wykonania uzgadniania negocjacji. Przekaż adres URL punktu końcowego negocjacji, minus negotiate segment, do zestawu HubConnectionBuilderSDK . Oto przykład w języku JavaScript:
JavaScript
const connection = new signalR.HubConnectionBuilder()
.withUrl("https://my-signalr-function-app.azurewebsites.net/api")
.build();
Zgodnie z konwencją zestaw SDK automatycznie dołącza /negotiate do adresu URL i używa go do rozpoczęcia negocjacji.
Jeśli skonfigurowano nadrzędny zasób usługi SignalR, możesz wysyłać komunikaty z klienta do usługi Azure Functions przy użyciu dowolnego klienta usługi SignalR. Oto przykład w języku JavaScript:
JavaScript
connection.send("method1", "arg1", "arg2");
Konfiguracja usługi Azure Functions
Aplikacje funkcji platformy Azure, które integrują się z usługą Azure SignalR Service, można wdrażać jak każda typowa aplikacja funkcji platformy Azure, korzystając z technik, takich jak ciągłe wdrażanie, wdrażanie zip i uruchamianie z pakietu.
Istnieje jednak kilka szczególnych zagadnień dotyczących aplikacji korzystających z powiązań usługi SignalR Service. Jeśli klient działa w przeglądarce, należy włączyć mechanizm CORS. Jeśli aplikacja wymaga uwierzytelniania, możesz zintegrować punkt końcowy negocjacji z uwierzytelnianiem usługi App Service.
Włączanie mechanizmu CORS
Klient JavaScript/TypeScript wysyła żądanie HTTP do funkcji negocjacji w celu zainicjowania negocjacji połączenia. Jeśli aplikacja kliencka jest hostowana w innej domenie niż aplikacja funkcji platformy Azure, udostępnianie zasobów między źródłami (CORS) musi być włączone w aplikacji funkcji lub przeglądarka zablokuje żądania.
Host lokalny
Podczas uruchamiania aplikacji funkcji na komputerze lokalnym można dodać sekcję Host do local.settings.json , aby włączyć mechanizm CORS.
Host W sekcji dodaj dwie właściwości:
CORS — wprowadź podstawowy adres URL, który jest źródłem aplikacji klienckiej
CORSCredentials — ustaw ją tak, aby true zezwalała na żądania "withCredentials"
Aby włączyć mechanizm CORS w aplikacji funkcji platformy Azure, przejdź do ekranu konfiguracji mechanizmu CORS na karcie Funkcje platformy aplikacji funkcji w witrynie Azure Portal.
Uwaga
Konfiguracja mechanizmu CORS nie jest jeszcze dostępna w planie użycia systemu Linux usługi Azure Functions. Użyj usługi Azure API Management , aby włączyć mechanizm CORS.
Mechanizm CORS z poświadczeniami Access-Control-Allow-Credentials musi być włączony, aby klient usługi SignalR mógł wywołać funkcję negocjacji. Aby ją włączyć, zaznacz pole wyboru.
W sekcji Dozwolone źródła dodaj wpis z podstawowym adresem URL aplikacji internetowej.
Chmura — Azure API Management
Usługa Azure API Management udostępnia bramę interfejsu API, która dodaje możliwości do istniejących usług zaplecza. Można go użyć do dodawania mechanizmu CORS do aplikacji funkcji. Oferuje warstwę zużycia z cenami płatności za akcję i miesięcznym bezpłatnym przyznaniem.
Zapoznaj się z dokumentacją usługi API Management, aby uzyskać informacje na temat importowania aplikacji funkcji platformy Azure. Po zaimportowaniu można dodać zasady ruchu przychodzącego, aby włączyć mechanizm CORS z obsługą mechanizmu ACCESS-Control-Allow-Credentials.
Skonfiguruj klientów usługi SignalR tak, aby używali adresu URL usługi API Management.
Korzystanie z uwierzytelniania usługi App Service
Usługa Azure Functions ma wbudowane uwierzytelnianie, które obsługuje popularnych dostawców, takich jak Facebook, X, Konto Microsoft, Google i Microsoft Entra ID. Tę funkcję można zintegrować z powiązaniem SignalRConnectionInfo , aby utworzyć połączenia z usługą Azure SignalR Service uwierzytelnioną w identyfikatorze użytkownika. Aplikacja może wysyłać komunikaty przy użyciu SignalR powiązania danych wyjściowych, które są przeznaczone dla tego identyfikatora użytkownika.
W witrynie Azure Portal na karcie Funkcje platformy aplikacji funkcji otwórz okno Ustawienia uwierzytelniania/autoryzacji. Postępuj zgodnie z dokumentacją uwierzytelniania usługi App Service, aby skonfigurować uwierzytelnianie przy użyciu wybranego dostawcy tożsamości.
Po skonfigurowaniu uwierzytelnione żądania HTTP zawierają x-ms-client-principal-name odpowiednio x-ms-client-principal-id i nagłówki zawierające nazwę użytkownika i identyfikator użytkownika tożsamości uwierzytelnionej.
Te nagłówki można użyć w konfiguracji powiązania, SignalRConnectionInfo aby utworzyć uwierzytelnione połączenia. Oto przykładowa funkcja negocjacji języka C#, która używa nagłówka x-ms-client-principal-id .
C#
[FunctionName("negotiate")]
publicstatic SignalRConnectionInfo Negotiate(
[HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
[SignalRConnectionInfo
(HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
SignalRConnectionInfo connectionInfo)
{
// connectionInfo contains an access key token with a name identifier claim set to the authenticated userreturn connectionInfo;
}
Następnie możesz wysyłać komunikaty do tego użytkownika, ustawiając UserId właściwość komunikatu usługi SignalR.
C#
[FunctionName("SendMessage")]
publicstatic Task SendMessage(
[HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
[SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
return signalRMessages.AddAsync(
new SignalRMessage
{
// the message will only be sent to these user IDs
UserId = "userId1",
Target = "newMessage",
Arguments = new [] { message }
});
}
Aby uzyskać informacje na temat innych języków, zobacz dokumentację powiązań usługi Azure SignalR Service dla usługi Azure Functions.
Następne kroki
Z tego artykułu dowiesz się, jak opracowywać i konfigurować bezserwerowe aplikacje usługi SignalR Service przy użyciu usługi Azure Functions. Spróbuj samodzielnie utworzyć aplikację przy użyciu jednego z przewodników Szybki start lub samouczków na stronie przeglądu usługi SignalR Service.
Cambiare un meccanismo di aggiornamento di un'app Web JavaScript da un'architettura di polling a una basata su push in tempo reale con il Servizio SignalR, Azure Cosmos DB e Funzioni di Azure. Usare Vue.js e JavaScript per usare SignalR con Visual Studio Code.
Progettare soluzioni end-to-end in Microsoft Azure per creare Funzioni di Azure, implementare e gestire app Web, sviluppare soluzioni che usano Archiviazione di Azure e altro ancora.