Omówienie wyzwalacza i powiązań usługi Azure Cosmos DB dla usługi Azure Functions

W tym zestawie artykułów wyjaśniono, jak pracować z powiązaniami usługi Azure Cosmos DB w usłudze Azure Functions. Usługa Azure Functions obsługuje powiązania wyzwalacza, danych wejściowych i wyjściowych dla usługi Azure Cosmos DB.

Akcja	Typ
Uruchamianie funkcji po utworzeniu lub zmodyfikowaniu dokumentu usługi Azure Cosmos DB	Wyzwalacz
Odczytywanie dokumentu usługi Azure Cosmos DB	Powiązanie wejściowe
Zapisywanie zmian w dokumencie usługi Azure Cosmos DB	Powiązanie wyjściowe

Ważne

Ta wersja rozszerzenia powiązania usługi Azure Cosmos DB obsługuje usługę Azure Functions w wersji 4.x. Jeśli aplikacja nadal używa wersji 1.x środowiska uruchomieniowego usługi Functions, zamiast tego zobacz Powiązania usługi Azure Cosmos DB dla usługi Azure Functions 1.x. W środowisku uruchomieniowym usługi Functions w wersji 1.x to powiązanie pierwotnie nosiło nazwę DocumentDB.

Obsługiwane interfejsy API

W tej tabeli przedstawiono sposób nawiązywania połączenia z różnymi interfejsami API usługi Azure Cosmos DB z poziomu kodu funkcji:

API	Rekomendacja
Azure Cosmos DB for NoSQL	Korzystanie z rozszerzenia powiązania usługi Azure Cosmos DB
Usługa Azure Cosmos DB dla bazy danych MongoDB	Użyj natywnego zestawu SDK klienta.
Usługa Azure Cosmos DB dla tabeli	Użyj wersji 5.x lub nowszej rozszerzenia powiązania tabel platformy Azure.
Usługa Azure Cosmos DB dla bazy danych Apache Cassandra	Użyj natywnego zestawu SDK klienta.
Usługa Azure Cosmos DB dla języka Apache Gremlin (interfejs API programu Graph)	Korzystanie z natywnego zestawu SDK klienta
Azure Cosmos DB for PostgreSQL	Użyj natywnego zestawu SDK klienta.

Instalowanie rozszerzenia

Instalowany pakiet NuGet rozszerzenia zależy od trybu języka C#, którego używasz w aplikacji funkcji:

Model izolowanego procesu roboczego

Funkcje są wykonywane w izolowanym procesie roboczym języka C#. Aby dowiedzieć się więcej, zobacz Przewodnik dotyczący uruchamiania usługi Azure Functions w języku C# w izolowanym procesie roboczym.

Model w procesie

Ważne

Wsparcie zostanie zakończone dla modelu procesu 10 listopada 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do izolowanego modelu procesu roboczego w celu uzyskania pełnej obsługi.

Funkcje są wykonywane w tym samym procesie co host usługi Functions. Aby dowiedzieć się więcej, zobacz Tworzenie funkcji biblioteki klas języka C# przy użyciu usługi Azure Functions.

W odmianie tego modelu funkcje można uruchamiać przy użyciu skryptów języka C#, które są obsługiwane głównie w przypadku edytowania portalu języka C#. Aby zaktualizować istniejące rozszerzenia powiązań dla aplikacji skryptów języka C# uruchomionych w portalu bez konieczności ponownego publikowania aplikacji funkcji, zobacz Aktualizowanie rozszerzeń.

Proces instalowania rozszerzenia różni się w zależności od wersji rozszerzenia:

Rozszerzenie 4.x+

W tej sekcji opisano używanie biblioteki klas. W przypadku skryptów języka C# należy zamiast tego zainstalować pakiet rozszerzeń w wersji 4.x.

Ta wersja rozszerzenia powiązań usługi Azure Cosmos DB wprowadza możliwość nawiązywania połączenia przy użyciu tożsamości zamiast wpisu tajnego. Aby zapoznać się z samouczkiem dotyczącym konfigurowania aplikacji funkcji przy użyciu tożsamości zarządzanych, zobacz samouczek dotyczący tworzenia aplikacji funkcji z połączeniami opartymi na tożsamościach.

Ta wersja zmienia również typy, z którymi można powiązać, zastępując typy z zestawu SDK Microsoft.Azure.DocumentDB w wersji 2 nowszymi typami z zestawu SDK w wersji 3 Microsoft.Azure.Cosmos. Dowiedz się więcej o tym, jak te nowe typy są różne i jak przeprowadzić migrację do nich z przewodnika migracji zestawu SDK, wyzwalacza, powiązania wejściowego i powiązań wyjściowych.

Ta wersja rozszerzenia jest dostępna jako pakiet NuGet w wersji 4.x.

Funkcje 2.x+

W tej sekcji opisano używanie biblioteki klas. W przypadku skryptów języka C# należy zamiast tego zainstalować pakiet rozszerzeń w wersji 2.x lub 3.x.

Praca z wyzwalaczem i powiązaniami wymaga odwołania się do odpowiedniego pakietu NuGet. Zainstaluj pakiet NuGet w wersji 3.x.

Rozszerzenie 4.x+

Ta wersja rozszerzenia powiązań usługi Azure Cosmos DB wprowadza możliwość nawiązywania połączenia przy użyciu tożsamości zamiast wpisu tajnego. Aby zapoznać się z samouczkiem dotyczącym konfigurowania aplikacji funkcji przy użyciu tożsamości zarządzanych, zobacz samouczek dotyczący tworzenia aplikacji funkcji z połączeniami opartymi na tożsamościach.

Dodaj rozszerzenie do projektu, instalując pakiet NuGet w wersji 4.x.

Jeśli piszesz aplikację przy użyciu języka F#, musisz również skonfigurować to rozszerzenie w ramach konfiguracji uruchamiania aplikacji. W wywołaniu metody ConfigureFunctionsWorkerDefaults() lub ConfigureFunctionsWebApplication()dodaj delegata, który przyjmuje IFunctionsWorkerApplication parametr . Następnie w treści tego delegata wywołaj obiekt ConfigureCosmosDBExtension() :

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

Funkcje 2.x+

Dodaj rozszerzenie do projektu, instalując pakiet NuGet w wersji 3.x.

Instalowanie pakietu

Aby móc używać tego rozszerzenia powiązania w aplikacji, upewnij się, że plik host.json w katalogu głównym projektu zawiera następujące extensionBundle odwołanie:

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

W tym przykładzie version[4.0.0, 5.0.0) wartość polecenia nakazuje hostowi usługi Functions użycie wersji pakietu, która jest co najmniej 4.0.0 mniejsza niż 5.0.0, która zawiera wszystkie potencjalne wersje 4.x. Ta notacja skutecznie utrzymuje aplikację w najnowszej dostępnej wersji pomocniczej pakietu rozszerzenia v4.x.

Jeśli to możliwe, należy użyć najnowszej wersji głównej pakietu rozszerzeń i zezwolić środowisku uruchomieniowemu na automatyczne utrzymywanie najnowszej wersji pomocniczej. Zawartość najnowszego pakietu można wyświetlić na stronie wydania pakietów rozszerzeń. Aby uzyskać więcej informacji, zobacz Pakiety rozszerzeń usługi Azure Functions.

Ze względu na zmiany schematu w zestawie SDK usługi Azure Cosmos DB wersja 4.x rozszerzenia usługi Azure Cosmos DB wymaga biblioteki azure-functions-java-library w wersji 3.0.0 dla funkcji Języka Java.

Typy powiązań

Typy powiązań obsługiwane dla platformy .NET zależą zarówno od wersji rozszerzenia, jak i trybu wykonywania języka C#, który może być jednym z następujących elementów:

Model izolowanego procesu roboczego

Izolowana biblioteka klas procesów roboczych skompilowana funkcja języka C# jest uruchamiana w procesie odizolowanym od środowiska uruchomieniowego.

Model w procesie

Biblioteka klas w procesie jest skompilowaną funkcją języka C# uruchamianą w tym samym procesie co środowisko uruchomieniowe usługi Functions.

Wybierz wersję, aby wyświetlić szczegóły typu powiązania dla trybu i wersji.

Rozszerzenie 4.x+

Rozszerzenie usługi Azure Cosmos DB obsługuje typy parametrów zgodnie z poniższą tabelą.

Scenariusz wiązania	Typy parametrów
Wyzwalacz usługi Cosmos DB (pojedynczy dokument)	Typyserializacji JSON 1
Wyzwalacz usługi Cosmos DB (partia dokumentów)	IEnumerable<T>gdzie T jest typemserializowalnym JSON 1
Dane wejściowe usługi Cosmos DB (pojedynczy dokument)	Typyserializacji JSON 1
Dane wejściowe usługi Cosmos DB (zapytanie zwracające wiele dokumentów)	CosmosClient IEnumerable<T> gdzie T jest typemserializowalnym JSON 1
Dane wyjściowe usługi Cosmos DB (pojedynczy dokument)	Typyserializacji JSON 1
Dane wyjściowe usługi Cosmos DB (wiele dokumentów)	ICollector<T> lub IAsyncCollector<T> gdzie T jest serializowalnym typemJSON 1

¹ Dokumenty zawierające dane JSON mogą być deserializowane do znanych typów zwykłych obiektów CLR (POCO).

Funkcje 2.x+

Starsze wersje rozszerzenia uwidoczniły typy z przestarzałej przestrzeni nazw Microsoft.Azure.Documents . Nowsze typy z witryny Microsoft.Azure.Cosmos są przeznaczone wyłącznie do rozszerzenia 4.x i nowszych.

Rozszerzenie 4.x+

Proces izolowany proces roboczy obsługuje typy parametrów zgodnie z poniższymi tabelami. Obsługa powiązania z typami z witryny Microsoft.Azure.Cosmosjest dostępna w wersji zapoznawczej.

Wyzwalacz usługi Cosmos DB

Jeśli chcesz, aby funkcja przetwarzała pojedynczy dokument, wyzwalacz usługi Cosmos DB może powiązać z następującymi typami:

Typ	Opis
Typy serializowalne w formacie JSON	Usługa Functions próbuje wykonać deserializacji danych JSON dokumentu z zestawienia zmian usługi Cosmos DB na zwykły typ obiektu CLR (POCO).

Jeśli chcesz, aby funkcja przetwarzała partię dokumentów, wyzwalacz usługi Cosmos DB może powiązać z następującymi typami:

Typ	Opis
IEnumerable<T>gdzie T jest typem serializowalnym JSON	Wyliczenie jednostek uwzględnionych w partii. Każdy wpis reprezentuje jeden dokument ze źródła zmian usługi Cosmos DB.

Powiązanie wejściowe usługi Cosmos DB

Jeśli chcesz, aby funkcja przetwarzała pojedynczy dokument, powiązanie wejściowe usługi Cosmos DB może wiązać się z następującymi typami:

Typ	Opis
Typy serializowalne w formacie JSON	Funkcje próbują wykonać deserializacji danych JSON dokumentu w zwykły typ obiektu CLR (POCO).

Jeśli chcesz, aby funkcja przetwarzała wiele dokumentów z zapytania, powiązanie wejściowe usługi Cosmos DB może wiązać się z następującymi typami:

Typ	Opis
IEnumerable<T>gdzie T jest typem serializowalnym JSON	Wyliczenie jednostek zwróconych przez zapytanie. Każdy wpis reprezentuje jeden dokument.
CosmosClient1	Klient połączony z kontem usługi Cosmos DB.
Baza danych1	Klient połączony z bazą danych Cosmos DB.
Kontener1	Klient połączony z kontenerem usługi Cosmos DB.

¹ Aby użyć tych typów, należy odwołać się do elementów Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 lub nowszych oraz typowych zależności dla powiązań typu zestawu SDK.

Powiązanie wyjściowe usługi Cosmos DB

Jeśli chcesz, aby funkcja zapisywała w jednym dokumencie, powiązanie wyjściowe usługi Cosmos DB może wiązać się z następującymi typami:

Typ	Opis
Typy serializowalne w formacie JSON	Obiekt reprezentujący zawartość JSON dokumentu. Funkcje próbują serializować zwykły typ obiektu CLR (POCO) do danych JSON.

Jeśli chcesz, aby funkcja zapisywała w wielu dokumentach, powiązanie wyjściowe usługi Cosmos DB może wiązać się z następującymi typami:

Typ	Opis
T[] gdzie T jest typem serializowalnym JSON	Tablica zawierająca wiele dokumentów. Każdy wpis reprezentuje jeden dokument.

W przypadku innych scenariuszy wyjściowych utwórz obiekt CosmosClient i użyj go bezpośrednio z innymi typami z witryny Microsoft.Azure.Cosmos. Zobacz Rejestrowanie klientów platformy Azure, aby zapoznać się z przykładem użycia wstrzykiwania zależności w celu utworzenia typu klienta z zestawu Azure SDK.

Funkcje 2.x+

Wcześniejsze wersje rozszerzeń w izolowanym procesie roboczym obsługują powiązanie tylko z typami serializowalnymi w formacie JSON. Dodatkowe opcje są dostępne dla rozszerzenia 4.x i nowszych.

Typy powiązań zestawu SDK

Obsługa typów zestawu SDK dla usługi Azure Cosmos jest dostępna w wersji zapoznawczej. Postępuj zgodnie z przykładowymi powiązaniami zestawu SDK języka Python dla usługi CosmosDB , aby rozpocząć pracę z typami zestawu SDK dla usługi Cosmos w języku Python.

Ważne

Korzystanie z powiązań typu zestawu SDK wymaga modelu programowania w języku Python w wersji 2.

---

Wiązanie	Typy parametrów	Przykłady
Dane wejściowe usługi CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	ContainerProxy, CosmosClient, DatabaseProxy

---

Wyjątki i kody powrotne

Wiązanie	Odwołanie
Azure Cosmos DB	Kody stanu HTTP dla usługi Azure Cosmos DB

ustawienia host.json

W tej sekcji opisano ustawienia konfiguracji dostępne dla tego powiązania w wersji 2.x lub nowszej. Ustawienia w pliku host.json mają zastosowanie do wszystkich funkcji w wystąpieniu aplikacji funkcji. Aby uzyskać więcej informacji na temat ustawień konfiguracji aplikacji funkcji, zobacz host.json dokumentacja usługi Azure Functions.

Rozszerzenie 4.x+

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

Właściwości	Domyślny	Opis
connectionMode	Gateway	Tryb połączenia używany przez funkcję podczas nawiązywania połączenia z usługą Azure Cosmos DB. Opcje: Direct łączy się bezpośrednio z replikami zaplecza za pośrednictwem protokołu TCP i może zapewnić mniejsze opóźnienie, a Gateway żądania są kierowane przez bramę frontonu za pośrednictwem protokołu HTTPS. Aby uzyskać więcej informacji, zobacz Tryby połączenia zestawu SDK usługi Azure Cosmos DB.
userAgentSuffix	nie dotyczy	Dodaje określoną wartość ciągu do wszystkich żądań wysyłanych przez wyzwalacz lub powiązanie z usługą. Ułatwia to śledzenie aktywności w usłudze Azure Monitor w oparciu o określoną aplikację funkcji i filtrowanie według User Agent.

Funkcje 2.x+

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

Właściwości	Domyślny	Opis
connectionMode	Gateway	Tryb połączenia używany przez funkcję podczas nawiązywania połączenia z usługą Azure Cosmos DB. Opcje: Direct łączy się bezpośrednio z replikami zaplecza za pośrednictwem protokołu TCP i może zapewnić mniejsze opóźnienie, a Gateway żądania są kierowane przez bramę frontonu za pośrednictwem protokołu HTTPS. Aby uzyskać więcej informacji, zobacz Tryby połączenia zestawu SDK usługi Azure Cosmos DB.
protokół	Https	Protokół połączenia używany przez funkcję podczas nawiązywania połączenia z usługą Azure Cosmos DB. Przeczytaj tutaj, aby zapoznać się z wyjaśnieniem obu trybów.
leasePrefix	nie dotyczy	Prefiks dzierżawy do użycia we wszystkich funkcjach w aplikacji.

Następne kroki

• Uruchamianie funkcji po utworzeniu lub zmodyfikowaniu dokumentu usługi Azure Cosmos DB (wyzwalacza)
• Odczytywanie dokumentu usługi Azure Cosmos DB (powiązanie wejściowe)
• Zapisywanie zmian w dokumencie usługi Azure Cosmos DB (powiązanie wyjściowe)