Udostępnij za pośrednictwem

Powiązania usługi Azure Service Bus dla usługi Azure Functions

  • Artykuł

Usługa Azure Functions integruje się z usługą Azure Service Bus za pośrednictwem wyzwalaczy i powiązań. Integracja z usługą Service Bus umożliwia tworzenie funkcji reagujących na kolejkę lub komunikaty tematu oraz wysyłanie ich.

Akcja Typ
Uruchamianie funkcji po utworzeniu kolejki usługi Service Bus lub komunikatu tematu Wyzwalacz
Wysyłanie komunikatów usługi Azure Service Bus Powiązanie wyjściowe

Instalowanie rozszerzenia

Instalowany pakiet NuGet rozszerzenia zależy od trybu języka C#, którego używasz w aplikacji funkcji:

Funkcje są wykonywane w izolowanym procesie roboczym języka C#. Aby dowiedzieć się więcej, zobacz Przewodnik dotyczący uruchamiania usługi Azure Functions w języku C# w izolowanym procesie roboczym.

Dodaj rozszerzenie do projektu instalujące ten pakiet NuGet.

Funkcjonalność rozszerzenia różni się w zależności od wersji rozszerzenia:

Ta wersja wprowadza możliwość nawiązywania połączenia przy użyciu tożsamości zamiast wpisu tajnego. Aby zapoznać się z samouczkiem dotyczącym konfigurowania aplikacji funkcji przy użyciu tożsamości zarządzanych, zobacz samouczek dotyczący tworzenia aplikacji funkcji z połączeniami opartymi na tożsamościach.

Ta wersja umożliwia powiązanie z typami z pliku Azure.Messaging.ServiceBus.

Ta wersja obsługuje konfigurację wyzwalaczy i powiązań za pośrednictwem integracji platformy .NET Aspire.

Dodaj rozszerzenie do projektu, instalując pakiet NuGet w wersji 5.x.

Instalowanie pakietu

Powiązanie usługi Service Bus jest częścią pakietu rozszerzenia określonego w pliku projektu host.json. Może być konieczne zmodyfikowanie tego pakietu, aby zmienić wersję powiązania lub jeśli pakiety nie zostały jeszcze zainstalowane. Aby dowiedzieć się więcej, zobacz pakiet rozszerzeń.

Ta wersja wprowadza możliwość nawiązywania połączenia przy użyciu tożsamości zamiast wpisu tajnego. Aby zapoznać się z samouczkiem dotyczącym konfigurowania aplikacji funkcji przy użyciu tożsamości zarządzanych, zobacz samouczek dotyczący tworzenia aplikacji funkcji z połączeniami opartymi na tożsamościach.

Tę wersję rozszerzenia można dodać z pakietu rozszerzeń w wersji 3, dodając lub zastępując następujący kod w host.json pliku:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Aby dowiedzieć się więcej, zobacz Aktualizowanie rozszerzeń.

Typy powiązań

Typy powiązań obsługiwane dla platformy .NET zależą zarówno od wersji rozszerzenia, jak i trybu wykonywania języka C#, który może być jednym z następujących elementów:

Izolowana biblioteka klas procesów roboczych skompilowana funkcja języka C# jest uruchamiana w procesie odizolowanym od środowiska uruchomieniowego.

Wybierz wersję, aby wyświetlić szczegóły typu powiązania dla trybu i wersji.

Proces izolowany proces roboczy obsługuje typy parametrów zgodnie z poniższymi tabelami.

Wyzwalacz usługi Service Bus

Jeśli chcesz, aby funkcja przetwarzała pojedynczy komunikat, wyzwalacz usługi Service Bus może powiązać z następującymi typami:

Type Opis
string Komunikat jako ciąg. Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Bajty komunikatu.
Typy serializowalne w formacie JSON Gdy zdarzenie zawiera dane JSON, usługa Functions próbuje wykonać deserializacji danych JSON w zwykły typ obiektu CLR (POCO).
ServiceBusReceivedMessage1 Obiekt komunikatu.

W przypadku powiązania z ServiceBusReceivedMessageusługą można również opcjonalnie dołączyć parametr typu ServiceBusMessageActions 1,2, aby wykonać akcje rozliczenia komunikatów.

Jeśli chcesz, aby funkcja przetwarzała partię komunikatów, wyzwalacz usługi Service Bus może powiązać z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów pojedynczych komunikatów Tablica zdarzeń z partii. Każdy wpis reprezentuje jedno zdarzenie.

W przypadku powiązania z ServiceBusReceivedMessage[]usługą można również opcjonalnie dołączyć parametr typu ServiceBusMessageActions 1,2, aby wykonać akcje rozliczenia komunikatów.

1 Aby użyć tych typów, należy odwołać się do elementów Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 lub nowszych oraz typowych zależności dla powiązań typu zestawu SDK.

2 W przypadku używania ServiceBusMessageActionsparametru ustaw AutoCompleteMessages właściwość atrybutu wyzwalacza na falsewartość . Zapobiega to próbie ukończenia komunikatów przez środowisko uruchomieniowe po pomyślnym wywołaniu funkcji.

Powiązanie wyjściowe usługi Service Bus

Jeśli chcesz, aby funkcja mogła napisać pojedynczy komunikat, powiązanie danych wyjściowych usługi Service Bus może wiązać się z następującymi typami:

Type Opis
string Komunikat jako ciąg. Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Bajty komunikatu.
Typy serializowalne w formacie JSON Obiekt reprezentujący komunikat. Funkcje próbują serializować zwykły typ obiektu CLR (POCO) do danych JSON.

Jeśli chcesz, aby funkcja zapisywała wiele komunikatów, powiązanie danych wyjściowych usługi Service Bus może wiązać się z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów pojedynczych komunikatów Tablica zawierająca wiele komunikatów. Każdy wpis reprezentuje jeden komunikat.

W przypadku innych scenariuszy wyjściowych utwórz obiekt ServiceBusClient i użyj go bezpośrednio z poziomu klasy Azure.Messaging.ServiceBus. Zobacz Rejestrowanie klientów platformy Azure, aby zapoznać się z przykładem użycia wstrzykiwania zależności w celu utworzenia typu klienta z zestawu Azure SDK.

ustawienia host.json

W tej sekcji opisano ustawienia konfiguracji dostępne dla tego powiązania, które zależą od środowiska uruchomieniowego i wersji rozszerzenia.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

Ustawienia clientRetryOptions dotyczą tylko interakcji z usługą Service Bus. Nie mają one wpływu na ponawianie prób wykonywania funkcji. Aby uzyskać więcej informacji, zobacz Ponowne próby.

Właściwości Domyślny opis
tryb Exponential Podejście do obliczania opóźnień ponawiania prób. Domyślny tryb wykładniczy ponawia próby z opóźnieniem w oparciu o strategię wycofywania, w której każda próba zwiększa czas trwania oczekiwania przed ponowną próbą. Tryb Fixed ponawia próby w stałych odstępach czasu z każdym opóźnieniem o stałym czasie trwania.
tryTimeout 00:01:00 Maksymalny czas trwania oczekiwania na operację na próbę.
zwłoka 00:00:00.80 Współczynnik opóźnienia lub wycofywania, który ma być stosowany między ponownymi próbami.
maxDelay 00:01:00 Maksymalne opóźnienie między próbami ponawiania prób
maxRetries 3 Maksymalna liczba ponownych prób przed rozważeniem skojarzonej operacji zakończyła się niepowodzeniem.
prefetchCount 0 Pobiera lub ustawia liczbę komunikatów, których odbiorca komunikatów może jednocześnie żądać.
transportType amqpTcp Protokół i transport używany do komunikacji z usługą Service Bus. Dostępne opcje: amqpTcp, amqpWebSockets
webProxy nie dotyczy Serwer proxy do komunikacji z usługą Service Bus za pośrednictwem gniazd internetowych. Nie można używać serwera proxy z transportem amqpTcp .
autoUzupełnianieKomunikaty true Określa, czy automatycznie ukończyć komunikaty po pomyślnym wykonaniu funkcji.
maxAutoLockRenewalDuration 00:05:00 Maksymalny czas trwania, w którym blokada komunikatu zostanie odnowiona automatycznie. To ustawienie dotyczy tylko funkcji, które odbierają jeden komunikat jednocześnie.
maxConcurrentCalls 16 Maksymalna liczba współbieżnych wywołań wywołań zwrotnych, które powinny być inicjowane na wystąpienie skalowane. Domyślnie środowisko uruchomieniowe usługi Functions przetwarza wiele komunikatów jednocześnie. To ustawienie jest używane tylko wtedy, gdy isSessionsEnabled właściwość lub atrybut w wyzwalaczu ma wartość false. To ustawienie dotyczy tylko funkcji, które odbierają jeden komunikat jednocześnie.
maxConcurrentSessions 8 Maksymalna liczba sesji, które mogą być obsługiwane współbieżnie na wystąpienie skalowane. To ustawienie jest używane tylko wtedy, gdy isSessionsEnabled właściwość lub atrybut w wyzwalaczu ma wartość true. To ustawienie dotyczy tylko funkcji, które odbierają jeden komunikat jednocześnie.
maxMessageBatchSize 1000 Maksymalna liczba komunikatów, które zostaną przekazane do każdego wywołania funkcji. To ustawienie dotyczy tylko funkcji, które odbierają partię komunikatów.
minMessageBatchSize1 1 Minimalna liczba komunikatów żądanych w partii. Minimalna wartość ma zastosowanie tylko wtedy, gdy funkcja odbiera wiele komunikatów i musi być mniejsza niż maxMessageBatchSize.
Minimalny rozmiar nie jest ściśle gwarantowany. Częściowa partia jest wysyłana, gdy nie można przygotować pełnej partii przed upływem maxBatchWaitTime .
maxBatchWaitTime1 00:00:30 Maksymalny interwał, który wyzwalacz powinien czekać na wypełnienie partii przed wywołaniem funkcji. Czas oczekiwania jest brany pod uwagę tylko wtedy, gdy minMessageBatchSize jest większy niż 1 i jest ignorowany w przeciwnym razie. minMessageBatchSize Jeśli komunikaty były dostępne przed upływem czasu oczekiwania, funkcja jest wywoływana z częściową partią. Najdłuższy dozwolony czas oczekiwania wynosi 50% czasu trwania blokady komunikatu jednostki, co oznacza, że maksymalna dozwolona wartość to 2 minuty i 30 sekund. W przeciwnym razie mogą wystąpić wyjątki blokady.

UWAGA: Ten interwał nie jest ścisłą gwarancją dokładnego czasu wywoływania funkcji. Istnieje niewielki margines błędu ze względu na precyzję czasomierza.
sessionIdleTimeout nie dotyczy Maksymalny czas oczekiwania na odebranie komunikatu dla aktualnie aktywnej sesji. Po upływie tego czasu sesja zostanie zamknięta, a funkcja podejmie próbę przetworzenia innej sesji.
enableCrossEntityTransactions false Czy włączyć transakcje obejmujące wiele jednostek w przestrzeni nazw usługi Service Bus.

1 Używanie pakietu minMessageBatchSize i maxBatchWaitTime wymaga wersji 5.10.0 Microsoft.Azure.WebJobs.Extensions.ServiceBus pakietu lub nowszej.

Następne kroki