Přehled triggerů a vazeb služby Azure Cosmos DB pro Azure Functions 2.x a vyšší

• Verze 1
• Verze 2 a vyšší

Tato sada článků vysvětluje, jak pracovat s vazbami služby Azure Cosmos DB ve službě Azure Functions 2.x a vyšší. 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	Trigger
Čtení dokumentu služby Azure Cosmos DB	Vstupní vazba
Uložení změn do dokumentu azure Cosmos DB	Výstupní vazba

Poznámka:

Tento odkaz je určený pro Azure Functions verze 2.x a vyšší. Informace o tom, jak tyto vazby používat ve službě Functions 1.x, najdete v tématu Vazby služby Azure Cosmos DB pro Azure Functions 1.x.

Tato vazba měla původně název DocumentDB. Ve službě Azure Functions verze 2.x a vyšší se aktivační událost, vazby a balíček nazývají Azure Cosmos DB.

Podporovaná rozhraní API

Vazby Azure Cosmos DB se podporují jenom pro použití se službou Azure Cosmos DB for NoSQL. Podpora služby Azure Cosmos DB pro tabulku je poskytována pomocí vazeb Table Storage počínaje rozšířením 5.x. Pro všechna ostatní rozhraní API služby Azure Cosmos DB byste měli přistupovat k databázi z vaší funkce pomocí statického klienta pro vaše rozhraní API, včetně Azure Cosmos DB pro MongoDB, Azure Cosmos DB for Cassandra a Azure Cosmos DB for Apache Gremlin.

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

Rozšíření vazeb Azure Cosmos DB je součástí sady rozšíření, která je zadaná v souboru projektu host.json . Možná budete muset tuto sadu upravit, aby se změnila verze vazby, nebo pokud sady ještě nejsou nainstalované. Další informace najdete v sadě rozšíření.

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.

Sada v4.x

Tato verze sady obsahuje verzi 4.x rozšíření vazeb Služby Azure Cosmos DB, které zavádí 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.

Tuto verzi rozšíření můžete přidat z sady rozšíření preview verze 4 přidáním nebo nahrazením následujícího kódu v host.json souboru:

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

Další informace najdete v tématu Aktualizace rozšíření.

Sada v2.x a v3.x

Tuto verzi rozšíření můžete nainstalovat do aplikace funkcí registrací sady rozšíření verze 2.x nebo 3.x.

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

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[] where T is JSON serializable type	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žívejte typy přímo z Microsoft.Azure.Cosmos .

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šší.

Výjimky a návratové kódy

Vazba	Reference
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 verzích 2.x a novějších. Nastavení v souboru host.json platí pro všechny funkce v instanci aplikace funkcí. Následující příklad host.json souboru obsahuje pouze nastavení verze 2.x+ pro tuto vazbu. Další informace o nastavení konfigurace aplikace funkcí ve verzích 2.x a novějších verzích 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 jsou Direct a Gateway
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 jsou Direct a Gateway
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)