Azure Cosmos DB-eseményindítók és kötések az Azure Functions 2.x-hez és magasabb szintű áttekintés

• 1-es verzió
• 2. és újabb verzió

Ez a cikkkészlet bemutatja, hogyan használható az Azure Cosmos DB-kötések az Azure Functions 2.x és újabb verzióiban. Az Azure Functions támogatja az Azure Cosmos DB trigger-, bemeneti és kimeneti kötéseit.

Művelet	Típus
Függvény futtatása Azure Cosmos DB-dokumentum létrehozásakor vagy módosításakor	Eseményindító
Azure Cosmos DB-dokumentum olvasása	Bemeneti kötés
Azure Cosmos DB-dokumentum módosításainak mentése	Kimeneti kötés

Feljegyzés

Ez a hivatkozás az Azure Functions 2.x és újabb verziójára vonatkozik. A kötések a Functions 1.x-ben való használatáról az Azure Functions 1.x-hez készült Azure Cosmos DB-kötések című témakörben olvashat.

Ezt a kötést eredetileg DocumentDB-nek hívták. Az Azure Functions 2.x és újabb verzióiban az eseményindító, a kötések és a csomag neve Azure Cosmos DB.

Támogatott API-k

Az Azure Cosmos DB-kötések csak az Azure Cosmos DB for NoSQL-hez használhatók. Az Azure Cosmos DB for Table támogatása a Table Storage-kötések használatával érhető el, kezdve az 5.x kiterjesztéssel. Az összes többi Azure Cosmos DB API esetében a függvényből kell elérnie az adatbázist az API statikus ügyfélalkalmazásával, beleértve a MongoDB-hez készült Azure Cosmos DB-t, a Cassandra-hoz készült Azure Cosmos DB-t és az Apache Gremlinhez készült Azure Cosmos DB-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:

Izolált feldolgozói modell

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.

Folyamaton belüli modell

Fontos

A folyamaton belüli modell támogatása 2026. november 10-én megszűnik. Erősen javasoljuk, hogy az alkalmazásokat az elkülönített feldolgozói modellbe migrálja a teljes támogatás érdekében.

A függvények ugyanabban a folyamatban futnak, mint a Functions-gazdagép. További információ: C# osztálykódtárfüggvények fejlesztése az Azure Functions használatával.

A modell egy változatában a Functions C#-szkriptekkel futtatható, amely elsősorban a C#-portál szerkesztéséhez támogatott. Ha a portálon futó C#-szkriptalkalmazások meglévő kötésbővítményeit szeretné frissíteni a függvényalkalmazás újbóli közzététele nélkül, olvassa el a bővítmények frissítése című témakört.

A bővítmény telepítésének folyamata a bővítmény verziójától függően változik:

4.x+ bővítmény

Ez a szakasz egy osztálytár használatát ismerteti. A C#-szkripteléshez ehelyett telepítenie kell a bővítménycsomagot, a 4.x-es verziót.

Az Azure Cosmos DB kötések bővítményének ezen verziója 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.

Ez a verzió azokat a típusokat is módosítja, amelyekhez kapcsolódhat, és a v2 SDK-ból Microsoft.Azure.DocumentDB származó típusokat a Microsoft.Azure.Cosmos v3 SDK újabb típusaira cseréli. Az SDK migrálási útmutatójából, az eseményindítóból, a bemeneti kötésből és a kimeneti kötési példákból megtudhatja, hogyan különböznek ezek az új típusok, és hogyan migrálhatók hozzájuk.

Ez a bővítményverzió NuGet-csomagként, 4.x-es verzióként érhető el.

Functions 2.x+

Ez a szakasz egy osztálytár használatát ismerteti. A C#-szkriptekhez ehelyett telepítenie kell a bővítménycsomagot, a 2.x vagy a 3.x verziót.

Az eseményindító és kötések használatához a megfelelő NuGet-csomagra kell hivatkozni. Telepítse a NuGet 3.x-es verzióját.

4.x+ bővítmény

Az Azure Cosmos DB kötések bővítményének ezen verziója 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 a NuGet-csomag 4.x-es verziójának telepítésével.

Ha az alkalmazást az F# használatával írja, ezt a bővítményt is konfigurálnia kell az alkalmazás indítási konfigurációjának részeként. A hívásban ConfigureFunctionsWorkerDefaults()ConfigureFunctionsWebApplication()adjon hozzá egy paramétert használó meghatalmazottat IFunctionsWorkerApplication . Ezután a meghatalmazott törzsén belül hívja meg ConfigureCosmosDBExtension() az objektumot:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Functions 2.x+

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

Csomag telepítése

Az Azure Cosmos DB kötések bővítménye 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.

Az Azure Cosmos DB SDK sémaváltozásai miatt az Azure Cosmos DB-bővítmény 4.x verziójához a Java-függvényekhez azure-functions-java-library V3.0.0 szükséges.

Csomag v4.x

A csomag ezen verziója az Azure Cosmos DB kötések bővítményének 4.x verzióját tartalmazza, amely 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 4-es verziójú előzetes 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.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

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

Csomag v2.x és v3.x

A bővítmény ezen verzióját a függvényalkalmazásban a bővítménycsomag 2.x vagy 3.x verziójának regisztrálásával telepítheti.

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

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:

Izolált feldolgozói modell

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.

Folyamaton belüli modell

A folyamatközi osztálykódtár egy lefordított C# függvény, amely ugyanabban a folyamatban fut, mint a Functions-futtatókörnyezet.

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

4.x+ bővítmény

Az Azure Cosmos DB-bővítmény az alábbi táblázatnak megfelelően támogatja a paramétertípusokat.

Kötési forgatókönyv	Paramétertípusok
Cosmos DB-eseményindító (egyetlen dokumentum)	JSON szerializálhatótípusok 1
Cosmos DB-eseményindító (dokumentumköteg)	IEnumerable<T>ahol T egy JSON szerializálható típus1
Cosmos DB-bemenet (egy dokumentum)	JSON szerializálhatótípusok 1
Cosmos DB-bemenet (több dokumentumot visszaadó lekérdezés)	CosmosClient IEnumerable<T> ahol T egy JSON szerializálható típus1
Cosmos DB-kimenet (egyetlen dokumentum)	JSON szerializálhatótípusok 1
Cosmos DB-kimenet (több dokumentum)	ICollector<T> vagy IAsyncCollector<T> hol T a JSON szerializálható típusa1

¹ A JSON-adatokat tartalmazó dokumentumok ismert egyszerű CLR-objektumtípusokba (POCO) deszerializálhatók.

Functions 2.x+

A bővítmény korábbi verziói a már elavult Microsoft.Azure.Documents névtérből származó típusok. A Microsoft.Azure.Cosmos újabb típusai kizárólag a 4.x és újabb bővítményeket tartalmazzák.

4.x+ bővítmény

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

Cosmos DB-eseményindító

Ha azt szeretné, hogy a függvény egyetlen dokumentumot dolgoz fel, a Cosmos DB-eseményindító a következő típusokhoz tud kapcsolódni:

Típus	Leírás
JSON szerializálható típusok	A Functions megpróbálja deszerializálni a dokumentum JSON-adatait a Cosmos DB változáscsatornájából egy egyszerű régi CLR-objektum (POCO) típusba.

Ha azt szeretné, hogy a függvény feldolgozza a dokumentumok kötegét, a Cosmos DB-eseményindító a következő típusokhoz tud kapcsolódni:

Típus	Leírás
IEnumerable<T>ahol T egy JSON szerializálható típus	A kötegben szereplő entitások számbavétele. Minden bejegyzés egy dokumentumot jelöl a Cosmos DB változáscsatornájából.

Cosmos DB bemeneti kötés

Ha azt szeretné, hogy a függvény egyetlen dokumentumot dolgoz fel, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:

Típus	Leírás
JSON szerializálható típusok	A Functions megpróbálja deszerializálni a dokumentum JSON-adatait egy egyszerű régi CLR-objektum (POCO) típusba.

Ha azt szeretné, hogy a függvény több dokumentumot dolgoz fel egy lekérdezésből, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:

Típus	Leírás
IEnumerable<T>ahol T egy JSON szerializálható típus	A lekérdezés által visszaadott entitások számbavétele. Minden bejegyzés egy dokumentumot jelöl.
CosmosClient1	A Cosmos DB-fiókhoz csatlakoztatott ügyfél.
1. adatbázis	A Cosmos DB-adatbázishoz csatlakoztatott ügyfél.
1. tároló	A Cosmos DB-tárolóhoz csatlakoztatott ügyfél.

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

Cosmos DB kimeneti kötés

Ha azt szeretné, hogy a függvény egyetlen dokumentumba írjon, a Cosmos DB kimeneti kötése a következő típusokhoz köthet:

Típus	Leírás
JSON szerializálható típusok	Egy dokumentum JSON-tartalmát képviselő 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 dokumentumba írjon, a Cosmos DB kimeneti kötése a következő típusokhoz köthet:

Típus	Leírás
T[] hol T van JSON szerializálható típus	Több dokumentumot tartalmazó tömb. Minden bejegyzés egy dokumentumot jelöl.

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

Functions 2.x+

Az izolált feldolgozó folyamat bővítményeinek korábbi verziói csak jSON szerializálható típusok kötését támogatják. További lehetőségek érhetők el a 4.x és újabb bővítményhez.

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

Kötés	Referencia
Azure Cosmos DB	HTTP-állapotkódok az Azure Cosmos DB-hez

host.json beállítások

Ez a szakasz a kötéshez elérhető konfigurációs beállításokat ismerteti a 2.x és újabb verziókban. Gépház a host.json fájlban egy függvényalkalmazás-példány összes függvényére vonatkozik. Az alábbi példában host.json fájl csak a kötés 2.x+ verziójának beállításait tartalmazza. A függvényalkalmazások konfigurációs beállításairól a 2.x és újabb verziókban host.json Azure Functionsre vonatkozó hivatkozásban talál további információt.

4.x+ bővítmény

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Tulajdonság	Alapértelmezett	Leírás
connectionMode	Gateway	A függvény által az Azure Cosmos DB szolgáltatáshoz való csatlakozáskor használt kapcsolati mód. A beállítások a következők:DirectGateway
userAgentSuffix	n.a.	Hozzáadja a megadott sztringértéket az eseményindító vagy kötés által a szolgáltatáshoz küldött összes kéréshez. Ez megkönnyíti a tevékenység nyomon követését az Azure Monitorban egy adott függvényalkalmazás alapján, és szűréssel User Agent.

Functions 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Tulajdonság	Alapértelmezett	Leírás
connectionMode	Gateway	A függvény által az Azure Cosmos DB szolgáltatáshoz való csatlakozáskor használt kapcsolati mód. A beállítások a következők:DirectGateway
Protokoll	Https	A függvény által az Azure Cosmos DB szolgáltatáshoz való csatlakozáskor használt kapcsolati protokoll. A két mód magyarázatát itt olvashatja el.
leasePrefix	n.a.	Előtag bérlete az alkalmazás összes függvényéhez.

Következő lépések

• Függvény futtatása Azure Cosmos DB-dokumentum létrehozásakor vagy módosításakor (trigger)
• Azure Cosmos DB-dokumentum olvasása (bemeneti kötés)
• Azure Cosmos DB-dokumentum módosításainak mentése (kimeneti kötés)