Powiązanie wyjściowe usługi Azure Cosmos DB dla usługi Azure Functions w wersji 2.x lub nowszej

Artykuł
10/18/2023

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.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Usługa Azure Functions obsługuje dwa modele programowania dla języka Python. Sposób definiowania powiązań zależy od wybranego modelu programowania.

Wersja 2
Wersja 1

Model programowania w języku Python w wersji 2 umożliwia definiowanie powiązań przy użyciu dekoratorów bezpośrednio w kodzie funkcji języka Python. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów języka Python.

Ten artykuł obsługuje oba modele programowania.

Funkcję języka C# można utworzyć przy użyciu jednego z następujących trybów języka C#:

Model izolowanego procesu roboczego: skompilowana funkcja języka C#, która jest uruchamiana w procesie roboczym izolowanym od środowiska uruchomieniowego. Proces izolowanego procesu roboczego jest wymagany do obsługi funkcji języka C# uruchomionych w wersjach LTS i innych niż LTS platformy .NET oraz programu .NET Framework. Rozszerzenia dla izolowanych funkcji procesu roboczego używają Microsoft.Azure.Functions.Worker.Extensions.* przestrzeni nazw.
Model przetwarzania: skompilowana funkcja języka C#, która działa w tym samym procesie co środowisko uruchomieniowe usługi Functions. W odmianie tego modelu funkcje można uruchamiać przy użyciu skryptów języka C#, które są obsługiwane głównie w przypadku edytowania portalu języka C#. Rozszerzenia dla funkcji przetwarzania używają Microsoft.Azure.WebJobs.Extensions.* przestrzeni nazw.

Ważne

Wsparcie zostanie zakończone dla modelu procesu 10 listopada 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do izolowanego modelu procesu roboczego w celu uzyskania pełnej obsługi.

Przykład

O ile nie określono inaczej, przykłady w tym artykule mają wersję docelową 3.x rozszerzenia usługi Azure Cosmos DB. Aby używać z rozszerzeniem w wersji 4.x, należy zastąpić ciąg collection we właściwości i nazwach atrybutów elementami container i connection_string_settingconnection.

Model izolowanego procesu roboczego
Model w procesie

Poniższy kod definiuje MyDocument typ:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

W poniższym przykładzie zwracany typ to IReadOnlyList<T>, który jest zmodyfikowaną listą dokumentów z parametru powiązania wyzwalacza:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

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

Wyzwalacz kolejki, zapis jednego dokumentu
Wyzwalacz kolejki, zapis jednego dokumentu (rozszerzenie w wersji 4)
Wyzwalacz kolejki, zapisywanie dokumentów przy użyciu klasy IAsyncCollector

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

namespace CosmosDBSamplesV2
{
    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 Microsoft.Extensions.Logging;
using System;

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

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

Wyzwalacz kolejki, zapis jednego dokumentu (rozszerzenie w wersji 4)

Aplikacje korzystające z rozszerzenia usługi Azure Cosmos DB w wersji 4.x lub nowszej będą miały różne właściwości atrybutów, które przedstawiono poniżej. 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 Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"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;
using Microsoft.Extensions.Logging;

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

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

Wyzwalacz kolejki, zapisywanie komunikatu w bazie danych za pośrednictwem wartości zwracanej
Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pomocą wartości zwracanej
Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pośrednictwem elementu OutputBinding
Wyzwalacz HTTP, zapisywanie wielu dokumentów w bazie danych za pomocą funkcji OutputBinding

Wyzwalacz kolejki, zapisywanie komunikatu w bazie danych za pośrednictwem wartości zwracanej

Poniższy przykład przedstawia funkcję Języka Java, która dodaje dokument do bazy danych z danymi z komunikatu w usłudze Queue Storage.

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

Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pomocą wartości zwracanej

W poniższym przykładzie pokazano funkcję Języka Java, której podpis jest oznaczony adnotacją @CosmosDBOutput i ma zwracaną wartość typu String. Dokument JSON zwrócony przez funkcję zostanie automatycznie zapisany w odpowiedniej kolekcji usługi Azure Cosmos DB.

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

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

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

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

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

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

        return jsonDocument;
    }

Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pośrednictwem elementu OutputBinding

W poniższym przykładzie pokazano funkcję Języka Java, która zapisuje dokument w usłudze Azure Cosmos DB za pośrednictwem parametru wyjściowego OutputBinding<T> . W tym przykładzie outputItem parametr musi być oznaczony adnotacją , @CosmosDBOutputa nie sygnaturą funkcji. Funkcja OutputBinding<T> umożliwia funkcji korzystanie z powiązania w celu zapisania dokumentu w usłudze Azure Cosmos DB, a jednocześnie umożliwia zwrócenie innej wartości do obiektu wywołującego funkcję, takiego jak kod JSON lub dokument XML.

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

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

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

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

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

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

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

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

Wyzwalacz HTTP, zapisywanie wielu dokumentów w bazie danych za pomocą funkcji OutputBinding

W poniższym przykładzie pokazano funkcję Języka Java, która zapisuje wiele dokumentów w usłudze Azure Cosmos DB za pośrednictwem parametru wyjściowego OutputBinding<T> . W tym przykładzie outputItem parametr jest oznaczony adnotacją , @CosmosDBOutputa nie sygnaturą funkcji. Parametr outputItem wyjściowy zawiera listę ToDoItem obiektów jako typ parametru szablonu. Użycie OutputBinding<T> funkcji umożliwia korzystanie z powiązania w celu zapisania dokumentów w usłudze Azure Cosmos DB, a jednocześnie umożliwia zwrócenie innej wartości do obiektu wywołującego funkcję, takiego jak dokument JSON lub XML.

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

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

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

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

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

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

          items.add(item);
        }

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

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

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @CosmosDBOutput adnotacji dotyczącej parametrów, które zostaną zapisane w usłudze Azure Cosmos DB. Typ parametru adnotacji to OutputBinding<T>, gdzie T jest natywnym typem Języka Java lub poJO.

Model w wersji 4
Model w wersji 3

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalaną przez kolejkę magazynu, 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 kod TypeScript:

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

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Aby wyświetlić wiele dokumentów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Model w wersji 4
Model w wersji 3

W poniższym przykładzie pokazano, jak kolejka magazynu wyzwoliła funkcję JavaScript 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 kod JavaScript:

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

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Aby wyświetlić wiele dokumentów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

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": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "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
      });
    };

W przypadku wstawiania zbiorczego najpierw utwórz obiekty, a następnie uruchom funkcję stringify. Oto kod JavaScript:

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "id": "John Henry-123456",
            "name": "John Henry",
            "employeeId": "123456",
            "address": "A town nearby"
        },
        {
            "id": "John Doe-123457",
            "name": "John Doe",
            "employeeId": "123457",
            "address": "A town far away"
        }]);
    };

W poniższym przykładzie pokazano, jak zapisywać dane w usłudze Azure Cosmos DB przy użyciu powiązania wyjściowego. Powiązanie jest deklarowane w pliku konfiguracji funkcji (functions.json) i pobiera dane z komunikatu kolejki i zapisuje je w dokumencie usługi Azure Cosmos DB.

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

W pliku run.ps1 obiekt zwrócony z funkcji jest mapowany na EmployeeDocument obiekt, który jest utrwalany w bazie danych.

param($QueueItem, $TriggerMetadata) 

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

W poniższym przykładzie pokazano, jak napisać dokument do bazy danych usługi Azure Cosmos DB jako dane wyjściowe funkcji. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

Wersja 2
Wersja 1

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

Definicja powiązania jest definiowana w function.json , gdzie typ jest ustawiony na cosmosDB.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Aby zapisać w bazie danych, przekaż obiekt dokumentu do set metody parametru bazy danych.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

Atrybuty

Biblioteki języka C# procesu roboczego zarówno w procesie przetwarzania procesów procesowych, jak i izolowanych, używają atrybutów do zdefiniowania funkcji. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

Właściwość atrybutu	opis
Połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
ContainerName	Nazwa monitorowanego kontenera.
CreateIfNotExists	Wartość logiczna wskazująca, czy kontener jest tworzony, gdy nie istnieje. Wartość domyślna to false , ponieważ nowe kontenery są tworzone z zarezerwowaną przepływnością, co ma wpływ na koszty. Aby uzyskać więcej informacji, zobacz stronę z cennikiem.
PartitionKey	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonego kontenera. Może zawierać parametry powiązania.
ContainerThroughput	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje przepływność utworzonego kontenera.
PreferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.

Właściwość atrybutu	opis
Połączenie ionStringSetting	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
Collectionname	Nazwa monitorowanej kolekcji.
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	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonej kolekcji. Może zawierać parametry powiązania.
CollectionThroughput	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje przepływność utworzonej kolekcji.
PreferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.
UseMultipleWriteLocations	(Opcjonalnie) W przypadku ustawienia `true` na wartość wraz z `PreferredLocations`programem program obsługuje zapisy w wielu regionach w usłudze Azure Cosmos DB.

Właściwość atrybutu	opis
Połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
ContainerName	Nazwa monitorowanego kontenera.
CreateIfNotExists	Wartość logiczna wskazująca, czy kontener jest tworzony, gdy nie istnieje. Wartość domyślna to false , ponieważ nowe kontenery są tworzone z zarezerwowaną przepływnością, co ma wpływ na koszty. Aby uzyskać więcej informacji, zobacz stronę z cennikiem.
PartitionKey	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonego kontenera. Może zawierać parametry powiązania.
ContainerThroughput	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje przepływność utworzonego kontenera.
PreferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.

Właściwość atrybutu	opis
Połączenie ionStringSetting	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
Collectionname	Nazwa monitorowanej kolekcji.
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	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonej kolekcji. Może zawierać parametry powiązania.
CollectionThroughput	Jeśli `CreateIfNotExists` wartość ma wartość true, definiuje przepływność utworzonej kolekcji.
PreferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.
UseMultipleWriteLocations	(Opcjonalnie) W przypadku ustawienia `true` na wartość wraz z `PreferredLocations`programem program obsługuje zapisy w wielu regionach w usłudze Azure Cosmos DB.

Dekoratory

Dotyczy tylko modelu programowania w wersji 2 języka Python.

W przypadku funkcji języka Python w wersji 2 zdefiniowanych przy użyciu dekoratora następujące właściwości w pliku cosmos_db_output:

Właściwości	opis
`arg_name`	Nazwa zmiennej używana w kodzie funkcji, która reprezentuje listę dokumentów ze zmianami.
`database_name`	Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
`collection_name`	Nazwa monitorowanej kolekcji usługi Azure Cosmos DB.
`create_if_not_exists`	Wartość logiczna wskazująca, czy baza danych i kolekcja powinny zostać utworzone, jeśli nie istnieją.
`connection_string_setting`	Parametry połączenia monitorowanej usługi Azure Cosmos DB.

Aby zapoznać się z funkcjami języka Python zdefiniowanymi przy użyciu function.json, zobacz sekcję Konfiguracja .

Adnotacje

Z biblioteki środowiska uruchomieniowego funkcji Języka Java użyj @CosmosDBOutput adnotacji dotyczącej parametrów zapisywanych w usłudze Azure Cosmos DB. Adnotacja obsługuje następujące właściwości:

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

Model w wersji 4
Model w wersji 3

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego output.cosmosDB() do metody . Właściwości type, directioni name nie mają zastosowania do modelu w wersji 4.

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json , gdzie właściwości różnią się wersją rozszerzenia:

Rozszerzenie 4.x+
Funkcje 2.x+

właściwość function.json	opis
Połączenia	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
containerName	Nazwa monitorowanego kontenera.
createIfNotExists	Wartość logiczna wskazująca, czy kontener jest tworzony, gdy nie istnieje. Wartość domyślna to false , ponieważ nowe kontenery są tworzone z zarezerwowaną przepływnością, co ma wpływ na koszty. Aby uzyskać więcej informacji, zobacz stronę z cennikiem.
partitionKey	Jeśli `createIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonego kontenera. Może zawierać parametry powiązania.
containerThroughput	Jeśli `createIfNotExists` wartość ma wartość true, definiuje przepływność utworzonego kontenera.
preferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.

właściwość function.json	opis
connectionStringSetting	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename	Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
Collectionname	Nazwa monitorowanej kolekcji.
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	Jeśli `createIfNotExists` wartość ma wartość true, definiuje ścieżkę klucza partycji dla utworzonej kolekcji. Może zawierać parametry powiązania.
collectionThroughput	Jeśli `createIfNotExists` wartość ma wartość true, definiuje przepływność utworzonej kolekcji.
preferredLocations	(Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład `East US,South Central US,North Europe`.
useMultipleWriteLocations	(Opcjonalnie) W przypadku ustawienia `true` na wartość wraz z `preferredLocations`programem program obsługuje zapisy w wielu regionach w usłudze Azure Cosmos DB.

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Użycie

Domyślnie podczas zapisywania w parametrze wyjściowym w funkcji dokument jest tworzony w bazie danych. Należy określić identyfikator dokumentu wyjściowego, 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.

Typ parametru obsługiwany przez powiązanie wyjściowe usługi Cosmos DB zależy od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Jeśli chcesz, aby funkcja zapisywała w jednym dokumencie, powiązanie wyjściowe usługi Cosmos DB może wiązać się z następującymi typami:

Type	Opis
Typy serializowalne w formacie JSON	Obiekt reprezentujący zawartość JSON dokumentu. Funkcje próbują serializować zwykły typ obiektu CLR (POCO) do danych JSON.

Jeśli chcesz, aby funkcja zapisywała w wielu dokumentach, powiązanie wyjściowe usługi Cosmos DB może wiązać się z następującymi typami:

Type	Opis
`T[]` gdzie `T` jest typem serializowalnym JSON	Tablica zawierająca wiele dokumentów. Każdy wpis reprezentuje jeden dokument.

W przypadku innych scenariuszy wyjściowych utwórz typy i użyj ich bezpośrednio z witryny Microsoft.Azure.Cosmos .

Połączenia

Właściwości connectionStringSetting/connection i leaseConnectionStringSetting/leaseConnection są odwołaniami do konfiguracji środowiska, która określa sposób łączenia aplikacji z usługą Azure Cosmos DB. Mogą one określać:

Nazwa ustawienia aplikacji zawierającego parametry połączenia
Nazwa udostępnionego prefiksu dla wielu ustawień aplikacji, definiująca połączenie oparte na tożsamościach. Ta opcja jest dostępna tylko dla connection wersji i leaseConnection z wersji 4.x lub nowszej rozszerzenia.

Jeśli skonfigurowana wartość jest dokładnie zgodna z pojedynczym ustawieniem i dopasowaniem prefiksu dla innych ustawień, zostanie użyte dokładne dopasowanie.

Connection string

Parametry połączenia dla konta bazy danych powinny być przechowywane w ustawieniu aplikacji z nazwą zgodną z wartością określoną przez właściwość połączenia konfiguracji powiązania.

Połączenia oparte na tożsamościach

Jeśli używasz rozszerzenia w wersji 4.x lub nowszej, zamiast używać parametry połączenia z wpisem tajnym, możesz użyć tożsamości Microsoft Entra. W tym celu należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na właściwość connection w konfiguracji wyzwalacza i powiązania.

W tym trybie rozszerzenie wymaga następujących właściwości:

Właściwości	Szablon zmiennej środowiskowej	opis	Przykładowa wartość
Punkt końcowy konta	`<CONNECTION_NAME_PREFIX>__accountEndpoint`	Identyfikator URI punktu końcowego konta usługi Azure Cosmos DB.	<https:// database_account_name.documents.azure.com:443/>

Aby dostosować połączenie, można ustawić dodatkowe właściwości. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

W przypadku hostowania w usłudze Azure Functions połączenia oparte na tożsamościach używają tożsamości zarządzanej. Tożsamość przypisana przez system jest używana domyślnie, chociaż tożsamości przypisanej przez użytkownika można określić za credential pomocą właściwości i clientID . Należy pamiętać, że konfigurowanie tożsamości przypisanej przez użytkownika przy użyciu identyfikatora zasobu nie jest obsługiwane. W przypadku uruchamiania w innych kontekstach, takich jak programowanie lokalne, tożsamość dewelopera jest używana, chociaż można to dostosować. Zobacz Programowanie lokalne z połączeniami opartymi na tożsamościach.

Udzielanie uprawnień tożsamości

Niezależnie od używanej tożsamości musi mieć uprawnienia do wykonywania zamierzonych akcji. W przypadku większości usług platformy Azure oznacza to, że musisz przypisać rolę w kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych ról, które zapewniają te uprawnienia.

Ważne

Niektóre uprawnienia mogą być uwidocznione przez usługę docelową, które nie są niezbędne dla wszystkich kontekstów. Jeśli to możliwe, przestrzegaj zasady najniższych uprawnień, udzielając tożsamości tylko wymaganych uprawnień. Jeśli na przykład aplikacja musi mieć możliwość odczytu tylko ze źródła danych, użyj roli, która ma uprawnienia tylko do odczytu. Niewłaściwe byłoby przypisanie roli, która umożliwia również zapisywanie w tej usłudze, ponieważ byłoby to nadmierne uprawnienie do operacji odczytu. Podobnie należy upewnić się, że przypisanie roli jest ograniczone tylko do zasobów, które należy odczytać.

Usługa Cosmos DB nie używa kontroli dostępu opartej na rolach platformy Azure na potrzeby operacji na danych. Zamiast tego używa wbudowanego systemu RBAC usługi Cosmos DB, który jest oparty na podobnych pojęciach. Należy utworzyć przypisanie roli, które zapewnia dostęp do konta bazy danych w czasie wykonywania. Role zarządzania RBAC platformy Azure, takie jak Właściciel , nie są wystarczające. W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z rozszerzenia usługi Azure Cosmos DB w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania	Przykładowe wbudowane role¹
Wyzwalacz²	Współautor danych wbudowanych w usłudze Cosmos DB
Powiązanie wejściowe	Wbudowany czytnik danych usługi Cosmos DB
Powiązanie wyjściowe	Współautor danych wbudowanych w usłudze Cosmos DB

¹ Tych ról nie można używać w przypisaniu roli RBAC platformy Azure. Aby uzyskać szczegółowe informacje na temat przypisywania tych ról, zobacz wbudowaną dokumentację systemu RBAC usługi Cosmos DB.

² W przypadku korzystania z tożsamości usługa Cosmos DB traktuje tworzenie kontenera jako operację zarządzania. Nie jest ona dostępna jako operacja płaszczyzny danych dla wyzwalacza. Przed skonfigurowaniem funkcji należy upewnić się, że utworzysz kontenery wymagane przez wyzwalacz (w tym kontener dzierżawy).

Wyjątki i kody powrotne

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

Powiązanie wyjściowe usługi Azure Cosmos DB dla usługi Azure Functions w wersji 2.x lub nowszej

Przykład

Wyzwalacz kolejki, zapis jednego dokumentu

Wyzwalacz kolejki, zapis jednego dokumentu (rozszerzenie w wersji 4)

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

Wyzwalacz kolejki, zapisywanie komunikatu w bazie danych za pośrednictwem wartości zwracanej

Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pomocą wartości zwracanej

Wyzwalacz HTTP, zapisz jeden dokument w bazie danych za pośrednictwem elementu OutputBinding

Wyzwalacz HTTP, zapisywanie wielu dokumentów w bazie danych za pomocą funkcji OutputBinding

Atrybuty

Dekoratory

Adnotacje

Konfigurowanie

Użycie

Połączenia

Connection string

Połączenia oparte na tożsamościach

Udzielanie uprawnień tożsamości

Wyjątki i kody powrotne

Następne kroki

Dodatkowe zasoby