Výstupní vazba služby Azure Event Hubs pro Azure Functions

  • Článek

Tento článek vysvětluje, jak pracovat s vazbami služby Azure Event Hubs pro Azure Functions. Azure Functions podporuje aktivační a výstupní vazby pro službu Event Hubs.

Informace o nastavení a konfiguraci najdete v přehledu.

Výstupní vazbu služby Event Hubs použijte k zápisu událostí do datového proudu událostí. Musíte mít oprávnění k odesílání do centra událostí, abyste do něj události mohli zapisovat.

Než se pokusíte implementovat výstupní vazbu, ujistěte se, že jsou zavedené požadované odkazy na balíčky.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Příklad

Následující příklad ukazuje funkci jazyka C#, která zapíše řetězec zprávy do centra událostí pomocí návratové hodnoty metody jako výstupu:

[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;
}

Následující příklad ukazuje funkci TypeScript aktivovanou časovačem, která odesílá jednu zprávu do centra událostí:

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,
});

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje časovač aktivovanou funkci JavaScriptu, která odesílá jednu zprávu do centra událostí:

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}`;
    },
});

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Dokončené příklady PowerShellu čekají na vyřízení.

Následující příklad ukazuje vazbu triggeru centra událostí a funkci Pythonu, která používá vazbu. Funkce zapíše zprávu do centra událostí. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

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'

Tady je kód Pythonu, který odesílá více zpráv:

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

Následující příklad ukazuje funkci Java, která zapíše zprávu obsahující aktuální čas do centra událostí.

@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();
 }

V knihovně modulu runtime funkcí Java použijte poznámku @EventHubOutput k parametrům, jejichž hodnota by byla publikována ve službě Event Hubs. Parametr by měl být typu OutputBinding<T> , kde T je POJO nebo jakýkoli nativní typ Java.

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají ke konfiguraci vazby atribut. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

Pomocí [EventHubOutputAttribute] definujte výstupní vazbu do centra událostí, která podporuje následující vlastnosti.

Parametry Popis
EventHubName Název centra událostí. Pokud se v připojovací řetězec nachází také název centra událostí, tato hodnota přepíše tuto vlastnost za běhu.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Event Hubs. Další informace najdete v tématu Připojení iony.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

U funkcí Pythonu v2 definovaných pomocí dekorátoru jsou tyto vlastnosti podporované pro event_hub_output:

Vlastnost Popis
arg_name Název proměnné použitý v kódu funkce, který představuje událost.
event_hub_name jmenuje se centrum událostí. Pokud se v připojovací řetězec nachází také název centra událostí, tato hodnota přepíše tuto vlastnost za běhu.
connection Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Event Hubs. Další informace najdete v tématu Připojení iony.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

V knihovně modulu runtime funkcí Java použijte poznámku EventHubOutput k parametrům, jejichž hodnota by se publikovala ve službě Event Hubs. V poznámce jsou podporována následující nastavení:

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.eventHub() .

Vlastnost Popis
eventHubName Název centra událostí. Pokud se v připojovací řetězec nachází také název centra událostí, tato hodnota přepíše tuto vlastnost za běhu.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Event Hubs. Další informace najdete v tématu Připojení iony.

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json , které se liší podle verze modulu runtime.

vlastnost function.json Popis
type Musí být nastavena na eventHubhodnotu .
direction Musí být nastavena na outhodnotu . Tento parametr se nastaví automaticky při vytváření vazby na webu Azure Portal.
Jméno Název proměnné použitý v kódu funkce, který představuje událost.
eventHubName Funkce 2.x a vyšší Název centra událostí. Pokud se v připojovací řetězec nachází také název centra událostí, tato hodnota přepíše tuto vlastnost za běhu.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Event Hubs. Další informace najdete v tématu Připojení iony.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Využití

Typ parametru podporovaný výstupní vazbou služby Event Hubs závisí na verzi modulu runtime služby Functions, verzi balíčku rozšíření a použitém režimu jazyka C#.

Pokud chcete, aby funkce zapisuje jednu událost, výstupní vazba služby Event Hubs může svázat s následujícími typy:

Typ Popis
string Událost jako řetězec. Použije se, když je událost jednoduchý text.
byte[] Bajty události.
Serializovatelné typy JSON Objekt představující událost. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisuje více událostí, výstupní vazba služby Event Hubs může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single event types Pole obsahující více událostí. Každá položka představuje jednu událost.

V případě jiných výstupních scénářů můžete přímo vytvářet a používat typy z Microsoft.Azure.EventHubs .

Existují dvě možnosti výstupu zprávy služby Event Hubs z funkce pomocí poznámky EventHubOutput :

  • Návratová hodnota: Použitím poznámky na samotnou funkci se návratová hodnota funkce zachová jako zpráva Event Hubs.

  • Imperativní: Pokud chcete explicitně nastavit hodnotu zprávy, použijte poznámku na konkrétní parametr typu OutputBinding<T>, kde T je POJO nebo jakýkoli nativní typ Java. Při této konfiguraci předání hodnoty metodě setValue zachová hodnotu jako zprávu Event Hubs.

Dokončené příklady PowerShellu čekají na vyřízení.

Přístup k výstupní zprávě vrácením hodnoty přímo nebo pomocí context.extraOutputs.set().

Existují dvě možnosti výstupu zprávy služby Event Hubs z funkce:

  • Návratová hodnota: Nastavte name vlastnost v function.json na $returnhodnotu . Při této konfiguraci se návratová hodnota funkce zachová jako zpráva služby Event Hubs.

  • Imperativní: Předejte hodnotu metodě sady parametru deklarovaného jako typ Out . Předaná set hodnota je trvalá jako zpráva služby Event Hubs.

Propojení

Vlastnost connection je odkazem na konfiguraci prostředí, která určuje, jak se má aplikace připojit ke službě Event Hubs. Může zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Tuto připojovací řetězec získáte kliknutím na tlačítko informace o Připojení pro obor názvů, nikoli samotným centrem událostí. Připojovací řetězec musí být pro obor názvů služby Event Hubs, nikoli pro samotné centrum událostí.

Při použití pro triggery musí mít připojovací řetězec k aktivaci funkce alespoň oprávnění ke čtení. Při použití pro výstupní vazby musí mít připojovací řetězec oprávnění k odesílání zpráv do datového proudu událostí.

Tato připojovací řetězec by měla být uložena v nastavení aplikace s názvem, který connection odpovídá hodnotě určené vlastností konfigurace vazby.

Připojení založená na identitách

Pokud používáte rozšíření verze 5.x nebo vyšší, můžete místo použití připojovací řetězec s tajným kódem použít aplikaci identitu Microsoft Entra. K tomu byste definovali nastavení pod běžnou předponou, která se mapuje na connection vlastnost v konfiguraci triggeru a vazby.

V tomto režimu rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Plně kvalifikovaný obor názvů <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Plně kvalifikovaný obor názvů služby Event Hubs. myeventhubns.servicebus.windows.net

Pro přizpůsobení připojení je možné nastavit další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Poznámka:

Při použití konfigurace Aplikace Azure nebo služby Key Vault k poskytnutí nastavení pro připojení spravované identity by názvy nastavení měly používat platný oddělovač klíčů, například : místo /__ názvu, aby se názvy správně přeložily.

Například <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Budete muset vytvořit přiřazení role, které poskytuje přístup k centru událostí za běhu. Oborem přiřazení role může být obor názvů služby Event Hubs nebo samotné centrum událostí. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Event Hubs v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí
Trigger Příjemce dat služby Azure Event Hubs, vlastník dat služby Azure Event Hubs
Výstupní vazba Odesílatel dat služby Azure Event Hubs

Výjimky a návratové kódy

Vazba Reference
Event Hubs Provozní příručka

Další kroky