Přehled triggerů a vazeb služby Azure Cosmos DB pro Azure Functions

Tato sada článků vysvětluje, jak pracovat s vazbami služby Azure Cosmos DB ve službě Azure Functions. Azure Functions podporuje aktivační, vstupní a výstupní vazby pro službu Azure Cosmos DB.

Akce	Typ
Spuštění funkce při vytvoření nebo úpravě dokumentu Azure Cosmos DB	Spouštěč
Čtení dokumentu služby Azure Cosmos DB	Vstupní vazba
Uložení změn do dokumentu azure Cosmos DB	Výstupní vazba

Důležité

Tato verze rozšíření vazeb Azure Cosmos DB podporuje Azure Functions verze 4.x. Pokud vaše aplikace stále používá verzi 1.x modulu runtime Functions, podívejte se místo toho na vazby Azure Cosmos DB pro Azure Functions 1.x. V modulu runtime Functions v1.x byla tato vazba původně pojmenována DocumentDB.

Podporovaná rozhraní API

Tato tabulka udává, jak se z kódu funkce připojit k různým rozhraním API služby Azure Cosmos DB:

API	Recommendation
Azure Cosmos DB for NoSQL	Použití rozšíření vazby služby Azure Cosmos DB
Azure Cosmos DB pro MongoDB	Použijte nativní klientskou sadu SDK.
Azure Cosmos DB pro tabulku	Použijte verzi 5.x nebo novější rozšíření vazby tabulek Azure.
Azure Cosmos DB pro Apache Cassandra	Použijte nativní klientskou sadu SDK.
Azure Cosmos DB pro Apache Gremlin (Graph API)	Použití nativní klientské sady SDK
Azure Cosmos DB for PostgreSQL	Použijte nativní klientskou sadu SDK.

Instalace rozšíření

Balíček NuGet rozšíření, který nainstalujete, závisí na režimu jazyka C#, který používáte ve své aplikaci funkcí:

Izolovaný model pracovního procesu

Funkce se spouštějí v izolovaném pracovním procesu C#. Další informace najdete v průvodci spuštěním služby Azure Functions v jazyce C# v izolovaném pracovním procesu.

Model v procesu

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

Funkce se spouštějí ve stejném procesu jako hostitel služby Functions. Další informace najdete v tématu Vývoj funkcí knihovny tříd jazyka C# pomocí Azure Functions.

Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Pokud chcete aktualizovat existující rozšíření vazeb pro aplikace skriptů jazyka C# spuštěné na portálu, aniž byste museli aplikaci funkcí znovu publikovat, přečtěte si téma Aktualizace rozšíření.

Postup instalace rozšíření se liší v závislosti na verzi rozšíření:

Rozšíření 4.x+

Tato část popisuje použití knihovny tříd. Pro skriptování jazyka C# byste museli místo toho nainstalovat sadu rozšíření verze 4.x.

Tato verze rozšíření vazeb Azure Cosmos DB představuje možnost připojení pomocí identity místo tajného kódu. Kurz konfigurace aplikací funkcí se spravovanými identitami najdete v kurzu vytvoření aplikace funkcí s připojeními založenými na identitách.

Tato verze také změní typy, se kterými se můžete svázat, a nahradí typy ze sady SDK Microsoft.Azure.DocumentDB v2 novějšími typy ze sady Microsoft.Azure.Cosmos SDK v3. Přečtěte si další informace o tom, jak se tyto nové typy liší a jak na ně migrovat z průvodce migrací sady SDK, triggeru, vstupní vazby a příkladů výstupních vazeb .

Tato verze rozšíření je k dispozici jako balíček NuGet verze 4.x.

Funkce 2.x+

Tato část popisuje použití knihovny tříd. Pro skriptování jazyka C# byste museli místo toho nainstalovat sadu rozšíření verze 2.x nebo 3.x.

Práce s triggerem a vazbami vyžaduje, abyste odkazovaly na příslušný balíček NuGet. Nainstalujte balíček NuGet verze 3.x.

Rozšíření 4.x+

Tato verze rozšíření vazeb Azure Cosmos DB představuje možnost připojení pomocí identity místo tajného kódu. Kurz konfigurace aplikací funkcí se spravovanými identitami najdete v kurzu vytvoření aplikace funkcí s připojeními založenými na identitách.

Přidejte rozšíření do projektu instalací balíčku NuGet verze 4.x.

Pokud píšete aplikaci pomocí F#, musíte toto rozšíření nakonfigurovat také jako součást konfigurace spuštění aplikace. Do volání ConfigureFunctionsWorkerDefaults() nebo ConfigureFunctionsWebApplication()přidejte delegáta, který přebírá IFunctionsWorkerApplication parametr. Potom v těle tohoto delegáta zavolejte ConfigureCosmosDBExtension() objekt:

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

Funkce 2.x+

Přidejte rozšíření do projektu instalací balíčku NuGet verze 3.x.

Instalace sady

Pokud chcete v aplikaci použít toto rozšíření vazeb, ujistěte se, že soubor host.json v kořenovém adresáři projektu obsahuje tento extensionBundle odkaz:

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

V tomto příkladu version hodnota [4.0.0, 5.0.0) dává hostiteli Functions pokyn, aby používal verzi sady, která je alespoň 4.0.0 , ale menší než 5.0.0, která zahrnuje všechny potenciální verze 4.x. Tato notace efektivně udržuje vaši aplikaci na nejnovější dostupné podverzi sady rozšíření v4.x.

Pokud je to možné, měli byste použít nejnovější hlavní verzi sady rozšíření a umožnit modulu runtime automaticky udržovat nejnovější podverzi. Obsah nejnovější sady můžete zobrazit na stránce verze sady rozšíření. Další informace najdete v sadách rozšíření Azure Functions.

Kvůli změnám schématu v sadě Sdk služby Azure Cosmos DB vyžaduje rozšíření Azure Cosmos DB verze 4.x azure-functions-java-library verze 3.0.0 pro funkce Java.

Typy vazeb

Typy vazeb podporované pro .NET závisí na režimu spouštění rozšíření i jazyka C#, což může být jedna z následujících možností:

Izolovaný model pracovního procesu

Kompilovaná funkce C# v izolované knihovně tříd pracovních procesů běží v procesu izolovaném od modulu runtime.

Model v procesu

Knihovna tříd v procesu je kompilovaná funkce jazyka C# spuštěná ve stejném procesu jako modul runtime služby Functions.

Zvolte verzi a zobrazte podrobnosti o typu vazby pro režim a verzi.

Rozšíření 4.x+

Rozšíření Azure Cosmos DB podporuje typy parametrů podle následující tabulky.

Scénář vazby	Typy parametrů
Trigger služby Cosmos DB (jeden dokument)	Serializovatelné typyJSON 1
Trigger služby Cosmos DB (dávka dokumentů)	IEnumerable<T>where T je serializovatelný typJSON 1
Vstup cosmos DB (jeden dokument)	Serializovatelné typyJSON 1
Vstup cosmos DB (dotaz vracející více dokumentů)	CosmosClient IEnumerable<T> where T je serializovatelný typJSON 1
Výstup služby Cosmos DB (jeden dokument)	Serializovatelné typyJSON 1
Výstup služby Cosmos DB (více dokumentů)	ICollector<T> nebo IAsyncCollector<T> kde T je serializovatelný typJSON 1

¹ Dokumenty obsahující data JSON lze deserializovat do známých typů objektů CLR (POCO).

Funkce 2.x+

Starší verze rozšíření vystavených typů z nově zastaralého oboru názvů Microsoft.Azure.Documents Novější typy z Microsoft.Azure.Cosmos jsou exkluzivní pro rozšíření 4.x a vyšší.

Rozšíření 4.x+

Izolovaný pracovní proces podporuje typy parametrů podle následujících tabulek. Podpora vazby na typy z Microsoft.Azure.Cosmosje ve verzi Preview.

Trigger služby Cosmos DB

Pokud chcete, aby funkce zpracovávala jeden dokument, trigger Cosmos DB může svázat s následujícími typy:

Typ	Popis
Serializovatelné typy JSON	Funkce se snaží deserializovat data JSON dokumentu z kanálu změn Cosmos DB do prostého typu objektu CLR (POCO).

Pokud chcete, aby funkce zpracovávala dávku dokumentů, trigger Cosmos DB může svázat s následujícími typy:

Typ	Popis
IEnumerable<T>where T je serializovatelný typ JSON	Výčet entit zahrnutých v dávce. Každá položka představuje jeden dokument z kanálu změn Cosmos DB.

Vstupní vazba Cosmos DB

Pokud chcete, aby funkce zpracovávala jeden dokument, vstupní vazba Cosmos DB může svázat s následujícími typy:

Typ	Popis
Serializovatelné typy JSON	Funkce se pokusí deserializovat data JSON dokumentu do prostého typu objektu CLR (POCO).

Pokud chcete, aby funkce zpracovávala více dokumentů z dotazu, vstupní vazba Cosmos DB může svázat s následujícími typy:

Typ	Popis
IEnumerable<T>where T je serializovatelný typ JSON	Výčet entit vrácených dotazem. Každá položka představuje jeden dokument.
CosmosClient1	Klient připojený k účtu Cosmos DB.
Databáze1	Klient připojený k databázi Cosmos DB.
Kontejner1	Klient připojený ke kontejneru Cosmos DB.

¹ Pokud chcete použít tyto typy, musíte odkazovat na Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 nebo novější a běžné závislosti pro vazby typu sady SDK.

Výstupní vazba Cosmos DB

Pokud chcete, aby funkce zapisuje do jednoho dokumentu, výstupní vazba Cosmos DB může svázat s následujícími typy:

Typ	Popis
Serializovatelné typy JSON	Objekt představující obsah JSON dokumentu. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisovat do více dokumentů, výstupní vazba Cosmos DB může svázat s následujícími typy:

Typ	Popis
T[] kde T je JSON serializovatelný typ	Pole obsahující více dokumentů. Každá položka představuje jeden dokument.

V případě jiných výstupních scénářů vytvořte a použijte CosmosClient s jinými typy z Microsoft.Azure.Cosmos přímo. Příklad použití injektáže závislostí k vytvoření typu klienta ze sady Azure SDK najdete v tématu Registrace klientů Azure.

Funkce 2.x+

Starší verze rozšíření v izolovaném pracovním procesu podporují pouze vazbu na serializovatelné typy JSON. Další možnosti jsou k dispozici pro rozšíření 4.x a vyšší.

Typy vazeb sady SDK

Podpora typu sady SDK pro Azure Cosmos je ve verzi Preview. Pokud chcete začít pracovat s typy sad SDK pro Cosmos v Pythonu, postupujte podle ukázek vazeb sady Python SDK pro Službu Cosmos DB .

Důležité

Použití vazeb typu sady SDK vyžaduje programovací model Pythonu v2.

---

Vazba	Typy parametrů	Vzorky
Vstup cosmos DB	ContainerProxy, CosmosClient, DatabaseProxy	ContainerProxy, CosmosClient, DatabaseProxy

---

Výjimky a návratové kódy

Vazba	Odkazy
Azure Cosmos DB	Stavové kódy HTTP pro službu Azure Cosmos DB

nastavení host.json

Tato část popisuje nastavení konfigurace dostupné pro tuto vazbu ve verzi 2.x a novější. Nastavení v souboru host.json platí pro všechny funkce v instanci aplikace funkcí. Další informace o nastavení konfigurace aplikace funkcí najdete v host.json referenčních informacích ke službě Azure Functions.

Rozšíření 4.x+

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

Vlastnost	Výchozí	Popis
connectionMode	Gateway	Režim připojení používaný funkcí při připojování ke službě Azure Cosmos DB. Možnosti: Direct Umožňuje připojení přímo k back-endovým replikám přes protokol TCP a může poskytovat nižší latenci a Gateway směrovat požadavky přes front-endovou bránu přes PROTOKOL HTTPS. Další informace najdete v tématu Režimy připojení sady SDK služby Azure Cosmos DB.
userAgentSuffix	Není k dispozici	Přidá zadanou řetězcovou hodnotu do všech požadavků provedených triggerem nebo vazbou ke službě. To usnadňuje sledování aktivity ve službě Azure Monitor na základě konkrétní aplikace funkcí a filtrování podle User Agent.

Funkce 2.x+

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

Vlastnost	Výchozí	Popis
connectionMode	Gateway	Režim připojení používaný funkcí při připojování ke službě Azure Cosmos DB. Možnosti: Direct Umožňuje připojení přímo k back-endovým replikám přes protokol TCP a může poskytovat nižší latenci a Gateway směrovat požadavky přes front-endovou bránu přes PROTOKOL HTTPS. Další informace najdete v tématu Režimy připojení sady SDK služby Azure Cosmos DB.
protokol	Https	Protokol připojení používaný funkcí při připojení ke službě Azure Cosmos DB. Tady najdete vysvětlení obou režimů.
leasePrefix	Není k dispozici	Předpona zapůjčení, která se použije ve všech funkcích v aplikaci.

Další kroky

• Spuštění funkce při vytvoření nebo změně dokumentu Azure Cosmos DB (trigger)
• Čtení dokumentu Azure Cosmos DB (vstupní vazba)
• Uložení změn do dokumentu Azure Cosmos DB (výstupní vazba)