This set of articles explains how to work with Azure Cosmos DB bindings in Azure Functions 2.x and higher. Azure Functions supports trigger, input, and output bindings for Azure Cosmos DB.
Action Type Run a function when an Azure Cosmos DB document is created or modified Trigger Read an Azure Cosmos DB document Input binding Save changes to an Azure Cosmos DB document Output binding Supported APIsAzure Cosmos DB bindings are only supported for use with Azure Cosmos DB for NoSQL. Support for Azure Cosmos DB for Table is provided by using the Table storage bindings, starting with extension 5.x. For all other Azure Cosmos DB APIs, you should access the database from your function by using the static client for your API, including Azure Cosmos DB for MongoDB, Azure Cosmos DB for Cassandra, and Azure Cosmos DB for Apache Gremlin.
Install extensionThe extension NuGet package you install depends on the C# mode you're using in your function app:
The process for installing the extension varies depending on the extension version:
This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 4.x.
This version of the Azure Cosmos DB bindings extension introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.
This version also changes the types that you can bind to, replacing the types from the v2 SDK Microsoft.Azure.DocumentDB with newer types from the v3 SDK Microsoft.Azure.Cosmos. Learn more about how these new types are different and how to migrate to them from the SDK migration guide, trigger, input binding, and output binding examples.
This extension version is available as a NuGet package, version 4.x.
This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 2.x or 3.x.
Working with the trigger and bindings requires that you reference the appropriate NuGet package. Install the NuGet package, version 3.x.
This version of the Azure Cosmos DB bindings extension introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.
Add the extension to your project by installing the NuGet package, version 4.x.
If you're writing your application using F#, you must also configure this extension as part of the app's startup configuration. In the call to ConfigureFunctionsWorkerDefaults() or ConfigureFunctionsWebApplication(), add a delegate that takes an IFunctionsWorkerApplication parameter. Then within the body of that delegate, call ConfigureCosmosDBExtension() on the object:
let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore
Add the extension to your project by installing the NuGet package, version 3.x.
Install bundleThe Azure Cosmos DB bindings extension is part of an extension bundle, which is specified in your host.json project file. You may need to modify this bundle to change the version of the binding, or if bundles aren't already installed. To learn more, see extension bundle.
Because of schema changes in the Azure Cosmos DB SDK, version 4.x of the Azure Cosmos DB extension requires azure-functions-java-library V3.0.0 for Java functions.
This version of the bundle contains version 4.x of the Azure Cosmos DB bindings extension that introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.
You can add this version of the extension from the preview extension bundle v4 by adding or replacing the following code in your host.json file:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
"version": "[4.0.0, 5.0.0)"
}
}
To learn more, see Update your extensions.
You can install this version of the extension in your function app by registering the extension bundle, version 2.x or 3.x.
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[3.3.0, 4.0.0)"
}
}
The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following:
An isolated worker process class library compiled C# function runs in a process isolated from the runtime.
An in-process class library is a compiled C# function runs in the same process as the Functions runtime.
Choose a version to see binding type details for the mode and version.
The Azure Cosmos DB extension supports parameter types according to the table below.
Binding scenario Parameter types Cosmos DB trigger (single document) JSON serializable types1 Cosmos DB trigger (batch of documents)IEnumerable<T>where T is a JSON serializable type1 Cosmos DB input (single document) JSON serializable types1
IEnumerable<T> where T is a JSON serializable type1 Cosmos DB output (single document) JSON serializable types1 Cosmos DB output (multiple documents) ICollector<T> or IAsyncCollector<T> where T is a JSON serializable type1
1 Documents containing JSON data can be deserialized into known plain-old CLR object (POCO) types.
Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.Documents namespace. Newer types from Microsoft.Azure.Cosmos are exclusive to extension 4.x and higher.
The isolated worker process supports parameter types according to the tables below. Support for binding to types from Microsoft.Azure.Cosmosis in preview.
Cosmos DB trigger
When you want the function to process a single document, the Cosmos DB trigger can bind to the following types:
Type Description JSON serializable types Functions tries to deserialize the JSON data of the document from the Cosmos DB change feed into a plain-old CLR object (POCO) type.When you want the function to process a batch of documents, the Cosmos DB trigger can bind to the following types:
Type DescriptionIEnumerable<T>where T is a JSON serializable type An enumeration of entities included in the batch. Each entry represents one document from the Cosmos DB change feed.
Cosmos DB input binding
When you want the function to process a single document, the Cosmos DB input binding can bind to the following types:
Type Description JSON serializable types Functions attempts to deserialize the JSON data of the document into a plain-old CLR object (POCO) type.When you want the function to process multiple documents from a query, the Cosmos DB input binding can bind to the following types:
Type DescriptionIEnumerable<T>where T is a JSON serializable type An enumeration of entities returned by the query. Each entry represents one document. CosmosClient1 A client connected to the Cosmos DB account. Database1 A client connected to the Cosmos DB database. Container1 A client connected to the Cosmos DB container.
1 To use these types, you need to reference Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 or later and the common dependencies for SDK type bindings.
Cosmos DB output binding
When you want the function to write to a single document, the Cosmos DB output binding can bind to the following types:
Type Description JSON serializable types An object representing the JSON content of a document. Functions attempts to serialize a plain-old CLR object (POCO) type into JSON data.When you want the function to write to multiple documents, the Cosmos DB output binding can bind to the following types:
Type DescriptionT[] where T is JSON serializable type An array containing multiple documents. Each entry represents one document.
For other output scenarios, create and use a CosmosClient with other types from Microsoft.Azure.Cosmos directly. See Register Azure clients for an example of using dependency injection to create a client type from the Azure SDK.
Earlier versions of extensions in the isolated worker process only support binding to JSON serializable types. Additional options are available to extension 4.x and higher.
Exceptions and return codes host.json settingsThis section describes the configuration settings available for this binding in version 2.x and later. Settings in the host.json file apply to all functions in a function app instance. For more information about function app configuration settings, see host.json reference for Azure Functions.
{
"version": "2.0",
"extensions": {
"cosmosDB": {
"connectionMode": "Gateway",
"userAgentSuffix": "MyDesiredUserAgentStamp"
}
}
}
Gateway The connection mode used by the function when connecting to the Azure Cosmos DB service. Options are Direct and Gateway userAgentSuffix n/a Adds the specified string value to all requests made by the trigger or binding to the service. This makes it easier for you to track the activity in Azure Monitor, based on a specific function app and filtering by User Agent.
{
"version": "2.0",
"extensions": {
"cosmosDB": {
"connectionMode": "Gateway",
"protocol": "Https",
"leaseOptions": {
"leasePrefix": "prefix1"
}
}
}
}
Gateway The connection mode used by the function when connecting to the Azure Cosmos DB service. Options are Direct and Gateway protocol Https The connection protocol used by the function when connection to the Azure Cosmos DB service. Read here for an explanation of both modes. leasePrefix n/a Lease prefix to use across all functions in an app. Next steps
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4