Azure IoT Hub-kötések az Azure Functionshez

  • Cikk

Ez a cikksorozat bemutatja, hogyan használható az Azure Functions-kötések az IoT Hubhoz. Az IoT Hub támogatása az Azure Event Hubs-kötésen alapul.

Fontos

Bár a következő kódminták az Event Hub API-t használják, a megadott szintaxis az IoT Hub-függvényekre vonatkozik.

Művelet Típus
Válasz az IoT Hub eseménystreamjének küldött eseményekre. Eseményindító

A bővítmény telepítése

A telepített NuGet-csomag a függvényalkalmazásban használt C# módtól függ:

A függvények izolált C# feldolgozói folyamatban futnak. További információ: Útmutató a C# Azure Functions izolált feldolgozói folyamatban való futtatásához.

A bővítmény funkciói a bővítmény verziójától függően változnak:

Ez a verzió lehetővé teszi, hogy titkos kulcs helyett identitással csatlakozzon. A függvényalkalmazások felügyelt identitásokkal való konfigurálásáról szóló oktatóanyagot az identitásalapú kapcsolatokkal rendelkező függvényalkalmazások létrehozásáról szóló oktatóanyagban tekintheti meg.

Adja hozzá a bővítményt a projekthez az 5.x-es verziójú NuGet-csomag telepítésével.

Csomag telepítése

Az Event Hubs-bővítmény egy bővítménycsomag része, amely a host.json projektfájlban van megadva. Előfordulhat, hogy módosítania kell ezt a csomagot a kötés verziójának módosításához, vagy ha a csomagok még nincsenek telepítve. További információkért tekintse meg a bővítménycsomagot.

Ez a verzió lehetővé teszi, hogy titkos kulcs helyett identitással csatlakozzon. A függvényalkalmazások felügyelt identitásokkal való konfigurálásáról szóló oktatóanyagot az identitásalapú kapcsolatokkal rendelkező függvényalkalmazások létrehozásáról szóló oktatóanyagban tekintheti meg.

A bővítmény ezen verzióját a 3. verziójú bővítménycsomagból is hozzáadhatja, ha hozzáadja vagy lecseréli a következő kódot a host.json fájlban:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

További információ: Bővítmények frissítése.

Kötéstípusok

A .NET-hez támogatott kötéstípusok a bővítményverziótól és a C# végrehajtási módtól is függenek, ami az alábbiak egyike lehet:

A C# függvényt lefordított izolált feldolgozói folyamatosztály-kódtár a futtatókörnyezettől elkülönített folyamatban fut.

Válasszon ki egy verziót a mód és a verzió kötéstípusának részleteinek megtekintéséhez.

Az izolált feldolgozó folyamat az alábbi táblázatoknak megfelelően támogatja a paramétertípusokat. Az Azure.Messaging.EventHubs-ból származó típusokhoz való kötés támogatása előzetes verzióban érhető el.

Event Hubs-eseményindító

Ha azt szeretné, hogy a függvény egyetlen eseményt dolgoz fel, az Event Hubs-eseményindító 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 Ha egy esemény JSON-adatokat tartalmaz, a Functions megpróbálja deszerializálni a JSON-adatokat egy egyszerű régi CLR-objektum (POCO) típusba.
Azure.Messaging.EventHubs.EventData1 Az eseményobjektum.
Ha az Event Hubs SDK-k bármely régebbi verziójából migrál, vegye figyelembe, hogy ez a verzió nem támogatja az örökölt Body típust az EventBody javára.

Ha azt szeretné, hogy a függvény feldolgozza az események kötegét, az Event Hubs-eseményindító a következő típusokhoz kapcsolódhat:

Típus Leírás
string[] A kötegből származó események tömbje sztringként. Minden bejegyzés egy eseményt jelöl.
EventData[]1 A kötegből származó események tömbje az Azure.Messaging.EventHubs.EventData példányaként. Minden bejegyzés egy eseményt jelöl.
T[] ahol T egy JSON szerializálható típus1 A kötegből származó események tömbje egyéni POCO-típus példányaként. Minden bejegyzés egy eseményt jelöl.

1 Ezeknek a típusoknak a használatához hivatkoznia kell a Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0-s vagy újabb verziójára, valamint az SDK-típuskötések gyakori függőségeire.

Event Hubs kimeneti kötés

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 .

host.json beállítások

A host.json fájl az Event Hubs-eseményindító viselkedését vezérlő beállításokat tartalmaz. A konfiguráció a bővítmény verziójától függően eltérő.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Tulajdonság Alapértelmezett Leírás
maxEventBatchSize2 100 A kötegekben szereplő események maximális száma egyetlen meghíváshoz. Legalább 1-nek kell lennie.
minEventBatchSize1 0 A kötegben kívánt események minimális száma. A minimum csak akkor érvényes, ha a függvény több eseményt fogad, és kisebbnek kell lennie.maxEventBatchSize
A minimális méret nem szigorúan garantált. Egy részleges köteg akkor lesz elküldve, ha a teljes köteg nem készíthető el a maxWaitTime leteltéig. A részleges kötegek valószínűleg a függvény skálázás utáni első meghívásához is szükségesek.
maxWaitTime1 00:01:00 Az a maximális időköz, amelyet az eseményindítónak várnia kell egy köteg kitöltésére a függvény meghívása előtt. A várakozási idő csak akkor számít, ha minEventBatchSize nagyobb, mint 1, és egyébként figyelmen kívül hagyja. Ha a várakozási idő eltelte előtt kevesebb minEventBatchSize esemény volt elérhető, a függvény részleges köteggel lesz meghívva. A leghosszabb várakozási idő 10 perc.

MEGJEGYZÉS: Ez az intervallum nem garantálja a függvény meghívásának pontos időzítését. Az időzítő pontossága miatt kis hiba van. A skálázás során előfordulhat, hogy a részleges köteggel történő első hívás gyorsabban fordul elő, vagy akár a konfigurált várakozási idő kétszeresét is igénybe veheti.
batchCheckpointFrequency 0 Az eseményközpont ellenőrzőpontjának létrehozása előtt feldolgozandó kötegek száma.
prefetchCount 300 Az Event Hubstól kért és a helyi gyorsítótárban tárolt események száma, amelyek lehetővé teszik az olvasást a hálózati műveletre való várakozás elkerülése érdekében
transportType amqpTcp Az Event Hubs szolgáltatással való kommunikációhoz használt protokoll és átvitel. Elérhető lehetőségek: amqpTcp, amqpWebSockets
webProxy null Az Event Hubs webes szoftvercsatornákon keresztüli kommunikációjához használható proxy. Az átvitelhez amqpTcp nem használható proxy.
customEndpointAddress null Az Event Hubs-kapcsolat létrehozásakor használandó cím, amely lehetővé teszi a hálózati kérések átirányítását egy alkalmazásátjárón vagy a gazdagépkörnyezethez szükséges egyéb útvonalon. Az eseményközpont teljes névterére akkor is szükség van, ha egyéni végpontcímet használ, és explicit módon vagy a kapcsolati sztring keresztül kell megadni.
targetUnprocessedEventThreshold1 null A feldolgozatlan események kívánt száma függvénypéldányonként. A küszöbértéket a célalapú skálázásban használják a beállításból származó alapértelmezett méretezési maxEventBatchSize küszöbérték felülbírálásához. Ha be van állítva, a feldolgozatlan események teljes száma el van osztva ezzel az értékkel a szükséges függvénypéldányok számának meghatározásához. A példányok száma egy kiegyensúlyozott partícióeloszlást létrehozó számra lesz kerekítve.
initialOffsetOptions/type fromStart Az eseménystreamben található hely, amely akkor kezdi el a feldolgozást, ha egy ellenőrzőpont nem létezik a tárolóban. Az összes partícióra vonatkozik. További információkért tekintse meg az OffsetType dokumentációját. Elérhető lehetőségek: fromStart, , fromEndfromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Megadja az esemény lekérdezett időpontját a streamben, amelyből megkezdi a feldolgozást. Ha initialOffsetOptions/type konfigurálva fromEnqueuedTimevan, ez a beállítás kötelező. Támogatja az időt a DateTime.Parse() által támogatott bármely formátumban, például2020-10-26T20:31Z. Az egyértelműség kedvéért meg kell adnia egy időzónát is. Ha nincs megadva az időzóza, a Functions a függvényalkalmazást futtató gép helyi időzónáját feltételezi, amely UTC az Azure-ban való futtatáskor.
clientRetryOptions/mode Exponenciális Az újrapróbálkozási késések kiszámításának módszere. Az exponenciális mód egy olyan háttérstratégián alapuló késleltetéssel próbálja újrapróbálkozásokat elvégezni, ahol minden kísérlet növeli az újrapróbálkozás előtt várakozó időtartamot. A rögzített módú újrapróbálkozások rögzített időközönként kísérlik meg az egyes késleltetéseket konzisztens időtartammal. Elérhető lehetőségek: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Az Event Hubs-művelet végrehajtásának maximális időtartama kísérletenként.
clientRetryOptions/delay 00:00:00.80 Az újrapróbálkozási kísérletek közötti alkalmazás késleltetési vagy visszalépési tényezője.
clientRetryOptions/maximumDelay 00:00:01 Az újrapróbálkozási kísérletek közötti maximális késleltetés.
clientRetryOptions/maximumRetries 3 Az újrapróbálkozások maximális száma, mielőtt a társított művelet sikertelennek tekintené.

1 A csomag 5.3.0-s vagy újabb verziójának használata minEventBatchSize és maxWaitTime megköveteléseMicrosoft.Azure.WebJobs.Extensions.EventHubs.

2 A csomag 6.0.0-sMicrosoft.Azure.WebJobs.Extensions.EventHubs verziójának alapértelmezett maxEventBatchSize módosítása. A korábbi verziókban ez 10 volt.

Ezekkel clientRetryOptions újrapróbálkozhat a Functions-gazdagép és az Event Hubs között (például események beolvasása és események küldése). Tekintse meg az Azure Functions hibakezelésével és újrapróbálkozásával kapcsolatos útmutatást az újrapróbálkozási szabályzatok egyes függvényekre való alkalmazásával kapcsolatban.

Az Azure Functions 2.x-ben és azon túli host.json az Azure Functions host.json referenciájában talál.

Következő lépések