Udostępnij za pośrednictwem

Powiązania usługi Azure IoT Hub dla usługi Azure Functions

  • Artykuł

W tym zestawie artykułów wyjaśniono, jak pracować z powiązaniami usługi Azure Functions dla usługi IoT Hub. Obsługa usługi IoT Hub jest oparta na powiązaniu usługi Azure Event Hubs.

Ważne

Poniższe przykłady kodu używają interfejsu API centrum zdarzeń, ale dana składnia ma zastosowanie do funkcji usługi IoT Hub.

Akcja Typ
Odpowiadanie na zdarzenia wysyłane do strumienia zdarzeń centrum IoT Hub. Wyzwalacz

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 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

Rozszerzenie usługi Event Hubs 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ć jedną z następujących opcji:

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ązania z typami z witryny Azure.Messaging.EventHubs jest dostępna w wersji zapoznawczej.

Wyzwalacz usługi Event Hubs

Jeśli chcesz, aby funkcja przetwarzała pojedyncze zdarzenie, wyzwalacz usługi Event Hubs może powiązać z następującymi typami:

Type Opis
string Zdarzenie jako ciąg. Użyj polecenia , gdy zdarzenie jest prostym tekstem.
byte[] Bajty zdarzenia.
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).
Azure.Messaging.EventHubs.EventData1 Obiekt zdarzenia.
Jeśli przeprowadzasz migrację ze starszych wersji zestawów SDK usługi Event Hubs, pamiętaj, że ta wersja nie obsługuje starszego Body typu na rzecz elementu EventBody.

Jeśli chcesz, aby funkcja przetwarzała partię zdarzeń, wyzwalacz usługi Event Hubs może powiązać z następującymi typami:

Type Opis
string[] Tablica zdarzeń z partii jako ciągi. Każdy wpis reprezentuje jedno zdarzenie.
EventData[] 1 Tablica zdarzeń z partii, jako wystąpienia azure.Messaging.EventHubs.EventData. Każdy wpis reprezentuje jedno zdarzenie.
T[] gdzie T jest typemserializowalnym JSON 1 Tablica zdarzeń z partii jako wystąpienia niestandardowego typu POCO. Każdy wpis reprezentuje jedno zdarzenie.

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

Powiązanie wyjściowe usługi Event Hubs

Jeśli chcesz, aby funkcja zapisywała pojedyncze zdarzenie, powiązanie danych wyjściowych usługi Event Hubs może wiązać się z następującymi typami:

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

Jeśli chcesz, aby funkcja zapisywała wiele zdarzeń, powiązanie wyjściowe usługi Event Hubs może wiązać się z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów zdarzeń Tablica zawierająca wiele zdarzeń. Każdy wpis reprezentuje jedno zdarzenie.

W przypadku innych scenariuszy wyjściowych utwórz element EventHubProducerClient z innymi typami bezpośrednio z witryny Azure.Messaging.EventHubs i użyj go. 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

Plik host.json zawiera ustawienia sterujące zachowaniem wyzwalacza usługi Event Hubs. Konfiguracja różni się w zależności od wersji rozszerzenia.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Właściwości Domyślny opis
maxEventBatchSize2 100 Maksymalna liczba zdarzeń uwzględnionych w partii dla pojedynczego wywołania. Musi być co najmniej 1.
minEventBatchSize1 1 Minimalna liczba zdarzeń żądanych w partii. Minimalna wartość ma zastosowanie tylko wtedy, gdy funkcja odbiera wiele zdarzeń i musi być mniejsza niż maxEventBatchSize.
Minimalny rozmiar nie jest ściśle gwarantowany. Częściowa partia jest wysyłana, gdy nie można przygotować pełnej partii przed upływem maxWaitTime . Częściowe partie są również prawdopodobnie w przypadku pierwszego wywołania funkcji po przeprowadzeniu skalowania.
maxWaitTime1 00:01:00 Maksymalny interwał, który wyzwalacz powinien czekać na wypełnienie partii przed wywołaniem funkcji. Czas oczekiwania jest brany pod uwagę tylko wtedy, gdy minEventBatchSize jest większy niż 1 i w przeciwnym razie jest ignorowany. Jeśli przed upływem czasu oczekiwania jest dostępna mniejsza niż minEventBatchSize zdarzenia, funkcja jest wywoływana z częściową partią. Najdłuższy dozwolony czas oczekiwania wynosi 10 minut.

UWAGA: Ten interwał nie jest ścisłą gwarancją dokładnego czasu wywoływania funkcji. Istnieje niewielki margines błędu ze względu na precyzję czasomierza. W przypadku skalowania pierwsze wywołanie z częściową partią może wystąpić szybciej lub może zająć do dwóch razy skonfigurowany czas oczekiwania.
batchCheckpointFrequency 1 Liczba partii do przetworzenia przed utworzeniem punktu kontrolnego dla centrum zdarzeń.
prefetchCount 300 Liczba zdarzeń, które są chętnie żądane z usługi Event Hubs i przechowywane w lokalnej pamięci podręcznej w celu umożliwienia odczytu, aby uniknąć oczekiwania na operację sieciową
transportType amqpTcp Protokół i transport używany do komunikacji z usługą Event Hubs. Dostępne opcje: amqpTcp, amqpWebSockets
webProxy null Serwer proxy do komunikacji z usługą Event Hubs za pośrednictwem gniazd internetowych. Nie można używać serwera proxy z transportem amqpTcp .
customEndpointAddress null Adres używany podczas nawiązywania połączenia z usługą Event Hubs, co umożliwia kierowanie żądań sieciowych przez bramę aplikacji lub inną ścieżkę wymaganą dla środowiska hosta. W pełni kwalifikowana przestrzeń nazw centrum zdarzeń jest nadal potrzebna, gdy jest używany niestandardowy adres punktu końcowego i musi zostać jawnie określony lub za pośrednictwem parametry połączenia.
targetUnprocessedEventThreshold1 null Żądana liczba nieprzetworzonych zdarzeń na wystąpienie funkcji. Próg jest używany w skalowaniu opartym na obiekcie docelowym, aby zastąpić domyślny próg skalowania wywnioskowany z maxEventBatchSize opcji. Po ustawieniu łączna liczba nieprzetworzonych zdarzeń jest podzielona przez tę wartość w celu określenia liczby potrzebnych wystąpień funkcji. Liczba wystąpień jest zaokrąglona do liczby, która tworzy zrównoważoną dystrybucję partycji.
initialOffsetOptions/typ fromStart Lokalizacja w strumieniu zdarzeń, aby rozpocząć przetwarzanie, gdy punkt kontrolny nie istnieje w magazynie. Dotyczy wszystkich partycji. Aby uzyskać więcej informacji, zobacz dokumentację OffsetType. Dostępne opcje: fromStart, , fromEndfromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Określa czas w kolejce zdarzenia w strumieniu, z którego ma rozpocząć przetwarzanie. Jeśli initialOffsetOptions/type ustawienie jest skonfigurowane jako fromEnqueuedTime, to ustawienie jest obowiązkowe. Obsługuje czas w dowolnym formacie obsługiwanym przez dateTime.Parse(), na przykład 2020-10-26T20:31Z. Aby uzyskać jasność, należy również określić strefę czasową. Gdy strefa czasowa nie jest określona, usługa Functions zakłada lokalną strefę czasową maszyny z uruchomioną aplikacją funkcji, która jest utc podczas uruchamiania na platformie Azure.
clientRetryOptions/mode wykładniczy Podejście do obliczania opóźnień ponawiania prób. Ponawianie prób w trybie wykładniczym próby z opóźnieniem w oparciu o strategię wycofywania, w której każda próba zwiększy czas oczekiwania przed ponowną próbą. Tryb stały ponawia próby w stałych odstępach czasu z każdym opóźnieniem o stałym czasie trwania. Dostępne opcje: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Maksymalny czas trwania oczekiwania na ukończenie operacji usługi Event Hubs na próbę.
clientRetryOptions/delay 00:00:00.80 Współczynnik opóźnienia lub wycofywania, który ma być stosowany między ponownymi próbami.
clientRetryOptions/maximumDelay 00:00:01 Maksymalne opóźnienie między ponownymi próbami.
clientRetryOptions/maximumRetries 3 Maksymalna liczba ponownych prób przed rozważeniem skojarzonej operacji zakończyła się niepowodzeniem.

1 Używanie pakietu minEventBatchSize i maxWaitTime wymaga wersji 5.3.0 Microsoft.Azure.WebJobs.Extensions.EventHubs pakietu lub nowszej.

2 Wartość domyślna maxEventBatchSize została zmieniona w wersji 6.0.0 Microsoft.Azure.WebJobs.Extensions.EventHubs pakietu. We wcześniejszych wersjach było to 10.

Są clientRetryOptions one używane do ponawiania prób operacji między hostem usługi Functions i usługą Event Hubs (takimi jak pobieranie zdarzeń i wysyłanie zdarzeń). Zapoznaj się ze wskazówkami dotyczącymi obsługi błędów i ponawiania prób w usłudze Azure Functions, aby uzyskać informacje na temat stosowania zasad ponawiania prób do poszczególnych funkcji.

Aby zapoznać się z dokumentacją host.json w usłudze Azure Functions 2.x i nowszych, zobacz host.json dokumentacji usługi Azure Functions.

Następne kroki