Aktivační událost služby Azure Event Hubs pro Azure Functions

Článek
05/13/2021
11 min ke čtení

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

Informace o nastavení a podrobnostech o konfiguraci najdete v tématu Přehled.

Pomocí triggeru funkce můžete reagovat na událost odeslaná do streamu událostí centra událostí. K nastavení triggeru musíte mít přístup pro čtení k základnímu centru událostí. Při aktivaci funkce se zpráva předaná funkci zadá jako řetězec.

Škálování

Každá instance funkce aktivované událostí je zálohována jednou instancí třídy EventProcessorHost. Trigger (používá ho Event Hubs) zajišťuje, že pro daný oddíl může získat zapůjčení pouze jedna instance třídy EventProcessorHost.

Zvažte například centrum událostí následujícím způsobem:

10 oddílů
Rovnoměrně rozděleno 1 000 událostí napříč všemi oddíly se 100 zprávami v každém oddílu

Když je funkce poprvé povolená, existuje pouze jedna instance funkce. Zavoláme první instanci funkce Function_0 . Funkce Function_0 má jednu instanci třídy EventProcessorHost, která má zapůjčení na všech deseti oddílech. Tato instance čte události z oddílů 0–9. Od tohoto okamžiku se stane jedna z následujících akcí:

Nové instance funkcí nejsou potřeba: dokáže zpracovat všech 1 000 událostí, než se logika Function_0 škálování služby Functions projeví. V tomto případě zpracovává všechny 1 000 Function_0 zpráv.
Přidá se další instance funkce: Pokud logika škálování functions určuje, že obsahuje více zpráv, než dokáže zpracovat, vytvoří se nová Function_0 instance aplikace funkcí ( Function_1 ). Tato nová funkce má také přidruženou instanci třídy EventProcessorHost. Vzhledem k tomu, Event Hubs instance hostitele zjišťuje, že nová instance hostitele zkouší číst zprávy, vyvažuje zatížení oddílů mezi instancemi hostitele. Například oddíly 0–4 mohou být přiřazeny k a Function_0 oddíly 5–9 k Function_1 .
Přidá se N dalších instancí funkce: Pokud logika škálování služby Functions určuje, že a mají více zpráv, než mohou zpracovat, vytvoří se nové instance aplikace Function_0 Function_1 Functions_N funkcí. Aplikace se vytvářejí až do bodu, kdy je větší než N počet oddílů centra událostí. V našem příkladu Event Hubs zatížení znovu vyvažuje oddíly, v tomto případě napříč instancemi Function_0 ... Functions_9 .

Při škálování je počet instancí větší než počet oddílů N centra událostí. Tento model se používá k zajištění, aby instance třídy EventProcessorHost byly dostupné pro získání zámků na oddílech, jakmile jsou dostupné z jiných instancí. Poplatky se vám účtují pouze za prostředky použité při spuštění instance funkce. Jinými slovy, za toto zřizování se vám neúčtuje žádné poplatky.

Po dokončení všech provádění funkcí (s chybami nebo bez nich) se do přidruženého účtu úložiště přidávají kontrolní body. Pokud je kontrolní bod úspěšný, 1 000 zpráv se už nikdy nenačítá.

Následující příklad ukazuje funkci jazyka C#, která protokoluje tělo zprávy triggeru centra událostí.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Pokud chcete získat přístup k metadatům událostí v kódu funkce, vytvořte vazbu na objekt EventData (vyžaduje příkaz using pro Microsoft.Azure.EventHubs ). Ke stejným vlastnostem můžete přistupovat také pomocí vazbových výrazů v podpisu metody. Následující příklad ukazuje oba způsoby, jak získat stejná data:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Pokud chcete přijímat události v dávce, vytvořte string nebo EventData pole.

Poznámka

Při příjmu v dávce nemůžete vytvořit vazbu na parametry metody jako ve výše uvedeném příkladu s a musíte je DateTime enqueuedTimeUtc přijmout z každého EventData objektu.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Následující příklad ukazuje vazbu triggeru centra událostí v souboru function.json a funkci skriptu jazyka C#, která tuto vazbu používá. Funkce protokoluje tělo zprávy triggeru centra událostí.

Následující příklady ukazují, Event Hubs vazby dat v souboru function.json.

Verze 2.x a vyšší

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Verze 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Tady je kód skriptu jazyka C#:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public static void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

Pokud chcete přijímat události v dávce, vytvořte string nebo EventData pole:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

Následující příklad ukazuje vazbu triggeru centra událostí v souboru function.json a funkci JavaScriptu, která tuto vazbu používá. Funkce načte metadata událostí a zahlásí zprávu.

Následující příklady ukazují, Event Hubs vazby dat v souboru function.json.

Verze 2.x a vyšší

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Verze 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Tady je kód JavaScriptu:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Pokud chcete přijímat události v dávce, nastavte v souboru cardinality many function.json na hodnotu , jak je znázorněno v následujících příkladech.

Verze 2.x a vyšší

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Verze 1.x

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "path": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Tady je kód JavaScriptu:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

Následující příklad ukazuje vazbu triggeru centra událostí v souboru function.json a funkci Pythonu, která tuto vazbu používá. Funkce načte metadata událostí a zahlásí zprávu.

Následující příklady ukazují, Event Hubs vazby dat v souboru function.json.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Tady je kód Pythonu:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

Následující příklad ukazuje vazbu triggeru centra událostí, která protokoluje tělo zprávy triggeru centra událostí.

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

V knihovně runtime java functionspoužijte poznámku k parametrům, EventHubTrigger jejichž hodnota by pošla z centra událostí. Parametry s těmito poznámkami způsobí, že se funkce spustí při doručení události. Tuto poznámku je možné použít s nativními typy Javy, POMO nebo hodnotami s možnou hodnotou null pomocí Optional<T> .

Atributy a poznámky

V knihovnách tříd jazyka C#použijte atribut EventHubTriggerAttribute.

Konstruktor atributu přebírá název centra událostí, název skupiny uživatelů a název nastavení aplikace, které obsahuje připojovací řetězec. Další informace o těchto nastaveních najdete v části konfigurace aktivační události. Tady je příklad EventHubTriggerAttribute atributu:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Kompletní příklad najdete v tématu Trigger – příklad jazyka C#.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které nastavíte v souboru function.json a EventHubTrigger atributu .

function.json – vlastnost	Vlastnost atributu	Description
Typ	Není k dispozici	Musí být nastavená na `eventHubTrigger` . Tato vlastnost se nastaví automaticky při vytvoření triggeru v Azure Portal.
Směru	Není k dispozici	Musí být nastavená na `in` . Tato vlastnost se nastaví automaticky při vytvoření triggeru v Azure Portal.
Jméno	Není k dispozici	Název proměnné, která představuje položku události v kódu funkce.
dílčí	EventHubName	Pouze funkce 1. x. Název centra událostí Pokud je v připojovacím řetězci přítomen i název centra událostí, tato hodnota tuto vlastnost Přepisuje za běhu.
eventHubName	EventHubName	Functions 2. x a vyšší. Název centra událostí Pokud je v připojovacím řetězci přítomen i název centra událostí, tato hodnota tuto vlastnost Přepisuje za běhu. Dá se odkazovat prostřednictvím nastavení aplikace . `%eventHubName%`
Klientská organizace	Klientská organizace	Volitelná vlastnost, která nastaví skupinu uživatelů použitou k přihlášení k odběru událostí v centru. Je-li tento parametr vynechán, `$Default` je použita skupina uživatelů.
kardinalita	Není k dispozici	Používá se pro všechny jazyky jiné než C #. Nastavte na, aby `many` bylo možné dávkování povolit. Je-li tento parametr vynechán nebo je nastaven na hodnotu `one` , je do funkce předána jedna zpráva. V jazyce C# je tato vlastnost automaticky přiřazena vždy, když Trigger obsahuje pole pro daný typ.
vázán	Připojení	Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k Event Hubs. Viz připojení.

Když vyvíjíte místně, nastavení aplikace se přechádí do local.settings.jssouboru.

Připojení

connectionVlastnost je odkaz na konfiguraci prostředí, který určuje, jak se má aplikace připojit k Event Hubs. Může specifikovat:

Název nastavení aplikace, které obsahuje připojovací řetězec
Název sdílené předpony pro více nastavení aplikace, která definuje připojení na základě identity.

Pokud je nakonfigurovaná hodnota přesnou shodu pro jedno nastavení a shoda předpony pro další nastavení, použije se přesná shoda.

Připojovací řetězec

Tento připojovací řetězec získáte kliknutím na tlačítko informace o připojení pro obor názvů, nikoli v samotném centru událostí. Připojovací řetězec musí být pro obor názvů Event Hubs, ne jako samotný střed centra událostí.

Při použití pro triggery musí mít připojovací řetězec alespoň oprávnění ke čtení, aby bylo možné funkci aktivovat. Při použití pro výstupní vazby musí mít připojovací řetězec oprávnění Odeslat, aby mohl odesílat zprávy do datového proudu událostí.

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

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

pokud používáte rozšíření verze 5. x nebo vyšší, místo použití připojovacího řetězce s tajným klíčem můžete aplikaci použít Azure Active Directory identity. K tomu byste definovali nastavení v rámci společné předpony, která se mapuje na connection vlastnost v aktivační události a v konfiguraci vazby.

V tomto režimu přípona vyžaduje následující vlastnosti:

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

Pro přizpůsobení připojení je možné nastavit další vlastnosti. Další informace najdete v tématu běžné vlastnosti pro připojení založená na identitách.

Při hostování ve Azure Functions používá připojení založená na identitě spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když identitu přiřazenou uživatelem je možné zadat pomocí vlastností credential clientID a . Při spuštění v jiných kontextech, jako je například místní vývoj, se místo toho použije 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í k identitě

Kterákoli použitá identita musí mít oprávnění k provedení zamýšlených akcí. V Azure RBACbudete muset přiřadit roli pomocí předdefinované nebo vlastní role, které tato oprávnění poskytují.

Důležité

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

Budete muset vytvořit přiřazení role, které poskytuje přístup k vašemu centru událostí za běhu. Rozsah přiřazení role musí být pro obor názvů Event Hubs, nikoli pro samotné centrum událostí. Role pro správu, jako je vlastník, nestačí. Následující tabulka uvádí předdefinované role, které se doporučují při běžném Event Hubs rozšíření. Vaše aplikace může na základě kódu, který píšete, vyžadovat další oprávnění.

Typ vazby	Příklady předdefinované role
Trigger	[Azure Event Hubs příjemce dat,] [vlastník Azure Event Hubs dat]
Výstupní vazba	Azure Event Hubs odesílatele dat

Využití

Výchozí

Pro spuštění centra událostí můžete použít následující typy parametrů:

string
byte[]
POCO
EventData – Výchozí vlastnosti EventData jsou k dispozici v oboru názvů Microsoft. Azure. EventHubs.

Další typy

Aplikace používající 5.0.0 nebo vyšší verze rozšíření centra událostí používají EventData typ v Azure. Messaging. EventHubs , nikoli v oboru názvů Microsoft. Azure. EventHubs. Tato verze vyřazuje podporu pro starší Body typ, a to ve prospěch následujících typů:

EventBody

Výchozí

Pro spuštění centra událostí můžete použít následující typy parametrů:

string
byte[]
POCO
EventData – Výchozí vlastnosti EventData jsou k dispozici v oboru názvů Microsoft. Azure. EventHubs.

Další typy

EventBody

Metadata události

Aktivační událost Event Hubs poskytuje několik vlastností metadat. Vlastnosti metadat lze použít jako součást výrazů vazby v jiných vazbách nebo jako parametry v kódu. Vlastnosti pocházejí ze třídy EventData .

Vlastnost	Typ	Description
`PartitionContext`	PartitionContext	Instance `PartitionContext`.
`EnqueuedTimeUtc`	`DateTime`	Čas zařazení do fronty ve standardu UTC.
`Offset`	`string`	Posun dat vzhledem ke streamu oddílu centra událostí. Posun je značka nebo identifikátor události v rámci Event Hubsho datového proudu. Identifikátor je jedinečný v rámci oddílu Event Hubsho datového proudu.
`PartitionKey`	`string`	Oddíl, do kterého mají být odeslána data událostí.
`Properties`	`IDictionary<String,Object>`	Vlastnosti uživatele dat události.
`SequenceNumber`	`Int64`	Číslo logické sekvence události
`SystemProperties`	`IDictionary<String,Object>`	Vlastnosti systému, včetně dat události.

Podívejte se na Příklady kódu , které používají tyto vlastnosti dříve v tomto článku.

host.jsnastavení

host.jsv souboru obsahuje nastavení, která řídí chování triggeru centra událostí. Podrobnosti o dostupných nastaveních najdete v části host.jsv nastavení .

Další kroky

Zápis událostí do datového proudu událostí (výstupní vazba)

Aktivační událost služby Azure Event Hubs pro Azure Functions

Ohodnoťte vaše zkušenosti

Škálování

Atributy a poznámky

Konfigurace

Připojení

Připojovací řetězec

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

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

Využití

Výchozí

Další typy

Metadata události

host.jsnastavení

Další kroky