Udostępnij za pośrednictwem

Powiązanie wyjściowe usługi Azure Event Hubs dla usługi Azure Functions

  • Artykuł

W tym artykule wyjaśniono, jak pracować z powiązaniami 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 powiązania wyjściowego usługi Event Hubs, aby zapisywać zdarzenia w strumieniu zdarzeń. Musisz mieć uprawnienie do wysłania do centrum zdarzeń, aby zapisywać w nim zdarzenia.

Przed podjęciem próby zaimplementowania powiązania wyjściowego upewnij się, że wymagane odwołania do pakietu zostały wdrożone.

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 zapisuje ciąg komunikatu w centrum zdarzeń przy użyciu wartości zwracanej metody jako danych wyjściowych:

[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 wyzwalaną przez czasomierz, która wysyła pojedynczy komunikat do centrum zdarzeń:

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

Aby wyświetlić wiele komunikatów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

W poniższym przykładzie przedstawiono funkcję javaScript wyzwalaną przez czasomierz, która wysyła pojedynczy komunikat do centrum zdarzeń:

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

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Aby wyświetlić wiele komunikatów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Kompletne przykłady programu PowerShell są oczekujące.

W poniższym przykładzie przedstawiono powiązanie wyzwalacza centrum zdarzeń i funkcję języka Python, która używa powiązania. Funkcja zapisuje komunikat w centrum zdarzeń. 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="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Oto kod języka Python, który wysyła wiele komunikatów:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

W poniższym przykładzie pokazano funkcję Języka Java, która zapisuje komunikat zawierający bieżący czas w centrum zdarzeń.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @EventHubOutput adnotacji parametrów, których wartość zostanie opublikowana w usłudze Event Hubs. Parametr powinien być typu OutputBinding<T> , gdzie T jest poJO lub dowolnym natywnym typem języka Java.

Atrybuty

Zarówno w procesie, jak i izolowanym procesie roboczym biblioteki języka C# używają atrybutu do konfigurowania powiązania. 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 elementu [EventHubOutputAttribute], aby zdefiniować powiązanie wyjściowe z centrum zdarzeń, które 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.
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 te właściwości są obsługiwane w przypadku event_hub_outputprogramu :

Właściwości opis
arg_name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje zdarzenie.
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. Aby dowiedzieć się więcej, 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 EventHubOutput dla parametrów, których wartość zostanie opublikowana w usłudze Event Hubs. Następujące ustawienia są obsługiwane w adnotacji:

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

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

właściwość function.json opis
type Musi być ustawiona wartość eventHub.
direction Musi być ustawiona wartość out. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w witrynie Azure Portal.
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje zdarzenie.
eventHubName Funkcje w wersji 2.x i nowszej. 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.
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.

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

Użycie

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

Istnieją dwie opcje wyprowadzania komunikatu usługi Event Hubs z funkcji przy użyciu adnotacji EventHubOutput :

  • Wartość zwracana: stosując adnotację do samej funkcji, zwracana wartość funkcji jest utrwalana jako komunikat usługi Event Hubs.

  • Imperatywne: Aby jawnie ustawić wartość komunikatu, zastosuj adnotację do określonego parametru typu OutputBinding<T>, gdzie T jest poJO lub dowolnym natywnym typem języka Java. W przypadku tej konfiguracji przekazanie wartości do setValue metody utrwala wartość jako komunikat usługi Event Hubs.

Kompletne przykłady programu PowerShell są oczekujące.

Uzyskaj dostęp do komunikatu wyjściowego, zwracając wartość bezpośrednio lub przy użyciu polecenia context.extraOutputs.set().

Istnieją dwie opcje wyprowadzania komunikatu usługi Event Hubs z funkcji:

  • Wartość zwracana name : ustaw właściwość w function.json na $returnwartość . W przypadku tej konfiguracji wartość zwracana funkcji jest utrwalana jako komunikat usługi Event Hubs.

  • Imperatywne: przekaż wartość do metody set parametru zadeklarowanego jako typ out . Przekazana wartość jest utrwalana set jako komunikat usługi Event Hubs.

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

Wyjątki i kody powrotne

Wiązanie Odwołanie
Event Hubs Przewodnik operacyjny

Następne kroki