Connect Azure Functions to Azure Cosmos DB using Visual Studio Code

Before you begin, you must complete the quickstart: Create a C# function in Azure using Visual Studio Code. If you already cleaned up resources at the end of that article, go through the steps again to recreate the function app and related resources in Azure.

Before you begin, you must complete the quickstart: Create a JavaScript function in Azure using Visual Studio Code. If you already cleaned up resources at the end of that article, go through the steps again to recreate the function app and related resources in Azure.

Before you begin, you must complete the quickstart: Create a Python function in Azure using Visual Studio Code. If you already cleaned up resources at the end of that article, go through the steps again to recreate the function app and related resources in Azure.

Except for HTTP and timer triggers, bindings are implemented as extension packages. Run the following dotnet add package command in the Terminal window to add the Azure Cosmos DB extension package to your project.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

Your project has been configured to use extension bundles, which automatically installs a predefined set of extension packages.

Extension bundles usage is enabled in the host.json file at the root of the project, which appears as follows:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

Your project has been configured to use extension bundles, which automatically installs a predefined set of extension packages.

Extension bundles usage is enabled in the host.json file at the root of the project, which appears as follows:

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

In a C# class library project, the bindings are defined as binding attributes on the function method.

Open the HttpExample.cs project file and add the following classes:

    public class MultiResponse
    {
        [CosmosDBOutput("my-database", "my-container",
            Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
        public MyDocument Document { get; set; }
        public HttpResponseData HttpResponse { get; set; }
    }
    public class MyDocument {
        public string id { get; set; }
        public string message { get; set; }
    }

The MyDocument class defines an object that gets written to the database. The connection string for the Storage account is set by the Connection property. In this case, you could omit Connection because you're already using the default storage account.

The MultiResponse class allows you to both write to the specified collection in the Azure Cosmos DB and return an HTTP success message. Because you need to return a MultiResponse object, you need to also update the method signature.

Specific attributes specify the name of the container and the name of its parent database. The connection string for your Azure Cosmos DB account is set by the CosmosDbConnectionSetting.

Binding attributes are defined directly in your function code. The Azure Cosmos DB output configuration describes the fields required for an Azure Cosmos DB output binding.

For this MultiResponse scenario, you need to add an extraOutputs output binding to the function.

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

Add the following properties to the binding configuration:

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

Binding attributes are defined directly in the function_app.py file. You use the cosmos_db_output decorator to add an Azure Cosmos DB output binding:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

In this code, arg_name identifies the binding parameter referenced in your code, database_name and container_name are the database and collection names that the binding writes to, and connection is the name of an application setting that contains the connection string for the Azure Cosmos DB account, which is in the CosmosDbConnectionSetting setting in the local.settings.json file.

Replace the existing Run method with the following code:

        [Function("HttpExample")]
        public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
            FunctionContext executionContext)
        {
            var logger = executionContext.GetLogger("HttpExample");
            logger.LogInformation("C# HTTP trigger function processed a request.");

            var message = "Welcome to Azure Functions!";

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
            response.WriteString(message);

            // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
            return new MultiResponse()
            {
                 Document = new MyDocument
                {
                    id = System.Guid.NewGuid().ToString(),
                    message = message
                },
                HttpResponse = response
            };
        }

Add code that uses the extraInputs output binding object on context to send a JSON document to the named output binding function, sendToCosmosDb. Add this code before the return statement.

      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

At this point, your function should look as follows:

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

This code now returns a MultiResponse object that contains both a document and an HTTP response.

Update HttpExample\function_app.py to match the following code. Add the outputDocument parameter to the function definition and outputDocument.set() under the if name: statement:

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

The document {"id": "name"} is created in the database collection specified in the binding.

Run the function locally

Visual Studio Code integrates with Azure Functions Core tools to let you run this project on your local development computer before you publish to Azure.

1. To call your function, press F5 to start the function app project. The Terminal panel displays the output from Core Tools. Your app starts in the Terminal panel. You can see the URL endpoint of your HTTP-triggered function running locally.

   

   If you have trouble running on Windows, make sure that the default terminal for Visual Studio Code isn't set to WSL Bash.

2. With the Core Tools running, go to the Azure: Functions area. Under Functions, expand Local Project > Functions. Right-click (Windows) or Ctrl - click (macOS) the HttpExample function and choose Execute Function Now....

   

3. In the Enter request body, press Enter to send a request message to your function.

4. When the function executes locally and returns a response, a notification is raised in Visual Studio Code. Information about the function execution is shown in the Terminal panel.

5. Press Ctrl + C to stop Core Tools and disconnect the debugger.

Run the function locally

1. As in the previous article, press F5 to start the function app project and Core Tools.

2. With Core Tools running, go to the Azure: Functions area. Under Functions, expand Local Project > Functions. Right-click (Ctrl-click on Mac) the HttpExample function and choose Execute Function Now....

   

3. In Enter request body you see the request message body value of { "name": "Azure" }. Press Enter to send this request message to your function.

4. After a response is returned, press Ctrl + C to stop Core Tools.

• Examples of complete Function projects in C#.

• Azure Functions C# developer reference

• Examples of complete Function projects in JavaScript.

• Azure Functions JavaScript developer guide

• Examples of complete Function projects in Python.

• Azure Functions Python developer guide