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

Die Azure Cosmos DB-Eingabebindung verwendet die SQL-API, um mindestens ein Azure Cosmos DB-Dokument abzurufen und an den Eingabeparameter der Funktion zu übergeben. Die Dokument-ID oder die Abfrageparameter können basierend auf dem Trigger, der die Funktion aufruft, ermittelt werden.

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

Hinweis

Wenn die Sammlung partitioniert ist, müssen Suchvorgänge auch den Partitionsschlüsselwert angeben.

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.

v2

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.

v1

Für das Python v1-Programmiermodell müssen Sie Bindungen in einer separaten function.json-Datei im Funktionsordner definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

Sofern nicht anders angegeben, beziehen sich die Beispiele in diesem Artikel auf Version 3.x der Azure Cosmos DB-Erweiterung. Zum Verwenden mit der Erweiterungsversion 4.x müssen Sie die Zeichenfolge collection in Eigenschaften- und Attributnamen durch container ersetzen.

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.

Isoliertes Workermodell

Dieser Abschnitt enthält Beispiele, die Version 3.x der Azure Cosmos DB-Erweiterung und 5.x der Azure Storage-Erweiterung erfordern. Falls nicht bereits in Ihrer Funktions-App vorhanden, fügen Sie einen Verweis auf die folgenden NuGet-Pakete hinzu:

• Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

• Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

• Warteschlangentrigger: Suchen der ID in JSON-Code

Die Beispiele beziehen sich auf einen einfachen ToDoItem-Typ:

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

Warteschlangentrigger: Suchen der ID in JSON-Code

Das folgende Beispiel zeigt eine Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine JSON-Nachricht in der Speicherwarteschlange ausgelöst. Der Warteschlangentrigger zerlegt den JSON-Code in ein Objekt vom Typ ToDoItemLookup, das die ID und den Partitionsschlüsselwert enthält, der abgerufen werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung zurückgegeben.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

In-Process-Modell

Dieser Abschnitt enthält die folgenden Beispiele für die Verwendung von In-Process-C#-Klassenbibliotheksfunktionen mit Erweiterungsversion 3.x:

• Warteschlangentrigger: Suchen der ID in JSON-Code
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge
• HTTP-Trigger: Suchen der ID in Routendaten
• HTTP-Trigger: Suchen der ID in Routendaten unter Verwendung von „SqlQuery“
• HTTP-Trigger: Abrufen mehrerer Dokumente unter Verwendung von „SqlQuery“
• HTTP-Trigger: Abrufen mehrerer Dokumente unter Verwendung von „DocumentClient“
• HTTP-Trigger: Abrufen mehrerer Dokumente mit CosmosClient (v4-Erweiterung)

Die Beispiele beziehen sich auf einen einfachen ToDoItem-Typ:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        [JsonProperty("id")]
        public string Id { get; set; }

        [JsonProperty("partitionKey")]
        public string PartitionKey { get; set; }

        public string Description { get; set; }
    }
}

Warteschlangentrigger: Suchen der ID in JSON-Code

Das folgende Beispiel zeigt eine C#-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine Warteschlangennachricht ausgelöst, die ein JSON-Objekt enthält. Der Warteschlangentrigger zerlegt den JSON-Code in ein Objekt vom Typ ToDoItemLookup, das die ID und den Partitionsschlüsselwert enthält, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

namespace CosmosDBSamplesV2
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }

        public string ToDoItemPartitionKeyValue { get; set; }
    }
}

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

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}",
                PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

            if (toDoItem == null)
            {
                log.LogInformation($"ToDo item not found");
            }
            else
            {
                log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }
}

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge

Das folgende Beispiel zeigt eine C#-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

Hinweis

Beim Wert für den HTTP-Abfragezeichenfolge-Parameter muss die Groß-/Kleinschreibung beachtet werden.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}",
                PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.LogInformation($"ToDo item not found");
            }
            else
            {
                log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
            }
            return new OkResult();
        }
    }
}

HTTP-Trigger: Suchen der ID in Routendaten

Das folgende Beispiel zeigt eine C#-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die Routendaten verwendet, um die ID und den Schlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}",
                PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.LogInformation($"ToDo item not found");
            }
            else
            {
                log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
            }
            return new OkResult();
        }
    }
}

HTTP-Trigger: Suchen der ID in Routendaten unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine C#-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Routendaten verwendet, um die zu suchende ID anzugeben. Anhand dieser ID wird ein Dokument vom Typ ToDoItem aus der angegebenen Datenbank und Sammlung abgerufen.

Das Beispiel veranschaulicht die Verwendung eines Bindungsausdrucks im Parameter SqlQuery. Sie können Routendaten wie gezeigt an den Parameter SqlQuery übergeben. Die Übergabe von Abfragezeichenfolgenwerten ist derzeit allerdings nicht möglich.

Hinweis

Wenn Sie nur über die ID eine Abfrage ausführen, sollten Sie wie in den vorherigen Beispielen einen Suchvorgang verwenden, da dadurch weniger Anforderungseinheiten verbraucht werden. Punktlesevorgänge (GET) sind effizienter als Abfragen über die ID.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequest req,
            [CosmosDB("ToDoItems", "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

HTTP-Trigger: Abrufen mehrerer Dokumente unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine C#-Funktion, die eine Liste von Dokumenten abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst. Die Abfrage wird in der Attributeigenschaft SqlQuery angegeben.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

HTTP-Trigger: Abrufen mehrerer Dokumente unter Verwendung von DocumentClient

Das folgende Beispiel zeigt eine C#-Funktion, die eine Liste von Dokumenten abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst. Der Code verwendet eine von der Azure Cosmos DB-Bindung bereitgestellte DocumentClient-Instanz, um eine Liste von Dokumenten zu lesen. Die DocumentClient-Instanz kann auch für Schreibvorgänge verwendet werden.

Hinweis

Sie können auch die IDocumentClient-Schnittstelle verwenden, um das Testen zu vereinfachen.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"];
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");

            log.LogInformation($"Searching for: {searchterm}");

            IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
                .Where(p => p.Description.Contains(searchterm))
                .AsDocumentQuery();

            while (query.HasMoreResults)
            {
                foreach (ToDoItem result in await query.ExecuteNextAsync())
                {
                    log.LogInformation(result.Description);
                }
            }
            return new OkResult();
        }
    }
}

HTTP-Trigger: Abrufen mehrerer Dokumente unter Verwendung von CosmosClient

Das folgende Beispiel zeigt eine C#-Funktion, die eine Liste von Dokumenten abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst. Der Code verwendet eine CosmosClient-Instanz, die von der Azure Cosmos DB-Bindung bereitgestellt wird, die in der Erweiterungsversion 4.x verfügbar ist, um eine Liste von Dokumenten zu lesen. Die CosmosClient-Instanz kann auch für Schreibvorgänge verwendet werden.

using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingCosmosClient
    {  
        [FunctionName("DocsByUsingCosmosClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")] CosmosClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"].ToString();
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Container container = client.GetDatabase("ToDoItems").GetContainer("Items");

            log.LogInformation($"Searching for: {searchterm}");

            QueryDefinition queryDefinition = new QueryDefinition(
                "SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
                .WithParameter("@searchterm", searchterm);
            using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
            {
                while (resultSet.HasMoreResults)
                {
                    FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
                    ToDoItem item = response.First();
                    log.LogInformation(item.Description);
                }
            }

            return new OkResult();
        }
    }
}

Dieser Abschnitt enthält folgende Beispiele:

• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge – Zeichenfolgenparameter
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge – POJO-Parameter
• HTTP-Trigger: Suchen der ID in Routendaten
• HTTP-Trigger: Suchen der ID in Routendaten unter Verwendung von „SqlQuery“
• HTTP-Trigger: Abrufen mehrerer Dokumente aus Routendaten unter Verwendung von SqlQuery

Die Beispiele beziehen sich auf einen einfachen ToDoItem-Typ:

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge – Zeichenfolgenparameter

Das folgende Beispiel zeigt eine Java-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein Dokument im Zeichenfolgenformat aus der angegebenen Datenbank und Sammlung abgerufen.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Verwenden Sie die @CosmosDBInput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Funktionsparameter, deren Wert von Azure Cosmos DB empfangen wird. Diese Anmerkung kann mit nativen Java-Typen, POJOs oder Werten mit Optional<T>, die NULL-Werte annehmen können, verwendet werden.

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge – POJO-Parameter

Das folgende Beispiel zeigt eine Java-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein Dokument aus der angegebenen Datenbank und Sammlung abgerufen. Das Dokument wird dann in eine Instanz des zuvor erstellten ToDoItem POJO konvertiert und als Argument an die Funktion übergeben.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP-Trigger: Suchen der ID in Routendaten

Das folgende Beispiel zeigt eine Java-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die einen Routenparameter verwendet, um die ID und den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein Dokument aus der angegebenen Datenbank und Sammlung abgerufen und als Optional<String> zurückgegeben.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

HTTP-Trigger: Suchen der ID in Routendaten unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine Java-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die einen Routenparameter verwendet, um die zu suchende ID anzugeben. Diese ID wird verwendet, um ein Dokument aus der angegebenen Datenbank und Sammlung abzurufen, wobei das Resultset in ein ToDoItem[] konvertiert wird, da viele Dokumente zurückgegeben werden können, je nach den Abfragekriterien.

Hinweis

Wenn Sie nur über die ID eine Abfrage ausführen, sollten Sie wie in den vorherigen Beispielen einen Suchvorgang verwenden, da dadurch weniger Anforderungseinheiten verbraucht werden. Punktlesevorgänge (GET) sind effizienter als Abfragen über die ID.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP-Trigger: Abrufen mehrerer Dokumente aus Routendaten unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine Java-Funktion, die mehrere Dokumente abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die den Routenparameter desc verwendet, um die in dem Feld description zu suchende Zeichenfolge anzugeben. Der Suchbegriff wird verwendet, um ein Sammlung von Dokumenten aus der angegebenen Datenbank und Sammlung abzurufen, wobei das Resultset in ein ToDoItem[] konvertiert und dieses als Argument an die Funktion übergeben wird.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

Dieser Abschnitt enthält die folgenden Beispiele, die ein einzelnes Dokument lesen, indem ein ID-Wert aus verschiedenen Quellen angegeben wird:

• Warteschlangentrigger: Suchen der ID in JSON-Code
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge
• HTTP-Trigger: Suchen der ID in Routendaten
• Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von „SqlQuery“

Warteschlangentrigger: Suchen der ID in JSON-Code

Das folgende Beispiel zeigt eine TypeScript-Funktion, die ein einzelnes Dokument liest und den Textwert des Dokuments aktualisiert.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

Modell v3

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

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge

Das folgende Beispiel zeigt eine TypeScript-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

Modell v4

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Modell v3

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

HTTP-Trigger: Suchen der ID in Routendaten

Das folgende Beispiel zeigt eine TypeScript-Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die Routendaten verwendet, um die ID und den Schlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

Modell v4

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Modell v3

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

Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine TypeScript-Funktion, die mehrere von einer SQL-Abfrage angegebene Dokumente mithilfe eines Warteschlangentriggers abruft, um die Abfrageparameter anzupassen.

Der Warteschlangentrigger stellt den Parameter departmentId bereit. Die Warteschlangennachricht { "departmentId" : "Finance" } gibt dann alle Datensätze für die Finanzabteilung zurück.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

Modell v3

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

Dieser Abschnitt enthält die folgenden Beispiele, die ein einzelnes Dokument lesen, indem ein ID-Wert aus verschiedenen Quellen angegeben wird:

• Warteschlangentrigger: Suchen der ID in JSON-Code
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge
• HTTP-Trigger: Suchen der ID in Routendaten
• Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von „SqlQuery“

Warteschlangentrigger: Suchen der ID in JSON-Code

Das folgende Beispiel zeigt eine JavaScript-Funktion, die ein einzelnes Dokument liest und den Textwert des Dokuments aktualisiert.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

Modell v3

Bindungsdaten in der Datei function.json:

{
    "name": "inputDocumentIn",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Der JavaScript-Code sieht wie folgt aus:

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge

Das folgende Beispiel zeigt eine JavaScript-Skriptfunktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Modell v3

Die Datei function.json sieht wie folgt aus:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "disabled": false
}

Der JavaScript-Code sieht wie folgt aus:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

HTTP-Trigger: Suchen der ID in Routendaten

Das folgende Beispiel zeigt eine JavaScript-Skriptfunktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die Routendaten verwendet, um die ID und den Schlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Modell v3

Die Datei function.json sieht wie folgt aus:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "disabled": false
}

Der JavaScript-Code sieht wie folgt aus:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine JavaScript-Funktion, die mehrere von einer SQL-Abfrage angegebene Dokumente mithilfe eines Warteschlangentriggers abruft, um die Abfrageparameter anzupassen.

Der Warteschlangentrigger stellt den Parameter departmentId bereit. Die Warteschlangennachricht { "departmentId" : "Finance" } gibt dann alle Datensätze für die Finanzabteilung zurück.

Modell v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

Modell v3

Bindungsdaten in der Datei function.json:

{
    "name": "documents",
    "type": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "CosmosDBConnection"
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Der JavaScript-Code sieht wie folgt aus:

module.exports = async function (context, input) {
  var documents = context.bindings.documents;
  for (const document of documents) {
    // operate on each document
  }
};

• Warteschlangentrigger: Suchen der ID in JSON-Code
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge
• HTTP-Trigger: Suchen der ID in Routendaten
• Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von „SqlQuery“

Warteschlangentrigger: Suchen der ID in JSON-Code

Im folgenden Beispiel wird veranschaulicht, wie Sie ein einzelnes Azure Cosmos DB-Dokument lesen und aktualisieren. Der eindeutige Bezeichner des Dokuments wird über einen JSON-Wert in einer Warteschlangennachricht bereitgestellt.

Die Azure Cosmos DB-Eingabebindung ist in der Liste mit den Bindungen aus der Konfigurationsdatei der Funktion (function.json) an erster Stelle aufgeführt.

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

Die Datei run.ps1 enthält den PowerShell-Code, mit dem die eingehenden Dokument- und Ausgabenänderungen gelesen werden.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document  

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge

Im folgenden Beispiel wird veranschaulicht, wie Sie ein einzelnes Azure Cosmos DB-Dokument über eine Web-API lesen und aktualisieren. Der eindeutige Bezeichner des Dokuments wird über einen querystring-Parameter aus der HTTP-Anforderung angegeben. Dies ist in der "Id": "{Query.Id}"-Eigenschaft der Bindung definiert.

Die Azure Cosmos DB-Eingabebindung ist in der Liste mit den Bindungen aus der Konfigurationsdatei der Funktion (function.json) an erster Stelle aufgeführt.

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
} 

Die Datei run.ps1 enthält den PowerShell-Code, mit dem die eingehenden Dokument- und Ausgabenänderungen gelesen werden.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

HTTP-Trigger: Suchen der ID in Routendaten

Im folgenden Beispiel wird veranschaulicht, wie Sie ein einzelnes Azure Cosmos DB-Dokument über eine Web-API lesen und aktualisieren. Der eindeutige Bezeichner des Dokuments wird über einen Routenparameter bereitgestellt. Der Routenparameter wird in der route-Eigenschaft der HTTP-Anforderungsbindung definiert, und in der Azure Cosmos DB-Bindungseigenschaft "Id": "{Id}" wird darauf verwiesen.

Die Azure Cosmos DB-Eingabebindung ist in der Liste mit den Bindungen aus der Konfigurationsdatei der Funktion (function.json) an erster Stelle aufgeführt.

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
} 

Die Datei run.ps1 enthält den PowerShell-Code, mit dem die eingehenden Dokument- und Ausgabenänderungen gelesen werden.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
} 

Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von SqlQuery

Im folgenden Beispiel wird veranschaulicht, wie Sie mehrere Azure Cosmos DB-Dokumente lesen. In der Konfigurationsdatei der Funktion (function.json) werden die Bindungseigenschaften definiert, in denen auch sqlQuery enthalten ist. Mit der für die sqlQuery-Eigenschaft angegebenen SQL-Anweisung wird die Gruppe von Dokumenten ausgewählt, die für die Funktion bereitgestellt werden.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
} 

Die Datei run1.ps1 enthält den PowerShell-Code, mit dem die eingehenden Dokumente gelesen werden.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
} 

Dieser Abschnitt enthält die folgenden Beispiele, die ein einzelnes Dokument lesen, indem ein ID-Wert aus verschiedenen Quellen angegeben wird:

• Warteschlangentrigger: Suchen der ID in JSON-Code
• HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge
• HTTP-Trigger: Suchen der ID in Routendaten
• Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von „SqlQuery“

Die Beispiele hängen davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

Warteschlangentrigger: Suchen der ID in JSON-Code

Das folgende Beispiel zeigt eine Azure Cosmos DB-Eingabebindung. Die Funktion liest ein einzelnes Dokument und aktualisiert den Textwert des Dokuments.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

v1

Bindungsdaten in der Datei function.json:

{
    "name": "documents",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "$return",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Dies ist der Python-Code:

import azure.functions as func

def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Document:
    if documents:
        document = documents[0]
        document['text'] = 'This was updated!'
        return document

HTTP-Trigger: Suchen der ID in einer Abfragezeichenfolge

Das folgende Beispiel zeigt eine Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die eine Abfragezeichenfolge verwendet, um die ID oder den Partitionsschlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

v2

Derzeit kein gleichwertiges Beispiel für v2.

v1

Die Datei function.json sieht wie folgt aus:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "scriptFile": "__init__.py"
}

Dies ist der Python-Code:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])

    return 'OK'

HTTP-Trigger: Suchen der ID in Routendaten

Das folgende Beispiel zeigt eine Funktion, die ein einzelnes Dokument abruft. Die Funktion wird durch eine HTTP-Anforderung ausgelöst, die Routendaten verwendet, um die ID und den Schlüsselwert anzugeben, der gesucht werden soll. Anhand dieser ID und dieses Partitionsschlüsselwerts wird ein ToDoItem-Dokument aus der angegebenen Datenbank und Sammlung abgerufen.

v2

Derzeit kein gleichwertiges Beispiel für v2.

v1

Die Datei function.json sieht wie folgt aus:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

Dies ist der Python-Code:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])
    return 'OK'

Warteschlangentrigger: Abrufen mehrerer Dokumente unter Verwendung von SqlQuery

Das folgende Beispiel zeigt eine Azure Cosmos DB-Eingabebindung und eine Python-Funktion, die die Bindung verwendet. Die Funktion ruft mehrere von einer SQL-Abfrage angegebene Dokumente mithilfe eines Warteschlangentriggers ab, um die Abfrageparameter anzupassen.

Der Warteschlangentrigger stellt den Parameter departmentId bereit. Die Warteschlangennachricht { "departmentId" : "Finance" } gibt dann alle Datensätze für die Finanzabteilung zurück.

v2

Derzeit kein gleichwertiges Beispiel für v2.

v1

Bindungsdaten in der Datei function.json:

{
    "name": "documents",
    "type": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "CosmosDBConnection"
}

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.

Erweiterung 4.x oder höher

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.
PartitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Containern ist dies erforderlich.
Id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
SqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
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.

Functions 2.x oder höher

Attributeigenschaft	BESCHREIBUNG
ConnectionStringSetting	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 der überwachten Sammlung.
CollectionName	Der Name der überwachten Sammlung.
PartitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Sammlungen ist dies erforderlich.
Id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
SqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
PreferredLocations	(Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: „USA, Osten,USA, Süden-Mitte,Europa, Norden“.

Erweiterung 4.x oder höher

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.
PartitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Containern ist dies erforderlich.
Id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
SqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
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.

Functions 2.x oder höher

Attributeigenschaft	BESCHREIBUNG
ConnectionStringSetting	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 der überwachten Sammlung.
CollectionName	Der Name der überwachten Sammlung.
PartitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Sammlungen ist dies erforderlich.
Id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
SqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften Id und SqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
PreferredLocations	(Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: „USA, Osten,USA, Süden-Mitte,Europa, Norden“.

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

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.
connection_string_setting	Die Verbindungszeichenfolge der Azure Cosmos DB, die überwacht wird.
partition_key	Der Partitionsschlüssel der Azure Cosmos DB, die überwacht wird.
id	Die ID des abzurufenden Dokuments.

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

Anmerkungen

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

• name
• connectionStringSetting
• databaseName
• collectionName
• dataType
• id
• partitionKey
• sqlQuery

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

Modell v4

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

Modell v3

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

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

Erweiterung 4.x oder höher

Eigenschaft von „function.json“	BESCHREIBUNG
type	Muss auf cosmosDB festgelegt sein.
direction	Muss auf in festgelegt sein.
name	Der im Code der Funktion verwendete Variablenname, der die Liste der Dokumente mit Änderungen darstellt.
connection	Der Name einer App-Einstellung oder eines Einstellungscontainers, die bzw. der 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.
partitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Containern ist dies erforderlich.
id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften id und sqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
sqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften id und sqlQuery fest. Wenn Sie keine der beiden Eigenschaften festlegen, wird der gesamte Container abgerufen.
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.

Functions 2.x oder höher

Eigenschaft von „function.json“	BESCHREIBUNG
type	Muss auf cosmosDBTrigger festgelegt sein.
direction	Muss auf in festgelegt sein.
name	Der im Code der Funktion verwendete Variablenname, der die Liste der Dokumente mit Änderungen darstellt.
connectionStringSetting	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 der überwachten Sammlung.
collectionName	Der Name der überwachten Sammlung.
partitionKey	Gibt den Wert des Partitionsschlüssels für die Suche an. Kann den Bindungsparameter enthalten. Für Suchvorgänge in partitionierten Sammlungen ist dies erforderlich.
id	Die ID des abzurufenden Dokuments. Diese Eigenschaft unterstützt Bindungsausdrücke. Legen Sie nicht die beiden Eigenschaften id und sqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
sqlQuery	Eine SQL-Abfrage in Azure Cosmos DB zum Abrufen mehrerer Dokumente. Die Eigenschaft unterstützt Laufzeitbindungen, wie in diesem Beispiel: SELECT * FROM c where c.departmentId = {departmentId}. Legen Sie nicht die beiden Eigenschaften id und sqlQuery fest. Wenn Sie keine der beiden festlegen, wird die gesamte Sammlung abgerufen.
preferredLocations	(Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispielsweise East US,South Central US,North Europe.

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verwendung

Erweiterung 4.x oder höher

Wenn die Funktion erfolgreich beendet wird, werden alle Änderungen am Eingabedokument automatisch persistent gespeichert.

Functions 2.x oder höher

Wenn die Funktion erfolgreich beendet wird, werden alle Änderungen am Eingabedokument automatisch persistent gespeichert.

Erweiterung 4.x oder höher

Wenn die Funktion erfolgreich beendet wird, werden alle Änderungen am Eingabedokument automatisch persistent gespeichert.

Functions 2.x oder höher

Wenn die Funktion erfolgreich beendet wird, werden alle Änderungen am Eingabedokument automatisch persistent gespeichert.

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.

Erweiterung 4.x oder höher

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

Functions 2.x oder höher

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

Erweiterung 4.x oder höher

Wenn die Funktion ein einzelnes Dokument verarbeiten soll, kann die Cosmos DB-Eingabebindung an die folgenden Typen gebunden werden:

type	BESCHREIBUNG
Serialisierbare JSON-Typen	Functions versucht, die JSON-Daten des Dokuments in einen POCO-Typ (Plain-Old CLR Object) zu deserialisieren.

Wenn die Funktion mehrere Dokumente aus einer Abfrage verarbeiten soll, kann die Cosmos DB-Eingabebindung an die folgenden Typen gebunden werden:

type	BESCHREIBUNG
IEnumerable<T>, wobei T ein serialisierbarer JSON-Typ ist.	Eine Enumeration von Entitäten, die von der Abfrage zurückgegeben werden. Jeder Eintrag stellt eine Entität dar.
CosmosClient1	Ein Client, der mit dem Cosmos DB-Konto verbunden ist.
Datenbank1	Ein Client, der mit der Cosmos DB-Datenbank verbunden ist.
Container1	Ein Client, der mit dem Cosmos DB-Container verbunden ist.

¹ Um diese Typen zu verwenden, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0-preview1 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

Functions 2.x oder höher

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

Die @CosmosDBInput-Anmerkung der Runtimebibliothek für Java-Funktionen macht Azure Cosmos DB-Daten für die Funktion verfügbar. Diese Anmerkung kann mit nativen Java-Typen, POJOs oder Werten mit Optional<T>, die NULL-Werte annehmen können, verwendet werden.

Modell v4

Greifen Sie mithilfe von context.extraInputs.get() auf das Dokument zu.

Modell v3

Greifen Sie mithilfe von context.bindings.<name> auf das Dokument zu, wobei <name> der in der name-Eigenschaft von function.json angegebene Wert ist.

Aktualisierungen von Dokumenten werden beim Beenden der Funktion nicht automatisch durchgeführt. Verwenden Sie zum Aktualisieren von Dokumenten in einer Funktion eine Ausgabebindung. Weitere Details finden Sie im PowerShell-Beispiel.

Daten werden der Funktion über einen DocumentList-Parameter zur Verfügung gestellt. Änderungen am Dokument werden nicht automatisch dauerhaft gespeichert.

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

¹ 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.

² 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.

Nächste Schritte

• Ausführen einer Funktion, wenn ein Azure Cosmos DB-Dokument erstellt oder geändert wird (Trigger)
• Speichern der Änderungen an einem Azure Cosmos DB-Dokument (Ausgabebindung)