Azure Cosmos DB Ausgabebindung für Azure Functions 2.x und höher

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Dekoratoren direkt in Ihrem Python Funktionscode definieren. Weitere Informationen finden Sie im Entwicklerhandbuch Python.

Das Python v1-Programmiermodell erfordert, dass Sie Bindungen in einer separaten function.jsondatei im Funktionsordner definieren. Weitere Informationen finden Sie im Entwicklerhandbuch Python.

Der folgende Code definiert einen MyDocument-Typ:

public class MyDocument
{
    public string? Id { get; set; }

    public string? Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Im folgenden Beispiel ist der Rückgabetyp IReadOnlyList<T>, eine geänderte Liste von Dokumenten aus dem Triggerbindungsparameter:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object? Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Dieser Abschnitt enthält folgende Beispiele:

• Warteschlangentrigger: Schreiben eines einzelnen Dokuments
• Warteschlangentrigger: Schreiben eines einzelnen Dokuments (v4-Erweiterung)
• Warteschlangentrigger: Schreiben von Dokumenten unter Verwendung von IAsyncCollector

Die Beispiele beziehen sich auf einen einfachen ToDoItem-Typ:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Warteschlangentrigger: Schreiben eines einzelnen Dokuments

Das folgende Beispiel zeigt eine C#-Funktion, die einer Datenbank ein Dokument hinzufügt und dazu die Daten aus der Meldung vom Warteschlangenspeicher verwendet.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Warteschlangentrigger: Schreiben eines einzelnen Dokuments (v4-Erweiterung)

Apps, die Azure Cosmos DB Erweiterung Version 4.x oder höher verwenden, weisen unterschiedliche Attributeigenschaften auf, die unten dargestellt werden. Das folgende Beispiel zeigt eine C#-Funktion, die einer Datenbank ein Dokument hinzufügt und dazu die Daten aus der Meldung vom Warteschlangenspeicher verwendet.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Warteschlangentrigger: Schreiben von Dokumenten unter Verwendung von „IAsyncCollector“

Das folgende Beispiel zeigt eine C#-Funktion, die einer Datenbank eine Sammlung von Dokumenten hinzufügt und dabei Daten aus dem JSON-Code einer Warteschlangennachricht verwendet.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

Das folgende Beispiel zeigt eine durch die Speicherwarteschlange ausgelöste TypeScript-Funktion für eine Warteschlange, die JSON im folgenden Format empfängt:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Die Funktion erstellt Azure Cosmos DB Dokumente im folgenden Format für jeden Datensatz:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Dies ist der TypeScript-Code:

import { app, InvocationContext, output } from '@azure/functions';

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Um mehrere Dokumente auszugeben, geben Sie anstelle eines einzelnen Objekts ein Array zurück. Beispiel:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

TypeScript-Beispiele sind für Modell v3 nicht dokumentiert.

Das folgende Beispiel zeigt eine durch die Speicherwarteschlange ausgelöste JavaScript-Funktion für eine Warteschlange, die JSON im folgenden Format empfängt:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Die Funktion erstellt Azure Cosmos DB Dokumente im folgenden Format für jeden Datensatz:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Der JavaScript-Code sieht wie folgt aus:

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

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Um mehrere Dokumente auszugeben, geben Sie anstelle eines einzelnen Objekts ein Array zurück. Beispiel:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Das folgende Beispiel zeigt eine Azure Cosmos DB Ausgabebindung in einer function.jsondatei und einer JavaScript-Funktion die die Bindung verwendet. Die Funktion verwendet eine Warteschlangeneingabebindung für eine Warteschlange, die JSON-Code im folgenden Format empfängt:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Die Funktion erstellt Azure Cosmos DB Dokumente im folgenden Format für jeden Datensatz:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Bindungsdaten in der Datei function.json:

{
    "name": "employeeDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Der JavaScript-Code sieht wie folgt aus:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Führen Sie zum Masseneinfügungsformular zuerst die Objekte aus, und führen Sie dann die Stringify-Funktion aus. Der JavaScript-Code sieht wie folgt aus:

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "id": "John Henry-123456",
            "name": "John Henry",
            "employeeId": "123456",
            "address": "A town nearby"
        },
        {
            "id": "John Doe-123457",
            "name": "John Doe",
            "employeeId": "123457",
            "address": "A town far away"
        }]);
    };

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

Die Bindungsdefinition ist in function.json definiert, wobei type auf cosmosDB festgelegt ist.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Um in die Datenbank zu schreiben, übergeben Sie ein Dokumentobjekt an die set-Methode des Parameters „database“.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die output.cosmosDB()-Methode übergeben wird. Die Eigenschaften type, direction und name gelten nicht für das Modell v4.

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die in der Datei function.json festgelegt werden, sowie über Eigenschaftsunterschiede nach Erweiterungsversion:

Eine Liste der unterstützten Typen finden Sie unter Bindungstypen.

Eine Liste der unterstützten Typen finden Sie unter Bindungstypen.

Wenn die Funktion in ein einzelnes Dokument schreiben soll, kann die Cosmos DB-Ausgabebindung an die folgenden Typen gebunden werden:

Wenn die Funktion in mehrere Dokumente schreiben soll, kann die Cosmos DB-Ausgabebindung an die folgenden Typen gebunden werden:

Erstellen und verwenden Sie für andere Ausgabeszenarien einen CosmosClient mit anderen Typen von Microsoft.Azure. Cosmos direkt. Ein Beispiel für die Verwendung der Abhängigkeitsinjektion zum Erstellen eines Clienttyps aus dem Azure SDK finden Sie unter Register Azure Clients.

Eine Liste der unterstützten Typen finden Sie unter Bindungstypen.