Powiązanie danych wejściowych usługi Azure Cosmos DB dla usługi Azure Functions w wersji 2.x lub nowszej

  • Artykuł

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

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

Uwaga

Gdy kolekcja jest partycjonowana, operacje wyszukiwania muszą również określać wartość klucza partycji.

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.

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.

Przykład

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

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.

Ta sekcja zawiera przykłady, które wymagają rozszerzenia usługi Azure Cosmos DB w wersji 3.x i rozszerzenia usługi Azure Storage w wersji 5.x. Jeśli jeszcze nie istnieje w aplikacji funkcji, dodaj odwołanie do następujących pakietów NuGet:

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

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

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

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie przedstawiono funkcję, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez komunikat JSON w kolejce magazynu. Wyzwalacz kolejki analizuje kod JSON w obiekcie typu ToDoItemLookup, który zawiera wartość identyfikatora i klucza partycji do pobrania. Ten identyfikator i wartość klucza partycji są używane do zwracania ToDoItem dokumentu z określonej bazy danych i kolekcji.

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

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

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

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

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania — parametr ciągu

W poniższym przykładzie przedstawiono funkcję Języka Java, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji są używane do pobierania dokumentu z określonej bazy danych i kolekcji w formularzu Ciąg.

public class DocByIdFromQueryString {

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

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

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

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @CosmosDBInput adnotacji dotyczącej parametrów funkcji, których wartość pochodzi z usługi Azure Cosmos DB. Tej adnotacji można używać z natywnymi typami Języka Java, obiektami POJO lub wartościami dopuszczanymi wartościami null przy użyciu polecenia Optional<T>.

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania — parametr POJO

W poniższym przykładzie przedstawiono funkcję Języka Java, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa ciągu zapytania do określenia identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji służący do pobierania dokumentu z określonej bazy danych i kolekcji. Dokument jest następnie konwertowany na wystąpienie wcześniej utworzonego ToDoItem obiektu POJO i przekazywany jako argument do funkcji.

public class DocByIdFromQueryStringPojo {

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

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

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy

W poniższym przykładzie przedstawiono funkcję Języka Java, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa parametru trasy do określenia identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji są używane do pobierania dokumentu z określonej bazy danych i kolekcji, zwracając je jako Optional<String>.

public class DocByIdFromRoute {

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

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

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

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

W poniższym przykładzie przedstawiono funkcję Języka Java, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa parametru trasy do określenia identyfikatora do wyszukania. Ten identyfikator służy do pobierania dokumentu z określonej bazy danych i kolekcji, konwertowania zestawu wyników na ToDoItem[]wartość , ponieważ wiele dokumentów może zostać zwróconych, w zależności od kryteriów zapytania.

Uwaga

Jeśli musisz wykonać zapytanie według tylko identyfikatora, zaleca się użycie wyszukiwania, podobnie jak w poprzednich przykładach, ponieważ zużywa mniej jednostek żądań. Operacje odczytu punktów (GET) są wydajniejsze niż zapytania według identyfikatora.

public class DocByIdFromRouteSqlQuery {

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

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

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

Wyzwalacz HTTP, pobieranie wielu dokumentów z danych trasy przy użyciu zapytania SqlQuery

W poniższym przykładzie przedstawiono funkcję Języka Java, która pobiera wiele dokumentów. Funkcja jest wyzwalana przez żądanie HTTP, które używa parametru desc trasy do określenia ciągu do wyszukania description w polu. Termin wyszukiwania służy do pobierania kolekcji dokumentów z określonej bazy danych i kolekcji, konwertując zestaw wyników na ToDoItem[] element i przekazując go jako argument do funkcji.

public class DocsFromRouteSqlQuery {

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

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

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

Ta sekcja zawiera następujące przykłady, które odczytują pojedynczy dokument, określając wartość identyfikatora z różnych źródeł:

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie pokazano funkcję TypeScript, która odczytuje pojedynczy dokument i aktualizuje wartość tekstową dokumentu.

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

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

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

interface MyDocument {
    text: string;
}

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

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania

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

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

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

interface ToDoDocument {
    description: string;
}

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

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy

W poniższym przykładzie przedstawiono funkcję TypeScript, która pobiera pojedynczy dokument. Funkcja jest wyzwalana przez żądanie HTTP, które używa danych trasy do określenia identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji są używane do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

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

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

interface ToDoDocument {
    description: string;
}

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

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

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

Poniższy przykład przedstawia funkcję TypeScript, która 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.

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

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

interface MyDocument {}

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

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

Ta sekcja zawiera następujące przykłady, które odczytują pojedynczy dokument, określając wartość identyfikatora z różnych źródeł:

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie pokazano funkcję języka JavaScript, która odczytuje pojedynczy dokument i aktualizuje wartość tekstową dokumentu.

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

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

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

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

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 identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji są używane do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

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

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

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

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 danych trasy do określenia identyfikatora i wartości klucza partycji do wyszukania. Ten identyfikator i wartość klucza partycji są używane do pobierania ToDoItem dokumentu z określonej bazy danych i kolekcji.

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

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

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

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

W poniższym przykładzie pokazano funkcję Języka JavaScript, która 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.

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

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

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

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie pokazano, jak odczytywać i aktualizować pojedynczy dokument usługi Azure Cosmos DB. Unikatowy identyfikator dokumentu jest dostarczany za pośrednictwem wartości JSON w komunikacie kolejki.

Powiązanie wejściowe usługi Azure Cosmos DB znajduje się na liście powiązań znalezionych w pliku konfiguracji funkcji (function.json).

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

Plik run.ps1 zawiera kod programu PowerShell, który odczytuje zmiany przychodzącego dokumentu i danych wyjściowych.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania

W poniższym przykładzie pokazano, jak odczytywać i aktualizować pojedynczy dokument usługi Azure Cosmos DB z internetowego interfejsu API. Unikatowy identyfikator dokumentu jest udostępniany za pośrednictwem parametru querystring z żądania HTTP, zgodnie z definicją we właściwości powiązania "Id": "{Query.Id}" .

Powiązanie wejściowe usługi Azure Cosmos DB znajduje się na liście powiązań znalezionych w pliku konfiguracji funkcji (function.json).

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

Plik run.ps1 zawiera kod programu PowerShell, który odczytuje zmiany przychodzącego dokumentu i danych wyjściowych.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

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

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

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

} else {

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

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy

W poniższym przykładzie pokazano, jak odczytywać i aktualizować pojedynczy dokument usługi Azure Cosmos DB z internetowego interfejsu API. Unikatowy identyfikator dokumentu jest udostępniany za pośrednictwem parametru trasy. Parametr trasy jest zdefiniowany we właściwości powiązania żądania HTTP i odwołuje się do właściwości powiązania route usługi Azure Cosmos DB "Id": "{Id}" .

Powiązanie wejściowe usługi Azure Cosmos DB znajduje się na liście powiązań znalezionych w pliku konfiguracji funkcji (function.json).

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

Plik run.ps1 zawiera kod programu PowerShell, który odczytuje zmiany przychodzącego dokumentu i danych wyjściowych.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

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

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

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

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

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

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

W poniższym przykładzie pokazano, jak odczytywać wiele dokumentów usługi Azure Cosmos DB. Plik konfiguracji funkcji (function.json) definiuje właściwości powiązania, które obejmują sqlQueryelement . Instrukcja SQL podana we sqlQuery właściwości wybiera zestaw dokumentów dostarczonych do funkcji.

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

Plik run1.ps1 zawiera kod programu PowerShell, który odczytuje dokumenty przychodzące.

param($QueueItem, $Documents, $TriggerMetadata)

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

Ta sekcja zawiera następujące przykłady, które odczytują pojedynczy dokument, określając wartość identyfikatora z różnych źródeł:

Przykłady zależą od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2.

Wyzwalacz kolejki, wyszukiwanie identyfikatora w formacie JSON

W poniższym przykładzie przedstawiono powiązanie wejściowe usługi Azure Cosmos DB. Funkcja odczytuje pojedynczy dokument i aktualizuje wartość tekstową dokumentu.

import logging
import azure.functions as func

app = func.FunctionApp()

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

Wyzwalacz HTTP, wyszukiwanie identyfikatora z ciągu zapytania

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

Obecnie nie ma równoważnej próbki dla wersji 2.

Wyzwalacz HTTP, wyszukiwanie identyfikatora z danych trasy

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

Obecnie nie ma równoważnej próbki dla wersji 2.

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

W poniższym przykładzie przedstawiono funkcję języka Python powiązania wejściowego usługi Azure Cosmos DB, 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.

Obecnie nie ma równoważnej próbki dla wersji 2.

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 kontem usługi Azure Cosmos DB, którego dotyczy zapytanie. 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.
PartitionKey Określa wartość klucza partycji dla wyszukiwania. Może zawierać parametry powiązania. Jest to wymagane w przypadku odnośników w kontenerach podzielonych na partycje.
Id Identyfikator dokumentu do pobrania. Ta właściwość obsługuje wyrażenia powiązań. Nie ustawiaj Id właściwości i SqlQuery . Jeśli nie ustawisz żadnej z nich, zostanie pobrany cały kontener.
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 Id właściwości i SqlQuery . Jeśli nie ustawisz żadnej z nich, zostanie pobrany cały kontener.
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.

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

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.
connection_string_setting Parametry połączenia monitorowanej usługi Azure Cosmos DB.
partition_key Klucz partycji monitorowanego usługi Azure Cosmos DB.
id Identyfikator dokumentu do pobrania.

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 @CosmosDBInput adnotacji dotyczącej parametrów odczytywanych z usługi Azure Cosmos DB. Adnotacja obsługuje następujące właściwości:

Konfigurowanie

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

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego input.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:

właściwość function.json opis
type Musi być ustawiona wartość cosmosDB.
direction Musi być ustawiona wartość in.
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje listę dokumentów ze zmianami.
Połączenia Nazwa ustawienia aplikacji lub kontenera ustawień, który określa sposób nawiązywania połączenia z monitorowanego konta 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.
partitionKey Określa wartość klucza partycji dla wyszukiwania. Może zawierać parametry powiązania. Jest to wymagane w przypadku odnośników w kontenerach podzielonych na partycje.
id Identyfikator dokumentu do pobrania. Ta właściwość obsługuje wyrażenia powiązań. Nie ustawiaj id właściwości i sqlQuery . Jeśli nie ustawisz żadnej z nich, zostanie pobrany cały kontener.
sqlQuery 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 id właściwości i sqlQuery . Jeśli nie ustawisz żadnej z nich, zostanie pobrany cały kontener.
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.

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

Użycie

Po pomyślnym zakończeniu działania funkcji wszystkie zmiany wprowadzone w dokumencie wejściowym są automatycznie utrwalane.

Typ parametru obsługiwany przez powiązanie wejś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 przetwarzała pojedynczy dokument, powiązanie wejściowe usługi Cosmos DB może wiązać się z następującymi typami:

Type Opis
Typy serializowalne w formacie JSON Funkcje próbują wykonać deserializacji danych JSON dokumentu w zwykły typ obiektu CLR (POCO).

Jeśli chcesz, aby funkcja przetwarzała wiele dokumentów z zapytania, powiązanie wejściowe usługi Cosmos DB może wiązać się z następującymi typami:

Type Opis
IEnumerable<T>gdzie T jest typem serializowalnym JSON Wyliczenie jednostek zwróconych przez zapytanie. Każdy wpis reprezentuje jeden dokument.
CosmosClient1 Klient połączony z kontem usługi Cosmos DB.
Baza danych1 Klient połączony z bazą danych Cosmos DB.
Kontener1 Klient połączony z kontenerem usługi Cosmos DB.

1 Aby użyć tych typów, należy odwołać się do elementów Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 lub nowszych oraz typowych zależności dla powiązań typu zestawu SDK.

W bibliotece środowiska uruchomieniowego funkcji Języka Java adnotacja @CosmosDBInput uwidacznia dane usługi Azure Cosmos DB w funkcji. Tej adnotacji można używać z natywnymi typami Języka Java, obiektami POJO lub wartościami dopuszczanymi wartościami null przy użyciu polecenia Optional<T>.

Uzyskaj dostęp do dokumentu przy użyciu polecenia context.extraInputs.get().

Aktualizacje dokumentów nie są wykonywane automatycznie po zakończeniu działania funkcji. Aby zaktualizować dokumenty w funkcji, użyj powiązania wyjściowego. Zobacz przykład programu PowerShell, aby uzyskać więcej szczegółów.

Dane są udostępniane funkcji za pośrednictwem parametru DocumentList . Zmiany wprowadzone w dokumencie nie są automatycznie utrwalane.

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

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 role1
Wyzwalacz2 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

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

2 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).

Następne kroki