Udostępnij za pośrednictwem

Wyzwalacz usługi Azure Event Hubs dla usługi Azure Functions

  • Artykuł

W tym artykule wyjaśniono, jak pracować z wyzwalaczem usługi Azure Event Hubs dla usługi Azure Functions. Usługa Azure Functions obsługuje powiązania wyzwalacza i wyjściowe dla usługi Event Hubs.

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

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ść cardinality many, 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ść cardinality many, 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łączenia.

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 event_hub_message_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łączenia.

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.
moc Ustaw wartość na many w celu włączenia przetwarzania wsadowego. Jeśli pominięto lub ustawiono onewartość , do funkcji zostanie przekazany pojedynczy komunikat.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Zobacz Połączenia.

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.
moc Ustaw wartość na many w celu włączenia przetwarzania wsadowego. Jeśli pominięto lub ustawiono onewartość , do funkcji zostanie przekazany pojedynczy komunikat.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Event Hubs. Zobacz Połączenia.

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 określa sposób łączenia aplikacji z usługą Event Hubs. Może to określać:

  • Nazwa ustawienia aplikacji zawierającego parametry połączenia
  • Nazwa udostępnionego prefiksu dla wielu ustawień aplikacji, definiująca połączenie oparte na tożsamościach.

Jeśli skonfigurowana wartość jest dokładnie zgodna z pojedynczym ustawieniem i dopasowaniem prefiksu dla innych ustawień, zostanie użyte dokładne dopasowanie.

Connection string

Uzyskaj tę parametry połączenia, klikając przycisk Informacje o połączeniu dla przestrzeni nazw, a nie samego centrum zdarzeń. Parametry połączenia musi dotyczyć przestrzeni nazw usługi Event Hubs, a nie samej centrum zdarzeń.

W przypadku użycia w przypadku wyzwalaczy parametry połączenia musi mieć co najmniej "odczyt" uprawnienia do aktywowania funkcji. W przypadku użycia w przypadku powiązań wyjściowych parametry połączenia musi mieć uprawnienia do wysyłania komunikatów do strumienia zdarzeń.

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.

Połączenia oparte na tożsamościach

Jeśli używasz rozszerzenia w wersji 5.x lub nowszej, zamiast używać parametry połączenia z wpisem tajnym, możesz mieć aplikację korzystającą z tożsamości Microsoft Entra. W tym celu należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na connection właściwość w konfiguracji wyzwalacza i powiązania.

W tym trybie rozszerzenie wymaga następujących właściwości:

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
W pełni kwalifikowana przestrzeń nazw <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace W pełni kwalifikowana przestrzeń nazw usługi Event Hubs. myeventhubns.servicebus.windows.net

Aby dostosować połączenie, można ustawić dodatkowe właściwości. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

Uwaga

W przypadku używania aplikacja systemu Azure Configuration lub Key Vault w celu zapewnienia ustawień dla połączeń tożsamości zarządzanej nazwy ustawień powinny używać prawidłowego separatora kluczy, takiego jak : lub / zamiast elementu __ , aby upewnić się, że nazwy są poprawnie rozpoznawane.

Na przykład <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

W przypadku hostowania w usłudze Azure Functions połączenia oparte na tożsamościach używają tożsamości zarządzanej. Tożsamość przypisana przez system jest używana domyślnie, chociaż tożsamości przypisanej przez użytkownika można określić za credential pomocą właściwości i clientID . Należy pamiętać, że konfigurowanie tożsamości przypisanej przez użytkownika przy użyciu identyfikatora zasobu nie jest obsługiwane. W przypadku uruchamiania w innych kontekstach, takich jak programowanie lokalne, tożsamość dewelopera jest używana, chociaż można to dostosować. Zobacz Programowanie lokalne z połączeniami opartymi na tożsamościach.

Udzielanie uprawnień tożsamości

Niezależnie od używanej tożsamości musi mieć uprawnienia do wykonywania zamierzonych akcji. W przypadku większości usług platformy Azure oznacza to, że musisz przypisać rolę w kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych ról, które zapewniają te uprawnienia.

Ważne

Niektóre uprawnienia mogą być uwidocznione przez usługę docelową, które nie są niezbędne dla wszystkich kontekstów. Jeśli to możliwe, przestrzegaj zasady najniższych uprawnień, udzielając tożsamości tylko wymaganych uprawnień. Jeśli na przykład aplikacja musi mieć możliwość odczytu tylko ze źródła danych, użyj roli, która ma uprawnienia tylko do odczytu. Niewłaściwe byłoby przypisanie roli, która umożliwia również zapisywanie w tej usłudze, ponieważ byłoby to nadmierne uprawnienie do operacji odczytu. Podobnie należy upewnić się, że przypisanie roli jest ograniczone tylko do zasobów, które należy odczytać.

Należy utworzyć przypisanie roli, które zapewnia dostęp do centrum zdarzeń w czasie wykonywania. Zakres przypisania roli może dotyczyć przestrzeni nazw usługi Event Hubs lub samego centrum zdarzeń. Role zarządzania, takie jak Właściciel , nie są wystarczające. W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z rozszerzenia usługi Event Hubs w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe role wbudowane
Wyzwalacz Odbiornik danych usługi Azure Event Hubs, właściciel danych usługi Azure Event Hubs
Powiązanie wyjściowe Nadawca danych usługi Azure Event Hubs

ustawienia host.json

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

Następne kroki