Freigeben über

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

  • Artikel

Die Azure Cosmos DB-Ausgabebindung ermöglicht das Schreiben eines neuen Dokuments in eine Azure Cosmos DB-Datenbank mithilfe der SQL-API.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

  • Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden. Erweiterungen für isolierte Workerprozessfunktionen verwenden Microsoft.Azure.Functions.Worker.Extensions.*-Namespaces.
  • In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird. In einer Variante dieses Modells kann Functions mithilfe von C#-Skripts ausgeführt werden. Dies wird hauptsächlich für die Bearbeitung im C#-Portal unterstützt. Erweiterungen für In-Process-Funktionen verwenden Microsoft.Azure.WebJobs.Extensions.*-Namespaces.

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Beispiel

Sofern nicht anders angegeben, beziehen sich die Beispiele in diesem Artikel auf Version 3.x der Azure Cosmos DB-Erweiterung. Für die Verwendung mit Erweiterung Version 4.x müssen Sie die Zeichenfolge collection in Eigenschafts- und Attributnamen durch container und connection_string_setting durch ersetzen connection.

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>
    }

Warteschlangentrigger: Speichern einer Nachricht in einer Datenbank über den Rückgabewert

Das folgende Beispiel zeigt eine Java-Funktion, die einer Datenbank ein Dokument hinzufügt und dazu die Daten aus der Meldung in Queue Storage verwendet.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

HTTP-Trigger: Speichern eines Dokuments in einer Datenbank über den Rückgabewert

Das folgende Beispiel zeigt eine Java-Funktion, deren Signatur mit @CosmosDBOutput kommentiert ist und einen Rückgabewert des Typs String besitzt. Das von der Funktion zurückgegebene JSON-Dokument wird automatisch in die entsprechende Azure Cosmos DB-Sammlung geschrieben.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

HTTP-Trigger: Speichern eines Dokuments in einer Datenbank über OutputBinding

Das folgende Beispiel zeigt eine Java-Funktion, die ein Dokument über einen OutputBinding<T>-Ausgabeparameter in Azure Cosmos DB schreibt. Beachten Sie, dass es in diesem Beispiel der Parameter outputItem ist, der mit @CosmosDBOutput kommentiert sein muss, nicht die Funktionssignatur. Durch die Verwendung von OutputBinding<T> kann Ihre Funktion die Bindung nutzen, um das Dokument in Azure Cosmos DB zu schreiben, und gleichzeitig einen anderen Wert an den Funktionsaufrufer zurückgeben, z. B. ein JSON- oder XML-Dokument.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

HTTP-Trigger: Speichern mehrerer Dokumente in einer Datenbank über OutputBinding

Das folgende Beispiel zeigt eine Java-Funktion, die mehrere Dokumente über einen OutputBinding<T>-Ausgabeparameter in Azure Cosmos DB schreibt. Beachten Sie, dass in diesem Beispiel der Parameter outputItem mit @CosmosDBOutput kommentiert sein muss, nicht die Funktionssignatur. Der Ausgabeparameter outputItem enthält eine Liste von ToDoItem-Objekten als deren Vorlagenparametertyp. Durch die Verwendung von OutputBinding<T> kann Ihre Funktion die Bindung nutzen, um die Dokumente in Azure Cosmos DB zu schreiben, und gleichzeitig einen anderen Wert an den Funktionsaufrufer zurückgeben, z. B. ein JSON- oder XML-Dokument.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Verwenden Sie die @CosmosDBOutput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, die in Azure Cosmos DB geschrieben werden. Der Parametertyp der Anmerkung sollte OutputBinding<T> sein, wobei T ein nativer Java-Typ oder ein POJO ist.

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 die einzelnen Datensätze:

{
    "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',
    },
];

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 die einzelnen Datensätze:

{
    "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',
    },
];

Im folgenden Beispiel wird gezeigt, wie Daten mithilfe einer Ausgabebindung in Azure Cosmos DB geschrieben werden. Die Bindung wird in der Konfigurationsdatei der Funktion (functions.json) deklariert. Daten werden aus einer Warteschlangennachricht abgerufen, und die Ausgabe erfolgt in einem Azure Cosmos DB-Dokument.

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

In der Datei run.ps1 wird das von der Funktion zurückgegebene Objekt einem EmployeeDocument-Objekt zugeordnet, das in der Datenbank persistent gespeichert wird.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

Im folgenden Beispiel wird veranschaulicht, wie ein Dokument als Ausgabe einer Funktion in eine Azure Cosmos DB-Datenbank geschrieben wird. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

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'

Attribute

Sowohl C#-Bibliotheken des Typs In-Process als auch des Typs Isolierter Workerprozess verwenden Attribute zum Definieren der Funktion. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Attributeigenschaft BESCHREIBUNG
Connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem zu überwachenden Azure Cosmos DB-Konto hergestellt werden soll. Weitere Informationen finden Sie unter Verbindungen.
DatabaseName Der Name der Azure Cosmos DB-Datenbank mit dem überwachten Container.
ContainerName Der Name des überwachten Containers.
CreateIfNotExists Ein boolescher Wert, der angibt, ob der Container erstellt wird, wenn er nicht vorhanden ist. Der Standardwert ist FALSE, da neue Container mit reserviertem Durchsatz erstellt werden. Dies wirkt sich auf die Kosten aus. Weitere Informationen hierzu finden Sie in der Preisübersicht.
PartitionKey Wenn CreateIfNotExists den Wert „TRUE“ hat, wird der Partitionsschlüsselpfad für den erstellten Container definiert. Kann den Bindungsparameter enthalten.
ContainerThroughput Wenn CreateIfNotExists den Wert „TRUE“ hat, wird der Durchsatz für den erstellten Container definiert.
PreferredLocations (Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: East US,South Central US,North Europe.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Decorators definiert wurden, gelten die folgenden Eigenschaften für cosmos_db_output:

Eigenschaft BESCHREIBUNG
arg_name Der im Code der Funktion verwendete Variablenname, der die Liste der Dokumente mit Änderungen darstellt.
database_name Der Name der Azure Cosmos DB-Datenbank mit der überwachten Sammlung.
collection_name Der Name der Azure Cosmos DB-Sammlung, die überwacht wird.
create_if_not_exists Ein boolescher Wert, der angibt, ob die Datenbank und Sammlung erstellt werden sollen, wenn sie nicht vorhanden sind.
connection_string_setting Die Verbindungszeichenfolge der zu überwachenden Azure Cosmos DB.

Informationen zu Python-Funktionen, die mithilfe von function.json definiert wurden, finden Sie im Abschnitt Konfiguration.

Anmerkungen

Verwenden Sie die @CosmosDBOutput-Anmerkung aus der Runtimebibliothek für Java-Funktionen für Parameter, die in Azure Cosmos DB schreiben. Für die Anmerkung werden folgende Eigenschaften unterstützt:

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

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:

Eigenschaft von „function.json“ BESCHREIBUNG
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem zu überwachenden Azure Cosmos DB-Konto hergestellt werden soll. Weitere Informationen finden Sie unter Verbindungen.
databaseName Der Name der Azure Cosmos DB-Datenbank mit dem überwachten Container.
containerName Der Name des überwachten Containers.
createIfNotExists Ein boolescher Wert, der angibt, ob der Container erstellt wird, wenn er nicht vorhanden ist. Der Standardwert ist FALSE, da neue Container mit reserviertem Durchsatz erstellt werden. Dies wirkt sich auf die Kosten aus. Weitere Informationen hierzu finden Sie in der Preisübersicht.
partitionKey Wenn createIfNotExists den Wert „TRUE“ hat, wird der Partitionsschlüsselpfad für den erstellten Container definiert. Kann den Bindungsparameter enthalten.
containerThroughput Wenn createIfNotExists den Wert „TRUE“ hat, wird der Durchsatz für den erstellten Container definiert.
preferredLocations (Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: East US,South Central US,North Europe.

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verwendung

Standardmäßig wird beim Schreiben in den Ausgabeparameter in Ihrer Funktion ein Dokument in der Datenbank erstellt. Sie sollten die Dokument-ID des Ausgabedokuments angeben, indem Sie die id-Eigenschaft im JSON-Objekt angeben, das an den Ausgabeparameter übergeben wird.

Hinweis

Wenn Sie die ID eines vorhandenen Dokuments angeben, wird dieses vom neuen Ausgabedokument überschrieben.

Der von der Cosmos DB-Ausgabebindung unterstützte Parametertyp hängt von der Version der Functions-Runtime, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

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

type BESCHREIBUNG
Serialisierbare JSON-Typen Ein Objekt, das den JSON-Inhalt eines Dokuments darstellt. Functions versucht, einen POCO-Typ (Plain-Old CLR Object) in JSON-Daten zu serialisieren.

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

type BESCHREIBUNG
T[], wobei T ein serialisierbarer JSON-Typ ist Ein Array, das mehrere Dokumente enthält. Jeder Eintrag stellt eine Entität dar.

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 Registrieren von Azure-Clients .

Verbindungen

Die Eigenschaften connectionStringSetting/connection und leaseConnectionStringSetting/leaseConnection sind Verweise auf eine Umgebungskonfiguration, die angibt, wie sich die App mit Azure Cosmos DB verbinden soll. Damit kann Folgendes festgelegt werden:

  • Der Name einer Anwendungseinstellung, die eine Verbindungszeichenfolge enthält
  • Der Name eines gemeinsam genutzten Präfixes für mehrere Anwendungseinstellungen, die zusammen eine identitätsbasierte Verbindung definieren. Diese Option ist nur für die connection- und leaseConnection-Versionen ab connection verfügbar.

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Die Verbindungszeichenfolge für Ihr Datenbankkonto sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der dem in der Verbindungseigenschaft der Bindungskonfiguration angegebenen Wert entspricht.

Identitätsbasierte Verbindungen

Wenn Sie Version 4.x oder eine höhere Version der Erweiterung verwenden, kann die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Microsoft Entra-Identität verwenden. Dazu definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Verbindungseigenschaft in der Trigger- und Bindungskonfiguration zugeordnet ist.

In diesem Modus benötigt die Erweiterung die folgenden Eigenschaften:

Eigenschaft Vorlage für Umgebungsvariable BESCHREIBUNG Beispielwert
Kontoendpunkt <CONNECTION_NAME_PREFIX>__accountEndpoint Der URI des Azure Cosmos DB-Kontoendpunkts. https://<Name_des_Datenbankkontos>.documents.azure.com:443/

Zusätzliche Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

Wichtig

Vom Zieldienst werden möglicherweise einige nicht für alle Kontexte erforderliche Berechtigungen verfügbar gemacht. Befolgen Sie nach Möglichkeit das Prinzip der geringsten Berechtigung, und gewähren Sie der Identität nur die erforderlichen Berechtigungen. Wenn die App beispielsweise nur Daten aus einer Datenquelle lesen muss, verwenden Sie eine Rolle, die nur über Leseberechtigungen verfügt. Es wäre nicht angemessen, eine Rolle zu zuweisen, die auch das Schreiben in diesen Dienst zulässt, da dies eine übermäßige Berechtigung für einen Lesevorgang wäre. Ebenso sollten Sie sicherstellen, dass die Rollenzuweisung auf die Ressourcen begrenzt ist, die gelesen werden müssen.

Azure RBAC wird von Cosmos DB nicht für Datenvorgänge verwendet. Stattdessen wird ein in Cosmos DB integriertes RBAC-System verwendet, das auf ähnlichen Konzepten basiert. Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihr Datenbankkonto ermöglicht. Azure RBAC-Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für den normalen Betrieb mit der Azure Cosmos DB-Erweiterung empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp Beispiele für integrierte Rollen1
Trigger2 Integrierter Mitwirkender an Cosmos DB-Daten
Eingabebindung Integrierter Cosmos DB-Datenleser
Ausgabebindung Integrierter Mitwirkender an Cosmos DB-Daten

1 Diese Rollen können nicht in einer Azure RBAC-Rollenzuweisung verwendet werden. Ausführliche Informationen zum Zuweisen dieser Rollen finden Sie in der Dokumentation zum in Cosmos DB integrierten RBAC-System.

2 Bei Verwendung von Identitäten behandelt Cosmos DB die Containererstellung als Verwaltungsvorgang. Es ist nicht als Datenebenenvorgang für den Trigger verfügbar. Sie müssen sicherstellen, dass Sie die vom Trigger benötigten Container (einschließlich des Leasecontainers) erstellen, bevor Sie Ihre Funktion einrichten.

Ausnahmen und Rückgabecodes

Bindung Verweis
Azure Cosmos DB HTTP-Statuscodes für Azure Cosmos DB

Nächste Schritte