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

• Wersja 1
• Wersja 2 lub nowsza

W tym zestawie artykułów wyjaśniono, jak pracować z powiązaniami usługi Azure Cosmos DB w usłudze Azure Functions w wersji 2.x i nowszej. 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

Uwaga

Ta dokumentacja dotyczy usługi Azure Functions w wersji 2.x i nowszej. Aby uzyskać informacje na temat używania tych powiązań w usłudze Functions 1.x, zobacz Powiązania usługi Azure Cosmos DB dla usługi Azure Functions 1.x.

To powiązanie pierwotnie nosiło nazwę DocumentDB. W usłudze Azure Functions w wersji 2.x i nowszej wyzwalacz, powiązania i pakiet mają nazwę Azure Cosmos DB.

Obsługiwane interfejsy API

Powiązania usługi Azure Cosmos DB są obsługiwane tylko do użycia z usługą Azure Cosmos DB for NoSQL. Obsługa usługi Azure Cosmos DB dla tabel jest zapewniana przy użyciu powiązań usługi Table Storage, począwszy od rozszerzenia 5.x. W przypadku wszystkich innych interfejsów API usługi Azure Cosmos DB należy uzyskać dostęp do bazy danych z funkcji przy użyciu klienta statycznego dla interfejsu API, w tym usługi Azure Cosmos DB dla bazy danych MongoDB, usługi Azure Cosmos DB dla bazy danych Cassandra i usługi Azure Cosmos DB dla języka Apache Gremlin.

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

Rozszerzenie powiązań usługi Azure Cosmos DB jest częścią pakietu rozszerzenia określonego w pliku projektu host.json. Może być konieczne zmodyfikowanie tego pakietu, aby zmienić wersję powiązania lub jeśli pakiety nie zostały jeszcze zainstalowane. Aby dowiedzieć się więcej, zobacz pakiet rozszerzeń.

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.

Pakiet w wersji 4.x

Ta wersja pakietu zawiera wersję 4.x rozszerzenia powiązań usługi Azure Cosmos DB, które 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.

Tę wersję rozszerzenia można dodać z pakietu rozszerzeń w wersji zapoznawczej w wersji 4, dodając lub zastępując następujący kod w host.json pliku:

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

Aby dowiedzieć się więcej, zobacz Aktualizowanie rozszerzeń.

Pakiet w wersji 2.x i v3.x

Tę wersję rozszerzenia można zainstalować w aplikacji funkcji, rejestrując pakiet rozszerzeń w wersji 2.x lub 3.x.

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

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:

Type	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:

Type	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:

Type	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:

Type	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:

Type	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:

Type	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 typy i użyj ich bezpośrednio z witryny Microsoft.Azure.Cosmos .

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.

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 wersjach 2.x i nowszych. Ustawienia w pliku host.json mają zastosowanie do wszystkich funkcji w wystąpieniu aplikacji funkcji. Poniższy przykładowy plik host.json zawiera tylko ustawienia wersji 2.x+ dla tego powiązania. Aby uzyskać więcej informacji na temat ustawień konfiguracji aplikacji funkcji w wersjach 2.x i nowszych, 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 to Direct i Gateway
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 to Direct i Gateway
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)