Azure Event Hubs kimeneti kötés az Azure Functionshez

Ez a cikk bemutatja, hogyan használható az Azure Event Hubs-kötések használata az Azure Functionshez. Az Azure Functions támogatja az Event Hubs eseményindító- és kimeneti kötéseit.

A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.

Az Event Hubs kimeneti kötésével eseményeket írhat egy eseményfolyamba. Küldési engedéllyel kell rendelkeznie ahhoz, hogy eseményeket írhasson egy eseményközpontba.

A kimeneti kötés implementálása előtt győződjön meg arról, hogy a szükséges csomaghivatkozások érvényben vannak.

Fontos

Ez a cikk lapokat használ a Node.js programozási modell több verziójának támogatásához. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további információkért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.

Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.

A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.

Ez a cikk mindkét programozási modellt támogatja.

Példa

Az alábbi példa egy C# függvényt mutat be, amely egy üzenetsztringet ír egy eseményközpontba, és a metódus visszatérési értékét használja kimenetként:

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

Az alábbi példa egy időzítő által aktivált TypeScript-függvényt mutat be, amely egyetlen üzenetet küld egy eseményközpontnak:

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

Több üzenet kimenetéhez egyetlen objektum helyett egy tömböt kell visszaadnia. Példa:

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

Az alábbi példa egy időzítő által aktivált JavaScript-függvényt mutat be, amely egyetlen üzenetet küld egy eseményközpontnak:

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

Több üzenet kimenetéhez egyetlen objektum helyett egy tömböt kell visszaadnia. Példa:

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

A Teljes PowerShell-példák függőben vannak.

Az alábbi példa egy eseményközpont eseményindító kötését és a kötést használó Python-függvényt mutatja be. A függvény üzenetet ír egy eseményközpontba. A példa attól függ, hogy a v1 vagy v2 Python programozási modellt használja-e.

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'

Az alábbi Python-kód több üzenetet küld:

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

Az alábbi példa egy Java-függvényt mutat be, amely az aktuális időt tartalmazó üzenetet ír egy eseményközpontba.

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

A Java-függvények futtatókörnyezeti kódtárában használja a széljegyzetet azon @EventHubOutput paramétereken, amelyek értéke közzé lesz téve az Event Hubsban. A paraméternek olyan típusúnak OutputBinding<T> kell lennie, ahol T a POJO vagy bármely natív Java-típus szerepel.

Attribútumok

A folyamaton belüli és az izolált feldolgozói folyamat C# kódtárai attribútummal konfigurálják a kötést. A C#-szkript ehelyett egy function.json konfigurációs fájlt használ a C#-szkriptelési útmutatóban leírtak szerint.

Az [EventHubOutputAttribute] használatával definiálhat kimeneti kötést egy eseményközponthoz, amely támogatja az alábbi tulajdonságokat.

Paraméterek Leírás
EventHubName Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. További információ: Csatlakozás.

Dekorátorok

Csak a Python v2 programozási modellre vonatkozik.

A dekoratőrrel definiált Python v2-függvények esetében a következő tulajdonságok a cosmos_db_triggerkövetkezők:

Tulajdonság Leírás
arg_name Az eseményt jelképező függvénykódban használt változónév.
event_hub_name az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot.
connection Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. További információ: Csatlakozás.

A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.

Jegyzetek

A Java-függvények futtatókörnyezeti kódtárában használja az EventHubOutput jegyzetet azon paramétereken, amelyeknek az értéke közzé lesz téve az Event Hubsban. A széljegyzet a következő beállításokat támogatja:

Konfiguráció

Csak a Python v1 programozási modellre vonatkozik.

Az alábbi táblázat a metódusnak output.eventHub() átadott objektumon options beállítható tulajdonságokat ismerteti.

Tulajdonság Leírás
eventHubName Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. További információ: Csatlakozás.

Az alábbi táblázat ismerteti a function.json fájlban beállított kötéskonfigurációs tulajdonságokat, amelyek futásidejű verziónként eltérnek.

function.json tulajdonság Leírás
type A beállításnak a eventHubkövetkezőnek kell lennie: .
direction A beállításnak a outkövetkezőnek kell lennie: . Ez a paraméter automatikusan be van állítva, amikor létrehozza a kötést az Azure Portalon.
név Az eseményt jelképező függvénykódban használt változónév.
eventHubName Függvények 2.x és újabb. Az eseményközpont neve. Ha az eseményközpont neve is szerepel a kapcsolati sztring, ez az érték futásidőben felülbírálja ezt a tulajdonságot.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Event Hubshoz. További információ: Csatlakozás.

Helyi fejlesztéskor adja hozzá az alkalmazásbeállításokat a gyűjtemény local.settings.json fájljáhozValues.

Használat

Az Event Hubs kimeneti kötés által támogatott paramétertípus a Functions futtatókörnyezet verziójától, a bővítménycsomag verziójától és a használt C# módtól függ.

Ha azt szeretné, hogy a függvény egyetlen eseményt írjon, az Event Hubs kimeneti kötése a következő típusokhoz kapcsolódhat:

Típus Leírás
string Az esemény sztringként. Akkor használja, ha az esemény egyszerű szöveg.
byte[] Az esemény bájtja.
JSON szerializálható típusok Az eseményt jelképező objektum. A Functions egy egyszerű régi CLR-objektum (POCO) típust próbál JSON-adatokká szerializálni.

Ha azt szeretné, hogy a függvény több eseményt írjon, az Event Hubs kimeneti kötése a következő típusokhoz köthet:

Típus Leírás
T[] ahol T az egyik egyetlen eseménytípus Több eseményt tartalmazó tömb. Minden bejegyzés egy eseményt jelöl.

Egyéb kimeneti forgatókönyvek esetén közvetlenül a Microsoft.Azure.EventHubsból hozhat létre és használhat típusokat .

Az EventHubOutput széljegyzet használatával kétféleképpen jelenítheti meg az Event Hubs-üzeneteket egy függvényből:

  • Visszatérési érték: Ha a széljegyzetet magára a függvényre alkalmazza, a függvény visszatérési értéke event Hubs-üzenetként marad meg.

  • Imperatív: Az üzenet értékének explicit beállításához alkalmazza a széljegyzetet a típus OutputBinding<T>egy adott paraméterére , ahol T a POJO vagy bármely natív Java-típus található. Ezzel a konfigurációval az értéknek a setValue metódusnak való átadása event Hubs-üzenetként megőrzi az értéket.

A Teljes PowerShell-példák függőben vannak.

A kimeneti üzenet eléréséhez adja vissza az értéket közvetlenül vagy a használatával context.extraOutputs.set().

Az Event Hubs-üzenetek függvényből való kimenetének két lehetősége van:

  • Visszatérési érték: Állítsa a tulajdonságot a name function.json értékre$return. Ezzel a konfigurációval a függvény visszatérési értéke Event Hubs-üzenetként marad meg.

  • Imperatív: Adjon át egy értéket a Ki típusúként deklarált paraméter beállított metódusának. Az átadott set érték Event Hubs-üzenetként marad meg.

Kapcsolatok

A connection tulajdonság a környezeti konfigurációra mutató hivatkozás, amely meghatározza, hogy az alkalmazásnak hogyan kell csatlakoznia az Event Hubshoz. A következőt határozhatja meg:

Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.

Kapcsolati sztring

Ezt a kapcsolati sztring a névtér Csatlakozás ion Information gombjára kattintva szerezheti be, és nem magát az eseményközpontot. A kapcsolati sztring egy Event Hubs-névtérnek kell lennie, nem magának az eseményközpontnak.

Eseményindítók esetén a kapcsolati sztring legalább "olvasási" engedélyekkel kell rendelkeznie a függvény aktiválásához. Kimeneti kötésekhez használva a kapcsolati sztring "küldési" engedéllyel kell rendelkeznie ahhoz, hogy üzeneteket küldjön az eseménystreambe.

Ezt a kapcsolati sztring a kötéskonfiguráció tulajdonsága által connection megadott értéknek megfelelő névvel rendelkező alkalmazásbeállításban kell tárolni.

Identitásalapú kapcsolatok

Ha a bővítmény 5.x vagy újabb verzióját használja, ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Ehhez meg kell határoznia a beállításokat egy közös előtag alatt, amely leképezi a connection tulajdonságot az eseményindító és a kötés konfigurációjában.

Ebben a módban a bővítményhez a következő tulajdonságok szükségesek:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Teljes névtér <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace A teljes mértékben minősített Event Hubs-névtér. myeventhubns.servicebus.windows.net

További tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.

Feljegyzés

Ha Azure-alkalmazás konfigurációt vagy Key Vaultot használ a felügyelt identitáskapcsolatok beállításainak megadásához, a beállítások neveinek egy érvényes kulcselválasztót kell használniuk, például : a __ helyett, / hogy a nevek megfelelően legyenek feloldva.

Például: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential tulajdonságokkal együtt clientID . Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.

Engedély megadása az identitáshoz

Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.

Fontos

A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.

Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít az eseményközponthoz. A szerepkör-hozzárendelés hatóköre lehet egy Event Hubs-névtér vagy maga az eseményközpont. A tulajdonoshoz hasonló felügyeleti szerepkörök nem elegendőek. Az alábbi táblázat olyan beépített szerepköröket mutat be, amelyek az Event Hubs-bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.

Kötés típusa Példa beépített szerepkörökre
Eseményindító Azure Event Hubs-adatátvevő, Azure Event Hubs-adattulajdonos
Kimeneti kötés Azure Event Hubs-adatküldő

Kivételek és visszatérési kódok

Kötés Referencia
Event Hubs Üzemeltetési útmutató

Következő lépések