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

• Wersja 1
• Wersja 2

Ważne

Pomoc techniczna zakończy się w wersji 1.x środowiska uruchomieniowego usługi Azure Functions 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 usłudze Azure Functions. Usługa Azure Functions obsługuje powiązania wyzwalacza, danych wejściowych i wyjściowych dla usługi Azure Cosmos DB.

Uwaga

Ten artykuł dotyczy usługi 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 usługi Azure Functions 2.x.

To powiązanie pierwotnie nosiło nazwę DocumentDB. W usłudze Azure Functions w 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 apache Cassandra, usługi Azure Cosmos DB dla języka Apache Gremlin i usługi Azure Cosmos DB dla tabel.

Pakiety — Functions 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 powiązań wyjściowych w każdym środowisku projektowym.

Środowisko projektowe	Aby dodać obsługę w usłudze Functions 1.x
Programowanie lokalne: biblioteka klas języka C#	Instalowanie pakietu
Programowanie lokalne: skrypt języka C#, JavaScript, F#	Automatyczne
Programowanie w portalu	Automatyczne

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. Kanał informacyjny zmian publikuje wstawki i aktualizacje, a nie usunięcia.

Wyzwalacz — przykład

C#

W poniższym przykładzie przedstawiono funkcję języka C# w procesie wywoływaną w przypadku 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ę Języka 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. Oto przykład atrybutu CosmosDBTrigger w podpisie metody:

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

Pełny 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 atrybutu CosmosDBTrigger .

właściwość function.json	Właściwość atrybutu	opis
type	nie dotyczy	Musi być ustawiona wartość cosmosDBTrigger.
direction	nie dotyczy	Musi być ustawiona wartość in. Ten parametr jest ustawiany automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
name	nie dotyczy	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 monitorowanego konta usługi Azure Cosmos DB.
databaseName	Nazwa bazy danych	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 do usługi, która przechowuje kolekcję dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta connectionStringSetting wartość. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w portalu. Parametry połączenia dla kolekcji dzierżaw musi 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 podczas tworzenia 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. Domyślna wartość 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 ona prefiks do dzierżaw utworzonych w kolekcji dzierżaw dla tej funkcji, co pozwala na współużytkowanie tej samej kolekcji dzierżawy przez dwie oddzielne funkcje platformy Azure przy użyciu różnych prefiksów.
feedPollDelay	FeedPollDelay	(Opcjonalnie) Po ustawieniu definiuje, w milisekundach, opóźnienie między sondowaniem partycji dla 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 obliczeniowego, jeśli partycje są równomiernie dystrybuowane między znane wystąpienia 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 dla partycji, które są obecnie przechowywane przez wystąpienie. Wartość domyślna to 17000 (17 sekund).
checkpointFrequency	Punkt kontrolnyFrequency	(Opcjonalnie) Po ustawieniu definiuje 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ą ilość elementów odebranych 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 przy pierwszym uruchomieniu wyzwalacza, tak jak w kolejnych uruchomieniach, punkty kontrolne są już przechowywane. Ustawienie tej wartości 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 w 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 używania 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, tylko udostępnia sam dokument. Jeśli musisz obsługiwać aktualizacje i wstawiać inaczej, możesz to zrobić, implementując pola znacznika czasu 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 w formacie JSON
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy 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 elementu 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 w formacie JSON

W poniższym przykładzie pokazano 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 pokazano 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 trasy

W poniższym przykładzie pokazano funkcję języka C#, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa danych tras 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);
        }
    }
}

Pomiń przykłady danych wejściowych

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

W poniższym przykładzie pokazano funkcję języka C#, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa danych tras 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);
        }
    }
}

Pomiń przykłady danych 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);
        }
    }
}

Pomiń przykłady danych 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 wystąpienia dostarczonego DocumentClient przez powiązanie usługi Azure Cosmos DB, aby odczytać listę dokumentów. Wystąpienie DocumentClient może być również używane na potrzeby 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 w formacie JSON
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania
• Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy
• Wyzwalacz kolejki, uzyskiwanie wielu dokumentów przy użyciu zapytania SqlQuery

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie pokazano 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 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"
      ],
      "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, uzyskiwanie wielu dokumentów przy użyciu zapytania SqlQuery

W poniższym przykładzie pokazano 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 zwraca { "departmentId" : "Finance" } 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 atrybutu DocumentDB .

właściwość function.json	Właściwość atrybutu	opis
type	nie dotyczy	Musi być ustawiona wartość documentdb.
direction	nie dotyczy	Musi być ustawiona wartość in.
name	nie dotyczy	Nazwa parametru powiązania, który reprezentuje dokument w funkcji.
databaseName	Nazwa bazy danych	Baza danych zawierająca dokument.
collectionName	CollectionName	Nazwa kolekcji zawierającej dokument.
id	Id	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łączenie	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 wszelkie zmiany wprowadzone w dokumencie wejściowym za pomocą nazwanych parametrów wejściowych są automatycznie utrwalane.

JavaScript

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

Wyjście

Powiązanie wyjściowe usługi Azure Cosmos DB umożliwia napisanie 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 klasy 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

W poniższym przykładzie pokazano powiązanie wyjściowe usługi Azure Cosmos DB w pliku function.json i funkcję Języka JavaScript, która używa powiązania. Funkcja używa powiązania wejściowego kolejki dla kolejki, która odbiera kod 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 Dane wyjściowe — konfiguracja. Oto przykład atrybutu DocumentDB 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 atrybutu DocumentDB .

właściwość function.json	Właściwość atrybutu	opis
type	nie dotyczy	Musi być ustawiona wartość documentdb.
direction	nie dotyczy	Musi być ustawiona wartość out.
name	nie dotyczy	Nazwa parametru powiązania, który reprezentuje dokument w funkcji.
databaseName	Nazwa bazy danych	Baza danych zawierająca kolekcję, w której jest tworzony dokument.
collectionName	CollectionName	Nazwa kolekcji, w której jest tworzony dokument.
createIfNotExists	CreateIfNotExists	Wartość logiczna określają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, zobacz stronę z cennikiem.
partitionKey	PartitionKey	Jeśli CreateIfNotExists wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonej kolekcji.
collectionThroughput	CollectionThroughput	W CreateIfNotExists przypadku wartości true definiuje przepływność utworzonej kolekcji.
połączenie	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 zostaje 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 za pomocą usługi Azure Cosmos DB
• Dowiedz się więcej o wyzwalaczach i powiązaniach usługi Azure Functions