Wyzwalacz usługi Azure IoT Hub dla usługi Azure Functions

  • Artykuł

W tym artykule 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.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

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.

Użyj wyzwalacza funkcji, aby odpowiedzieć na zdarzenie wysyłane do strumienia zdarzeń centrum zdarzeń. Aby skonfigurować wyzwalacz, musisz mieć dostęp do odczytu do bazowego centrum zdarzeń. Po wyzwoleniu funkcji komunikat przekazywany do funkcji jest wpisywany jako ciąg.

Decyzje dotyczące skalowania usługi Event Hubs dla planów Zużycie i Premium są wykonywane za pośrednictwem skalowania na podstawie celu. Aby uzyskać więcej informacji, zobacz Target Based Scaling (Skalowanie na podstawie celu).

Aby uzyskać informacje o sposobie reagowania usługi Azure Functions na zdarzenia wysyłane do strumienia zdarzeń centrum zdarzeń przy użyciu wyzwalaczy, zobacz Integrowanie usługi Event Hubs z funkcjami bezserwerowymi na platformie Azure.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Usługa Azure Functions obsługuje dwa modele programowania dla języka Python. Sposób definiowania powiązań zależy od wybranego modelu programowania.

Model programowania w języku Python w wersji 2 umożliwia definiowanie powiązań przy użyciu dekoratorów bezpośrednio w kodzie funkcji języka Python. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów języka Python.

Ten artykuł obsługuje oba modele programowania.

Przykład

W poniższym przykładzie pokazano funkcję języka C#, która jest wyzwalana na podstawie centrum zdarzeń, gdzie ciąg komunikatu wejściowego jest zapisywany w dziennikach:

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalacza usługi Event Hubs. Funkcja odczytuje metadane zdarzeń i rejestruje komunikat.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Aby odbierać zdarzenia w partii, ustaw wartość cardinalitymany, jak pokazano w poniższym przykładzie.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

W poniższym przykładzie przedstawiono funkcję JavaScript wyzwalacza usługi Event Hubs. Funkcja odczytuje metadane zdarzeń i rejestruje komunikat.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Aby odbierać zdarzenia w partii, ustaw wartość cardinalitymany, jak pokazano w poniższym przykładzie.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

Oto kod programu PowerShell:

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

W poniższym przykładzie pokazano powiązanie wyzwalacza usługi Event Hubs i funkcję języka Python, która używa powiązania. Funkcja odczytuje metadane zdarzeń i rejestruje komunikat. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

Poniższy przykład przedstawia powiązanie wyzwalacza usługi Event Hubs, które rejestruje treść komunikatu wyzwalacza usługi Event Hubs.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj EventHubTrigger adnotacji parametrów, których wartość pochodzi z centrum zdarzeń. Parametry z tymi adnotacjami powodują uruchomienie funkcji po nadejściu zdarzenia. Tej adnotacji można używać z natywnymi typami Języka Java, obiektami POJO lub wartościami dopuszczanymi wartościami null przy użyciu polecenia Optional<T>.

Poniższy przykład ilustruje obszerne użycie SystemProperties i inne opcje powiązania dla dalszego introspekcji zdarzenia wraz z zapewnieniem dobrze sformułowanej BlobOutput ścieżki, która jest hierarchiczna Data.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Atrybuty

Biblioteki języka C# procesu roboczego zarówno w procesie przetwarzania procesów procesów przetwarzania w procesie przetwarzania, jak i izolowanego, używają atrybutu do konfigurowania wyzwalacza. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

Użyj polecenia , EventHubTriggerAttribute aby zdefiniować wyzwalacz w centrum zdarzeń, który obsługuje następujące właściwości.

Parametry opis
EventHubName Nazwa centrum zdarzeń. Gdy nazwa centrum zdarzeń jest również obecna w parametry połączenia, ta wartość zastępuje tę właściwość w czasie wykonywania. Można odwoływać się do ustawień aplikacji, takich jak %eventHubName%
ConsumerGroup Opcjonalna właściwość, która ustawia grupę odbiorców używaną do subskrybowania zdarzeń w centrum. Po pominięciu $Default grupa odbiorców jest używana.
Połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Aby dowiedzieć się więcej, zobacz Połączenie ions.

Dekoratory

Dotyczy tylko modelu programowania w wersji 2 języka Python.

W przypadku funkcji języka Python w wersji 2 zdefiniowanych przy użyciu dekoratora następujące właściwości w pliku cosmos_db_trigger:

Właściwości opis
arg_name Nazwa zmiennej reprezentującej element zdarzenia w kodzie funkcji.
event_hub_name Nazwa centrum zdarzeń. Gdy nazwa centrum zdarzeń jest również obecna w parametry połączenia, ta wartość zastępuje tę właściwość w czasie wykonywania.
connection Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Zobacz Połączenie ions.

Aby zapoznać się z funkcjami języka Python zdefiniowanymi przy użyciu function.json, zobacz sekcję Konfiguracja .

Adnotacje

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj adnotacji EventHubTrigger, która obsługuje następujące ustawienia:

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego app.eventHub() do metody .

Właściwości opis
eventHubName Nazwa centrum zdarzeń. Gdy nazwa centrum zdarzeń jest również obecna w parametry połączenia, ta wartość zastępuje tę właściwość w czasie wykonywania. Można odwoływać się za pomocą ustawień aplikacji%eventHubName%
consumerGroup Opcjonalna właściwość, która ustawia grupę odbiorców używaną do subskrybowania zdarzeń w centrum. W przypadku pominięcia $Default grupa odbiorców jest używana.
Kardynalność Ustaw wartość na many w celu włączenia przetwarzania wsadowego. Jeśli pominięto lub ustawiono onewartość , do funkcji zostanie przekazany pojedynczy komunikat.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Zobacz Połączenie ions.

W poniższej tabeli opisano właściwości konfiguracji wyzwalacza ustawione w pliku function.json , które różnią się wersją środowiska uruchomieniowego.

właściwość function.json opis
type Musi być ustawiona wartość eventHubTrigger. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
direction Musi być ustawiona wartość in. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
name Nazwa zmiennej reprezentującej element zdarzenia w kodzie funkcji.
eventHubName Nazwa centrum zdarzeń. Gdy nazwa centrum zdarzeń jest również obecna w parametry połączenia, ta wartość zastępuje tę właściwość w czasie wykonywania. Można odwoływać się za pomocą ustawień aplikacji%eventHubName%
consumerGroup Opcjonalna właściwość, która ustawia grupę odbiorców używaną do subskrybowania zdarzeń w centrum. W przypadku pominięcia $Default grupa odbiorców jest używana.
Kardynalność Ustaw wartość na many w celu włączenia przetwarzania wsadowego. Jeśli pominięto lub ustawiono onewartość , do funkcji zostanie przekazany pojedynczy komunikat.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Zobacz Połączenie ions.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Użycie

Aby dowiedzieć się więcej o tym, jak wyzwalacz usługi Event Hubs i wyzwalacze usługi IoT Hub skaluje, zobacz Korzystanie ze zdarzeń za pomocą usługi Azure Functions.

Typ parametru obsługiwany przez powiązanie wyjściowe usługi Event Hubs zależy od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

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.

Typ parametru może być jednym z następujących elementów:

  • Wszelkie natywne typy języka Java, takie jak int, String, byte[].
  • Wartości dopuszczane wartości null przy użyciu opcji Opcjonalne.
  • Dowolny typ POJO.

Aby dowiedzieć się więcej, zobacz dokumentację EventHubTrigger .

Metadane zdarzenia

Wyzwalacz usługi Event Hubs udostępnia kilka właściwości metadanych. Właściwości metadanych mogą być używane jako część wyrażeń powiązań w innych powiązaniach lub jako parametry w kodzie. Właściwości pochodzą z klasy EventData .

Właściwość Type Opis
PartitionContext PartitionContext Wystąpienie elementu PartitionContext.
EnqueuedTimeUtc DateTime Czas w kolejce w formacie UTC.
Offset string Przesunięcie danych względem strumienia partycji centrum zdarzeń. Przesunięcie jest znacznikiem lub identyfikatorem zdarzenia w strumieniu usługi Event Hubs. Identyfikator jest unikatowy w ramach partycji strumienia usługi Event Hubs.
PartitionKey string Partycja, do której mają być wysyłane dane zdarzenia.
Properties IDictionary<String,Object> Właściwości użytkownika danych zdarzenia.
SequenceNumber Int64 Numer sekwencji logicznej zdarzenia.
SystemProperties IDictionary<String,Object> Właściwości systemu, w tym dane zdarzenia.

Zobacz przykłady kodu, które używają tych właściwości wcześniej w tym artykule.

Połączenia

Właściwość connection jest odwołaniem do konfiguracji środowiska, która zawiera nazwę ustawienia aplikacji zawierającego parametry połączenia. Możesz uzyskać tę parametry połączenia, wybierając przycisk Połączenie ion Information (Informacje o Połączenie) dla przestrzeni nazw. Parametry połączenia musi dotyczyć przestrzeni nazw usługi Event Hubs, a nie samej centrum zdarzeń.

Aby aktywować funkcję, parametry połączenia musi mieć co najmniej uprawnienia do odczytu.

Ta parametry połączenia powinna być przechowywana w ustawieniu aplikacji z nazwą zgodną z wartością określoną przez connection właściwość konfiguracji powiązania.

Uwaga

Połączenia oparte na tożsamościach nie są obsługiwane przez wyzwalacz usługi IoT Hub. Jeśli potrzebujesz kompleksowej obsługi tożsamości zarządzanych, możesz zamiast tego użyć routingu usługi IoT Hub do wysyłania danych do centrum zdarzeń, które kontrolujesz. W ten sposób routing wychodzący można uwierzytelnić przy użyciu tożsamości zarządzanej, którą zdarzenie można odczytać z tego centrum zdarzeń przy użyciu tożsamości zarządzanej.

host.json właściwości

Plik host.json zawiera ustawienia kontrolujące zachowanie wyzwalacza centrum zdarzeń. Aby uzyskać szczegółowe informacje dotyczące dostępnych ustawień, zobacz sekcję host.json settings (Ustawienia host.json).

Następne kroki