Powiązania usługi Azure Cosmos DB dla Azure Functions 1.x

• Wersja 1
• Wersja 2

Ważne

Wsparcie dla wersji 1.x środowiska uruchomieniowego Azure Functions zakończy się 14 września 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do wersji 4.x w celu uzyskania pełnej pomocy technicznej.

W tym artykule wyjaśniono, jak pracować z powiązaniami usługi Azure Cosmos DB w Azure Functions. Azure Functions obsługuje powiązania wyzwalacza, danych wejściowych i wyjściowych dla usługi Azure Cosmos DB.

Uwaga

Ten artykuł dotyczy Azure Functions 1.x. Aby uzyskać informacje na temat używania tych powiązań w usłudze Functions 2.x i nowszych, zobacz Powiązania usługi Azure Cosmos DB dla Azure Functions 2.x.

To powiązanie pierwotnie nosiło nazwę DocumentDB. W Azure Functions wersji 1.x nazwa wyzwalacza została zmieniona tylko na Azure Cosmos DB; powiązanie wejściowe, powiązanie wyjściowe i pakiet NuGet zachowują nazwę usługi DocumentDB.

Uwaga

Użycie powiązań usługi Azure Cosmos DB jest obsługiwane tylko w przypadku interfejsu API SQL. W przypadku wszystkich innych interfejsów API usługi Azure Cosmos DB należy uzyskać dostęp do bazy danych z funkcji przy użyciu klienta statycznego dla interfejsu API, w tym usługi Azure Cosmos DB dla bazy danych MongoDB, usługi Azure Cosmos DB dla bazy danych Apache Cassandra, usługi Azure Cosmos DB dla języka Apache Gremlin i usługi Azure Cosmos DB dla tabeli.

Pakiety — Funkcje 1.x

Powiązania usługi Azure Cosmos DB dla usługi Functions w wersji 1.x są dostępne w pakiecie NuGet Microsoft.Azure.WebJobs.Extensions.DocumentDB w wersji 1.x. Kod źródłowy powiązań znajduje się w repozytorium GitHub azure-webjobs-sdk-extensions .

W poniższej tabeli przedstawiono sposób dodawania obsługi tego powiązania w każdym środowisku deweloperów.

Środowisko deweloperskie	Aby dodać obsługę w programie Functions w wersji 1.x
Programowanie lokalne — biblioteka klas języka C#	Instalowanie pakietu
Programowanie lokalne — skrypt języka C#, JavaScript, F#	Automatyczny
Programowanie w portalu	Automatyczny

Wyzwalacz

Wyzwalacz usługi Azure Cosmos DB używa zestawienia zmian usługi Azure Cosmos DB do nasłuchiwania wstawiania i aktualizacji między partycjami. Źródło zmian publikuje wstawki i aktualizacje, a nie usunięcia.

Wyzwalacz — przykład

C#

Poniższy przykład przedstawia funkcję języka C# w procesie wywoływaną podczas wstawiania lub aktualizacji w określonej bazie danych i kolekcji.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;

namespace CosmosDBSamplesV1
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            TraceWriter log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.Info($"Documents modified: {documents.Count}");
                log.Info($"First document Id: {documents[0].Id}");
            }
        }
    }
}

JavaScript

W poniższym przykładzie pokazano powiązanie wyzwalacza usługi Azure Cosmos DB w pliku function.json i funkcję JavaScript , która używa powiązania. Funkcja zapisuje komunikaty dziennika podczas modyfikowania rekordów usługi Azure Cosmos DB.

Oto dane powiązania w pliku function.json :

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Oto kod JavaScript:

    module.exports = async function (context, documents) {
        context.log('First document Id modified : ', documents[0].id);
    }

Wyzwalacz — atrybuty

C#

W przypadku bibliotek klas języka C# w procesie użyj atrybutu CosmosDBTrigger .

Konstruktor atrybutu przyjmuje nazwę bazy danych i nazwę kolekcji. Aby uzyskać informacje o tych ustawieniach i innych właściwościach, które można skonfigurować, zobacz Wyzwalacz — konfiguracja. CosmosDBTrigger Oto przykład atrybutu w podpisie metody:

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

Kompletny przykład można znaleźć w temacie Trigger — C# example (Wyzwalacz — przykład w języku C#).

JavaScript

Atrybuty nie są obsługiwane przez język JavaScript.

Wyzwalacz — konfiguracja

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json i atrybucie CosmosDBTrigger .

function.json, właściwość	Właściwość atrybutu	Opis
Typu	n/d	Musi być ustawiona na cosmosDBTriggerwartość .
Kierunku	n/d	Musi być ustawiona na inwartość . Ten parametr jest ustawiany automatycznie podczas tworzenia wyzwalacza w Azure Portal.
Nazwa	n/d	Nazwa zmiennej używana w kodzie funkcji, która reprezentuje listę dokumentów ze zmianami.
connectionStringSetting	ConnectionStringSetting	Nazwa ustawienia aplikacji zawierającego parametry połączenia używane do nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB.
databaseName	Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
Collectionname	Collectionname	Nazwa monitorowanej kolekcji.
leaseConnectionStringSetting	LeaseConnectionStringSetting	(Opcjonalnie) Nazwa ustawienia aplikacji zawierającego parametry połączenia z usługą, która przechowuje kolekcję dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta connectionStringSetting wartość . Ten parametr jest ustawiany automatycznie po utworzeniu powiązania w portalu. Parametry połączenia dla kolekcji dzierżaw muszą mieć uprawnienia do zapisu.
leaseDatabaseName	LeaseDatabaseName	(Opcjonalnie) Nazwa bazy danych, która zawiera kolekcję używaną do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość databaseName ustawienia. Ten parametr jest ustawiany automatycznie po utworzeniu powiązania w portalu.
leaseCollectionName	LeaseCollectionName	(Opcjonalnie) Nazwa kolekcji używanej do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość leases .
createLeaseCollectionIfNotExists	CreateLeaseCollectionIfNotExists	(Opcjonalnie) Gdy jest ustawiona wartość true, kolekcja dzierżaw jest tworzona automatycznie, gdy jeszcze nie istnieje. Wartość domyślna to false.
leasesCollectionThroughput	LeasesCollectionThroughput	(Opcjonalnie) Definiuje liczbę jednostek żądań do przypisania podczas tworzenia kolekcji dzierżaw. To ustawienie jest używane tylko wtedy, gdy createLeaseCollectionIfNotExists jest ustawione na truewartość . Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania przy użyciu portalu.
leaseCollectionPrefix	LeaseCollectionPrefix	(Opcjonalnie) Po ustawieniu dodaje prefiks do dzierżaw utworzonych w kolekcji Dzierżawa dla tej funkcji, co skutecznie umożliwia dwa oddzielne Azure Functions współużytkowania tej samej kolekcji dzierżawy przy użyciu różnych prefiksów.
feedPollDelay	FeedPollDelay	(Opcjonalnie) Po ustawieniu definiuje, w milisekundach, opóźnienie między sondowaniem partycji pod kątem nowych zmian w kanale informacyjnym, po opróżnieniu wszystkich bieżących zmian. Wartość domyślna to 5000 (5 sekund).
leaseAcquireInterval	LeaseAcquireInterval	(Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał uruchamiania zadania do obliczenia, jeśli partycje są dystrybuowane równomiernie wśród znanych wystąpień hosta. Wartość domyślna to 13000 (13 sekund).
leaseExpirationInterval	LeaseExpirationInterval	(Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał, dla którego dzierżawa jest wykonywana w dzierżawie reprezentującej partycję. Jeśli dzierżawa nie zostanie odnowiona w tym interwale, spowoduje to wygaśnięcie, a własność partycji zostanie przeniesiona do innego wystąpienia. Wartość domyślna to 60000 (60 sekund).
leaseRenewInterval	LeaseRenewInterval	(Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał odnawiania dla wszystkich dzierżaw partycji, które są obecnie przechowywane przez wystąpienie. Wartość domyślna to 17000 (17 sekund).
checkpointFrequency	CheckpointFrequency	(Opcjonalnie) Po ustawieniu definiuje on interwał między punktami kontrolnymi dzierżawy w milisekundach. Wartość domyślna jest zawsze po każdym wywołaniu funkcji.
maxItemsPerInvocation	MaxItemsPerInvocation	(Opcjonalnie) Po ustawieniu dostosowuje maksymalną liczbę odebranych elementów na wywołanie funkcji.
startFromBeginning	StartFromBeginning	(Opcjonalnie) Po ustawieniu informuje wyzwalacz o rozpoczęciu odczytywania zmian od początku historii kolekcji zamiast bieżącej godziny. Działa to tylko po raz pierwszy po uruchomieniu wyzwalacza, ponieważ w kolejnych uruchomieniach punkty kontrolne są już przechowywane. Ustawienie tego ustawienia na true wartość , gdy istnieją już utworzone dzierżawy, nie ma wpływu.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Wyzwalacz — użycie

Wyzwalacz wymaga drugiej kolekcji używanej do przechowywania dzierżaw na partycjach. Zarówno monitorowana kolekcja, jak i kolekcja zawierająca dzierżawy muszą być dostępne, aby wyzwalacz działał.

Ważne

Jeśli wiele funkcji jest skonfigurowanych do korzystania z wyzwalacza usługi Azure Cosmos DB dla tej samej kolekcji, każda z funkcji powinna używać dedykowanej kolekcji dzierżaw lub określać inną LeaseCollectionPrefix dla każdej funkcji. W przeciwnym razie zostanie wyzwolona tylko jedna z funkcji. Aby uzyskać informacje o prefiksie, zobacz sekcję Konfiguracja.

Wyzwalacz nie wskazuje, czy dokument został zaktualizowany, czy wstawiony, po prostu udostępnia sam dokument. Jeśli musisz obsługiwać aktualizacje i wstawiać inaczej, możesz to zrobić, implementując pola sygnatury czasowej na potrzeby wstawiania lub aktualizacji.

Dane wejściowe

Powiązanie wejściowe usługi Azure Cosmos DB używa interfejsu API SQL, aby pobrać co najmniej jeden dokument usługi Azure Cosmos DB, a następnie przekazuje go do parametru wejściowego funkcji. Identyfikator dokumentu lub parametry zapytania można określić na podstawie wyzwalacza wywołującego funkcję.

Dane wejściowe — przykład

C#

Ta sekcja zawiera następujące przykłady:

• Wyzwalacz kolejki, wyszukiwanie identyfikatora z formatu JSON
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych tras
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych tras przy użyciu zapytania SqlQuery
• Wyzwalacz HTTP, uzyskiwanie wielu dokumentów przy użyciu zapytania SqlQuery
• Wyzwalacz HTTP, uzyskiwanie wielu dokumentów przy użyciu klasy DocumentClient

Przykłady odnoszą się do prostego ToDoItem typu:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Wyzwalacz kolejki, wyszukiwanie identyfikatora z formatu JSON

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez komunikat kolejki zawierający obiekt JSON. Wyzwalacz kolejki analizuje kod JSON do obiektu o nazwie ToDoItemLookup, który zawiera identyfikator do wyszukania. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}")]ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId}");

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia wyszukiwanego identyfikatora. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych tras

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa danych trasy do określenia identyfikatora do wyszukania. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static HttpResponseMessage Run(
            [HttpTrigger(
                AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Pomijanie przykładów wejściowych

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych tras przy użyciu zapytania SqlQuery

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa danych trasy do określenia identyfikatora do wyszukania. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")] IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Pomijanie przykładów wejściowych

Wyzwalacz HTTP, uzyskiwanie wielu dokumentów przy użyciu zapytania SqlQuery

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera listę dokumentów. Funkcja jest wyzwalana przez żądanie HTTP. Zapytanie jest określone we właściwości atrybutu SqlQuery .

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Pomijanie przykładów wejściowych

Wyzwalacz HTTP, uzyskiwanie wielu dokumentów przy użyciu klasy DocumentClient (C#)

W poniższym przykładzie przedstawiono funkcję języka C# , która pobiera listę dokumentów. Funkcja jest wyzwalana przez żądanie HTTP. Kod używa DocumentClient wystąpienia dostarczonego przez powiązanie usługi Azure Cosmos DB, aby odczytać listę dokumentów. Wystąpienie DocumentClient może być również używane do operacji zapisu.

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 System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
            string searchterm = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
                .Value;

            if (searchterm == null)
            {
                return req.CreateResponse(HttpStatusCode.NotFound);
            }

            log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
            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.Info(result.Description);
                }
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

JavaScript

Ta sekcja zawiera następujące przykłady:

• Wyzwalacz kolejki, wyszukiwanie identyfikatora z formatu JSON
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych tras
• Wyzwalacz kolejki, uzyskiwanie wielu dokumentów przy użyciu zapytania SqlQuery

Wyzwalacz kolejki, wyszukiwanie identyfikatora z formatu JSON

W poniższym przykładzie przedstawiono powiązanie wejściowe usługi Azure Cosmos DB w pliku function.json i funkcję JavaScript , która używa powiązania. Funkcja odczytuje pojedynczy dokument i aktualizuje wartość tekstową dokumentu.

Oto dane powiązania w pliku function.json :

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

W sekcji konfiguracji opisano te właściwości.

Oto kod JavaScript:

    // 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!";
    };

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania

W poniższym przykładzie przedstawiono funkcję Języka JavaScript , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia wyszukiwanego identyfikatora. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

Oto plik function.json :

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

Oto kod JavaScript:

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy

W poniższym przykładzie pokazano funkcję Języka JavaScript , która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia wyszukiwanego identyfikatora. Ten identyfikator służy do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

Oto plik function.json :

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

Oto kod JavaScript:

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

Wyzwalacz kolejki, pobieranie wielu dokumentów przy użyciu zapytania SqlQuery

Poniższy przykład przedstawia powiązanie wejściowe usługi Azure Cosmos DB w pliku function.json i funkcję JavaScript , która używa powiązania. Funkcja pobiera wiele dokumentów określonych przez zapytanie SQL przy użyciu wyzwalacza kolejki w celu dostosowania parametrów zapytania.

Wyzwalacz kolejki udostępnia parametr departmentId. Komunikat w kolejce z poleceniem { "departmentId" : "Finance" } zwróci wszystkie rekordy dla działu finansowego.

Oto dane powiązania w pliku function.json :

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

W sekcji konfiguracji opisano te właściwości.

Oto kod JavaScript:

    module.exports = async function (context, input) {
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }
    };

Dane wejściowe — atrybuty

C#

W bibliotekach klas języka C# w procesie użyj atrybutu DocumentDB .

Konstruktor atrybutu przyjmuje nazwę bazy danych i nazwę kolekcji. Aby uzyskać informacje o tych ustawieniach i innych właściwościach, które można skonfigurować, zobacz następującą sekcję konfiguracji.

JavaScript

Atrybuty nie są obsługiwane przez język JavaScript.

Dane wejściowe — konfiguracja

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json i atrybucie DocumentDB .

function.json, właściwość	Właściwość atrybutu	Opis
Typu	n/d	Musi być ustawiona na documentdbwartość .
Kierunku	n/d	Musi być ustawiona na inwartość .
Nazwa	n/d	Nazwa parametru powiązania, który reprezentuje dokument w funkcji.
databaseName	Databasename	Baza danych zawierająca dokument.
Collectionname	Collectionname	Nazwa kolekcji zawierającej dokument.
id	Identyfikator	Identyfikator dokumentu do pobrania. Ta właściwość obsługuje wyrażenia powiązań. Nie ustawiaj zarówno właściwości id , jak i sqlQuery . Jeśli nie ustawisz żadnej z nich, cała kolekcja zostanie pobrana.
sqlQuery	Zapytanie SQL	Zapytanie SQL usługi Azure Cosmos DB używane do pobierania wielu dokumentów. Właściwość obsługuje powiązania środowiska uruchomieniowego, jak w tym przykładzie: SELECT * FROM c where c.departmentId = {departmentId}. Nie ustawiaj zarówno właściwości id , jak i sqlQuery . Jeśli nie ustawisz żadnej z nich, cała kolekcja zostanie pobrana.
Połączenia	ConnectionStringSetting	Nazwa ustawienia aplikacji zawierającego parametry połączenia usługi Azure Cosmos DB.
partitionKey	PartitionKey	Określa wartość klucza partycji dla wyszukiwania. Może zawierać parametry powiązania.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Dane wejściowe — użycie

C#

Po pomyślnym zakończeniu działania funkcji wszystkie zmiany wprowadzone w dokumencie wejściowym za pośrednictwem nazwanych parametrów wejściowych są automatycznie utrwalane.

JavaScript

Aktualizacje nie są wykonywane automatycznie po zakończeniu działania funkcji. Zamiast tego użyj polecenia context.bindings.<documentName>In i context.bindings.<documentName>Out , aby dokonać aktualizacji. Zobacz przykład danych wejściowych.

Dane wyjściowe

Powiązanie wyjściowe usługi Azure Cosmos DB umożliwia zapisanie nowego dokumentu w bazie danych usługi Azure Cosmos DB przy użyciu interfejsu API SQL.

Dane wyjściowe — przykład

C#

Ta sekcja zawiera następujące przykłady:

• Wyzwalacz kolejki, zapis jednego dokumentu
• Wyzwalacz kolejki, zapisywanie dokumentów przy użyciu polecenia IAsyncCollector

Przykłady odnoszą się do prostego ToDoItem typu:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Wyzwalacz kolejki, zapis jednego dokumentu

W poniższym przykładzie pokazano funkcję języka C# , która dodaje dokument do bazy danych przy użyciu danych podanych w komunikacie z usługi Queue Storage.

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

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

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

Wyzwalacz kolejki, zapisywanie dokumentów przy użyciu interfejsu IAsyncCollector

W poniższym przykładzie pokazano funkcję języka C# , która dodaje kolekcję dokumentów do bazy danych przy użyciu danych podanych w kodzie JSON komunikatu kolejki.

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

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

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

JavaScript

Poniższy przykład przedstawia powiązanie wyjściowe usługi Azure Cosmos DB w pliku function.json i funkcję JavaScript , która używa powiązania. Funkcja używa powiązania wejściowego kolejki dla kolejki, która odbiera dane JSON w następującym formacie:

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

Funkcja tworzy dokumenty usługi Azure Cosmos DB w następującym formacie dla każdego rekordu:

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

Oto dane powiązania w pliku function.json :

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

W sekcji konfiguracji opisano te właściwości.

Oto kod JavaScript:

    module.exports = async function (context) {

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

Dane wyjściowe — atrybuty

C#

W bibliotekach klas języka C# w procesie użyj atrybutu DocumentDB .

Konstruktor atrybutu przyjmuje nazwę bazy danych i nazwę kolekcji. Aby uzyskać informacje o tych ustawieniach i innych właściwościach, które można skonfigurować, zobacz Output - configuration (Dane wyjściowe — konfiguracja). DocumentDB Oto przykład atrybutu w podpisie metody:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

Pełny przykład można znaleźć w temacie Output (Dane wyjściowe).

JavaScript

Atrybuty nie są obsługiwane przez język JavaScript.

Dane wyjściowe — konfiguracja

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json i atrybucie DocumentDB .

function.json, właściwość	Właściwość atrybutu	Opis
Typu	n/d	Musi być ustawiona na documentdbwartość .
Kierunku	n/d	Musi być ustawiona na outwartość .
Nazwa	n/d	Nazwa parametru powiązania, który reprezentuje dokument w funkcji.
databaseName	Databasename	Baza danych zawierająca kolekcję, w której tworzony jest dokument.
Collectionname	Collectionname	Nazwa kolekcji, w której tworzony jest dokument.
createIfNotExists	CreateIfNotExists	Wartość logiczna wskazująca, czy kolekcja jest tworzona, gdy nie istnieje. Wartość domyślna to false , ponieważ nowe kolekcje są tworzone z zarezerwowaną przepływnością, co ma wpływ na koszty. Aby uzyskać więcej informacji, odwiedź stronę cennika.
partitionKey	PartitionKey	Gdy CreateIfNotExists wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonej kolekcji.
collectionThroughput	CollectionThroughput	W przypadku CreateIfNotExists wartości true definiuje przepływność utworzonej kolekcji.
Połączenia	ConnectionStringSetting	Nazwa ustawienia aplikacji zawierającego parametry połączenia usługi Azure Cosmos DB.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Dane wyjściowe — użycie

Domyślnie podczas zapisywania w parametrze wyjściowym w funkcji dokument jest tworzony w bazie danych. Ten dokument ma automatycznie wygenerowany identyfikator GUID jako identyfikator dokumentu. Identyfikator dokumentu wyjściowego można określić, określając id właściwość w obiekcie JSON przekazanym do parametru wyjściowego.

Uwaga

Po określeniu identyfikatora istniejącego dokumentu zostanie on zastąpiony przez nowy dokument wyjściowy.

Wyjątki i kody powrotne

Wiązanie	Odwołanie
Azure Cosmos DB	Kody stanu HTTP dla usługi Azure Cosmos DB

Następne kroki

• Dowiedz się więcej o przetwarzaniu bezserwerowych baz danych w usłudze Azure Cosmos DB
• Dowiedz się więcej o wyzwalaczach i powiązaniach Azure Functions