Azure Cosmos DB indatabindning för Azure Functions 2.x och senare

Azure Cosmos DB-indatabindningen använder SQL API för att hämta en eller flera Azure Cosmos DB-dokument och skickar dem till indataparametern för funktionen. Dokument-ID:t och frågeparametrarna kan fastställas baserat på den utlösare som anropar funktionen.

Information om installation och konfiguration finns i översikten.

Anteckning

Om samlingen är partitioneradmåste sökningsåtgärder också ange partitionsnyckelvärdet.

Det här avsnittet innehåller följande exempel:

Exemplen refererar till en enkel 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; }
    }
}

Köutlösare, leta upp ID från JSON

I följande exempel visas en C#-funktion som hämtar ett enskilt dokument. Funktionen utlöses av ett kömeddelande som innehåller ett JSON-objekt. Köutlösaren parsar JSON till ett objekt av typen , som innehåller ToDoItemLookup ID:t och partitionsnyckelvärdet som ska sökas upp. ID:t och partitionsnyckelvärdet används för att hämta ToDoItem ett dokument från den angivna databasen och samlingen.

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-utlösare, leta upp ID från frågesträng

I följande exempel visas en C#-funktion som hämtar ett enskilt dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange ID och partitionsnyckelvärde som ska sökas upp. ID:t och partitionsnyckelvärdet används för att hämta ToDoItem ett dokument från den angivna databasen och samlingen.

Anteckning

Http-frågesträngsparametern är fallkänslig.

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-utlösare, leta upp ID från vägdata

I följande exempel visas en C#-funktion som hämtar ett enskilt dokument. Funktionen utlöses av en HTTP-begäran som använder vägdata för att ange ID och partitionsnyckelvärde som ska sökas upp. ID:t och partitionsnyckelvärdet används för att hämta ToDoItem ett dokument från den angivna databasen och samlingen.

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-utlösare, leta upp ID från vägdata med hjälp av SqlQuery

I följande exempel visas en C#-funktion som hämtar ett enskilt dokument. Funktionen utlöses av en HTTP-begäran som använder vägdata för att ange det ID som ska sökas upp. Detta ID används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

Exemplet visar hur du använder ett bindningsuttryck i SqlQuery parametern . Du kan skicka vägdata till SqlQuery parametern som visas, men för närvarande kan du inte skicka frågesträngsvärden .

Anteckning

Om du bara behöver fråga efter ID:t rekommenderar vi att du använder en sökning, som i föregående exempel,eftersom den förbrukar färre enheter för begäran. Punktläsningsåtgärder (GET) är mer effektiva än frågor efter 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-utlösare, hämta flera dokument med hjälp av SqlQuery

I följande exempel visas en C#-funktion som hämtar en lista med dokument. Funktionen utlöses av en HTTP-begäran. Frågan anges i SqlQuery attributegenskapen.

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-utlösare, hämta flera dokument med DocumentClient

I följande exempel visas en C#-funktion som hämtar en lista med dokument. Funktionen utlöses av en HTTP-begäran. Koden använder en instans DocumentClient som tillhandahålls av Azure Cosmos DB för att läsa en lista över dokument. Instansen DocumentClient kan också användas för skrivåtgärder.

Anteckning

Du kan också använda gränssnittet IDocumentClient för att göra testningen enklare.

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-utlösare, hämta flera dokument med hjälp av CosmosClient

I följande exempel visas en C#-funktion som hämtar en lista med dokument. Funktionen utlöses av en HTTP-begäran. Koden använder en -instans som tillhandahålls av Azure Cosmos DB-bindningen, som finns i CosmosClient tilläggsversion 4.x, för att läsa en lista över dokument. Instansen CosmosClient kan också användas för skrivåtgärder.

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();
        }
    }
}

Attribut och anteckningar

I C#-klassbibliotekanvänder du CosmosDB-attributet.

Attributets konstruktor tar databasnamnet och samlingsnamnet. I tilläggsversion 4.x har vissa inställningar och egenskaper tagits bort eller bytt namn. Information om inställningar och andra egenskaper som du kan konfigurera för alla versioner finns i följande konfigurationsavsnitt.

Konfiguration

I följande tabell beskrivs de bindningskonfigurationsegenskaper som du anger i function.json-filen och CosmosDB -attributet.

function.json-egenskap Attributegenskap Description
Typ saknas Måste anges till cosmosDB .
riktning saknas Måste anges till in .
Namn saknas Namnet på bindningsparametern som representerar dokumentet i funktionen.
Databasename DatabaseName Databasen som innehåller dokumentet.
collectionName
eller
containerName
CollectionName
eller
ContainerName
Namnet på samlingen som innehåller dokumentet.

I version 4.x av tillägget kallas den här egenskapen för ContainerName .
id Id ID för dokumentet som ska hämtas. Den här egenskapen stöder bindningsuttryck. Ange inte både - och id sqlQuery-egenskaperna. Om du inte anger någon av dem hämtas hela samlingen.
sqlQuery SqlQuery En Azure Cosmos DB SQL fråga som används för att hämta flera dokument. Egenskapen stöder körningsbindningar, som i det här exemplet: SELECT * FROM c where c.departmentId = {departmentId} . Ange inte både egenskaperna id och sqlQuery . Om du inte anger någon av dem hämtas hela samlingen.
connectionStringSetting
eller
Anslutning
ConnectionStringSetting
eller
Anslutning
Namnet på appinställningen som innehåller din Azure Cosmos DB anslutningssträng.

I version 4.x av tillägget kallas den här egenskapen för Connection . Värdet är namnet på en appinställning som antingen innehåller anslutningssträngen eller innehåller ett konfigurationsavsnitt eller prefix som definierar anslutningen. Se Anslutningar.
partitionKey PartitionKey Anger partitionsnyckelvärdet för uppslag. Kan innehålla bindningsparametrar. Det krävs för uppslag i partitionerade samlingar.
preferredLocations PreferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB tjänsten. Värdena ska vara kommaavgränsade. Till exempel "USA, östra,USA, södra centrala,Europa, norra".

När du utvecklar lokalt går appinställningarna till ilocal.settings.js på filen.

Användning

När funktionen avslutas sparas automatiskt alla ändringar som görs i indatadokumentet via namngivna indataparametrar.

Nästa steg