Udostępnij za pośrednictwem

Omówienie wyzwalacza i powiązań usługi Azure Queue Storage dla usługi Azure Functions

  • Artykuł

Usługa Azure Functions może działać jako nowe komunikaty usługi Azure Queue Storage są tworzone i mogą zapisywać komunikaty w kolejce w ramach funkcji.

Akcja Typ
Uruchamianie funkcji jako zmiany danych magazynu kolejek Wyzwalacz
Zapisywanie komunikatów magazynu kolejek 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.

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 witryny Azure.Storage.Queues.

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.

Korzystanie z interfejsu wiersza polecenia platformy .NET:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Uwaga

Obiekty blob platformy Azure, kolejki platformy Azure i tabele platformy Azure używają teraz oddzielnych rozszerzeń i są przywołyane indywidualnie. Aby na przykład użyć wyzwalaczy i powiązań dla wszystkich trzech usług w aplikacji procesów izolowanych platformy .NET, należy dodać następujące pakiety do projektu:

Wcześniej rozszerzenia dostarczane razem jako Microsoft.Azure.Functions.Worker.Extensions.Storage, wersja 4.x. Ten sam pakiet ma również wersję 5.x, która odwołuje się tylko do podzielonych pakietów dla obiektów blob i kolejek. Podczas uaktualniania odwołań do pakietu ze starszych wersji może być konieczne dodatkowe odwołanie do nowego pakietu NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables . Ponadto podczas odwoływania się do tych nowszych pakietów podzielonych upewnij się, że nie odwołujesz się do starszej wersji połączonego pakietu magazynu, ponieważ spowoduje to konflikty z dwóch definicji tych samych powiązań.

Instalowanie pakietu

Powiązanie usługi Blob Storage 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 zapoznawczej 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. Obsługa powiązań z typami z usługi Azure.Storage.Queues jest dostępna w wersji zapoznawczej.

Wyzwalacz kolejki

Wyzwalacz kolejki może wiązać się z następującymi typami:

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

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

Powiązanie danych wyjściowych kolejki

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

Type Opis
string Zawartość wiadomości jako ciąg. Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Bajty komunikatu.
Typy serializowalne w formacie JSON Obiekt reprezentujący zawartość komunikatu JSON. 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 kolejki 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 zawartość dla wielu komunikatów. Każdy wpis reprezentuje jeden komunikat.

W przypadku innych scenariuszy wyjściowych utwórz obiekt QueueClient i użyj go bezpośrednio z innymi typami z witryny Azure.Storage.Queues. 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 w wersjach 2.x i nowszych. Ustawienia w pliku host.json mają zastosowanie do wszystkich funkcji w wystąpieniu aplikacji funkcji. Poniższy przykładowy plik host.json zawiera tylko ustawienia wersji 2.x+ dla tego powiązania. Aby uzyskać więcej informacji na temat ustawień konfiguracji aplikacji funkcji w wersjach 2.x i nowszych, zobacz host.json dokumentacja usługi Azure Functions.

Uwaga

Aby zapoznać się z dokumentacją host.json w usłudze Functions 1.x, zobacz host.json reference for Azure Functions 1.x (Dokumentacja usługi Azure Functions 1.x).

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Właściwości Domyślny opis
maxPollingInterval 00:01:00 Maksymalny interwał między sondami kolejki. Minimalny interwał to 00:00:00.100 (100 ms). Interwały zwiększają się do maxPollingInterval. Wartość domyślna to maxPollingInterval 00:01:00 (1 min). maxPollingInterval nie może być mniejsza niż 00:00:00.100 (100 ms). W systemie Functions w wersji 2.x lub nowszej typ danych to TimeSpan. W usłudze Functions 1.x jest w milisekundach.
visibilityTimeout (limit czasu widoczności) 00:00:00 Interwał czasu między ponowną próbą w przypadku niepowodzenia przetwarzania komunikatu.
batchSize 16 Liczba komunikatów kolejki pobieranych jednocześnie przez środowisko uruchomieniowe usługi Functions i przetwarza je równolegle. Gdy przetwarzany numer jest w dół do newBatchThreshold, środowisko uruchomieniowe pobiera kolejną partię i rozpoczyna przetwarzanie tych komunikatów. Dlatego maksymalna liczba przetwarzanych współbieżnych komunikatów na funkcję to batchSize plus newBatchThreshold. Ten limit ma zastosowanie oddzielnie do każdej funkcji wyzwalanej przez kolejkę.

Jeśli chcesz uniknąć równoległego wykonywania komunikatów odebranych w jednej kolejce, możesz ustawić wartość batchSize 1. To ustawienie eliminuje jednak współbieżność, o ile aplikacja funkcji działa tylko na jednej maszynie wirtualnej. Jeśli aplikacja funkcji skaluje się w poziomie do wielu maszyn wirtualnych, każda maszyna wirtualna może uruchomić jedno wystąpienie każdej funkcji wyzwalanej w kolejce.

Maksymalna wartość batchSize to 32.
maxDequeueCount 5 Liczba prób przetworzenia komunikatu przed przeniesieniem go do kolejki trucizny.
newBatchThreshold N*batchSize/2 Za każdym razem, gdy liczba przetwarzanych jednocześnie komunikatów spadnie do tej liczby, środowisko uruchomieniowe pobiera kolejną partię.

N reprezentuje liczbę procesorów wirtualnych dostępnych podczas uruchamiania w planach usługi App Service lub Premium. Jego wartość jest 1 dla planu zużycia.
messageEncoding base64 To ustawienie jest dostępne tylko w pakiecie rozszerzeń w wersji 5.0.0 lub nowszej. Reprezentuje format kodowania komunikatów. Prawidłowe wartości to base64 i none.

Następne kroki