Associazione di input di Azure Cosmos DB per Funzioni di Azure 2.x e versioni successive

  • Articolo

L'associazione di input di Azure Cosmos DB usa l'API SQL per recuperare uno o più documenti di Azure Cosmos DB e li passa al parametro di input della funzione. L'ID documento o i parametri di query possono essere determinati in base al trigger che richiama la funzione.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

Nota

Quando la raccolta è partizionata, le operazioni di ricerca devono specificare anche il valore della chiave di partizione.

Importante

Questo articolo usa schede per supportare le versioni diverse del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

Se non diversamente specificato, gli esempi in questo articolo sono destinati alla versione 3.x dell'estensione Azure Cosmos DB. Per usare con l'estensione versione 4.x, è necessario sostituire la stringa collection nei nomi delle proprietà e degli attributi con container.

È possibile creare una funzione C# usando una delle modalità C# seguenti:

  • Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
  • Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

Questa sezione contiene esempi che richiedono la versione 3.x dell'estensione Azure Cosmos DB e la versione 5.x dell'estensione Archiviazione di Azure. Se non è già presente nell'app per le funzioni, aggiungere un riferimento ai pacchetti NuGet seguenti:

Gli esempi fanno riferimento a un tipo semplice ToDoItem:

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

Trigger della coda e ricerca dell'ID da JSON

Nell'esempio seguente viene illustrata una funzione che recupera un singolo documento. La funzione viene attivata da un messaggio JSON nella coda di archiviazione. Il trigger della coda analizza il codice JSON in un oggetto di tipo ToDoItemLookup, che contiene l'ID e il valore della chiave di partizione da recuperare. Tale ID e il valore della chiave di partizione vengono usati per restituire un ToDoItem documento dal database e dalla raccolta specificati.

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

Questa sezione contiene gli esempi seguenti:

Gli esempi fanno riferimento a un tipo semplice ToDoItem:

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 + "}";
  }
}

Trigger HTTP e ricerca dell'ID da una stringa di query - Parametro String

L'esempio seguente illustra una funzione Java che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID e il valore della chiave di partizione da cercare. L'ID e il valore della chiave di partizione vengono usati per recuperare un documento dal database e dalla raccolta specificati, sotto forma di stringa.

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

Nella libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBInput sui parametri della funzione il cui valore proviene da Azure Cosmos DB. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>.

Trigger HTTP e ricerca dell'ID da una stringa di query - Parametro POJO

L'esempio seguente illustra una funzione Java che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID e il valore della chiave di partizione da cercare. Valore di ID e chiave di partizione utilizzato per recuperare un documento dal database e dalla raccolta specificati. Il documento viene quindi convertito in un'istanza del ToDoItem POJO precedentemente creato e passato come argomento alla funzione.

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

Trigger HTTP e ricerca dell'ID dai dati della route

L'esempio seguente illustra una funzione Java che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa un parametro di route per specificare l'ID e il valore della chiave di partizione da cercare. Tale ID e il valore della chiave di partizione vengono usati per recuperare un documento dal database e dalla raccolta specificati, restituendolo come 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();
        }
    }
}

Trigger HTTP e ricerca dell'ID dai dati della route con SqlQuery

L'esempio seguente illustra una funzione Java che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa un parametro di route per specificare l'ID da cercare. Questo ID viene usato per recuperare un documento dal database e dalla raccolta specificati, convertendo il set di risultati in ToDoItem[], dato che possono essere restituiti molti documenti, a seconda dei criteri di query.

Nota

Se è necessario eseguire una query solo in base all'ID, è consigliabile usare una ricerca, come gli esempi precedenti, perché utilizzerà meno unità richiesta. Le operazioni di lettura del punto (GET) sono più efficienti rispetto alle query in base all'ID.

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

HTTP trigger e recupero di più documenti dai dati della route con SqlQuery

L'esempio seguente illustra una funzione Java che recupera più documenti. La funzione viene attivata da una richiesta HTTP che usa un parametro desc di route per specificare la stringa da cercare nel description campo. Il termine di ricerca viene usato per recuperare una raccolta di documenti dal database e dalla raccolta specificati, convertendo il set di risultati in ToDoItem[] e passandolo come argomento alla funzione.

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

Questa sezione contiene gli esempi seguenti per leggere un singolo documento specificando un valore di ID da varie origini:

Trigger della coda e ricerca dell'ID da JSON

Nell'esempio seguente viene illustrata una funzione TypeScript che legge un singolo documento e aggiorna il valore di testo del documento.

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

Trigger HTTP e ricerca dell'ID da una stringa di query

Nell'esempio seguente viene illustrata una funzione TypeScript che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

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

Trigger HTTP e ricerca dell'ID dai dati della route

Nell'esempio seguente viene illustrata una funzione TypeScript che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa i dati della route per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

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

Trigger della coda e recupero di più documenti con SqlQuery

Nell'esempio seguente viene illustrata una funzione TypeScript che recupera più documenti specificati da una query SQL, usando un trigger di coda per personalizzare i parametri di query.

Il trigger di coda fornisce un parametro departmentId. Un messaggio nella coda di { "departmentId" : "Finance" } restituirà tutti i record per il reparto finanziario.

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

Questa sezione contiene gli esempi seguenti per leggere un singolo documento specificando un valore di ID da varie origini:

Trigger della coda e ricerca dell'ID da JSON

L'esempio seguente mostra una funzione JavaScript che legge un singolo documento e aggiorna il valore di testo del documento.

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

Trigger HTTP e ricerca dell'ID da una stringa di query

L'esempio seguente illustra una funzione JavaScript che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

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

Trigger HTTP e ricerca dell'ID dai dati della route

L'esempio seguente illustra una funzione JavaScript che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa i dati della route per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

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

Trigger della coda e recupero di più documenti con SqlQuery

L'esempio seguente illustra una funzione JavaScript che recupera più documenti specificati da una query SQL, usando un trigger della coda per personalizzare i parametri di query.

Il trigger di coda fornisce un parametro departmentId. Un messaggio nella coda di { "departmentId" : "Finance" } restituirà tutti i record per il reparto finanziario.

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

Trigger della coda e ricerca dell'ID da JSON

L'esempio seguente illustra come leggere e aggiornare un singolo documento di Azure Cosmos DB. L'identificatore univoco del documento viene fornito tramite il valore JSON in un messaggio della coda.

L'associazione di input di Azure Cosmos DB è elencata per prima nell'elenco delle associazioni disponibili nel file di configurazione della funzione (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"
}

Il file run.ps1 include il codice di PowerShell che legge il documento in ingresso e restituisce le modifiche.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Trigger HTTP e ricerca dell'ID da una stringa di query

L'esempio seguente illustra come leggere e aggiornare un singolo documento di Azure Cosmos DB da un'API Web. L'identificatore univoco del documento viene fornito tramite un parametro querystring della richiesta HTTP, come definito nella proprietà dell'associazione "Id": "{Query.Id}" .

L'associazione di input di Azure Cosmos DB è elencata per prima nell'elenco delle associazioni disponibili nel file di configurazione della funzione (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 
}

Il file run.ps1 include il codice di PowerShell che legge il documento in ingresso e restituisce le modifiche.

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

Trigger HTTP e ricerca dell'ID dai dati della route

L'esempio seguente illustra come leggere e aggiornare un singolo documento di Azure Cosmos DB da un'API Web. L'identificatore univoco del documento viene fornito tramite un parametro di route. Il parametro di route viene definito nella proprietà dell'associazione di route richieste HTTP e viene fatto riferimento nella proprietà di associazione di Azure Cosmos DB "Id": "{Id}" .

L'associazione di input di Azure Cosmos DB è elencata per prima nell'elenco delle associazioni disponibili nel file di configurazione della funzione (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 
}

Il file run.ps1 include il codice di PowerShell che legge il documento in ingresso e restituisce le modifiche.

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

Trigger della coda e recupero di più documenti con SqlQuery

L'esempio seguente illustra come leggere più documenti di Azure Cosmos DB. Il file di configurazione della funzione (function.json) definisce le proprietà di associazione, che includono .sqlQuery L'istruzione SQL fornita alla sqlQuery proprietà seleziona il set di documenti forniti alla funzione.

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

Il file run1.ps1 contiene il codice di PowerShell che legge i documenti in ingresso.

param($QueueItem, $Documents, $TriggerMetadata)

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

Questa sezione contiene gli esempi seguenti per leggere un singolo documento specificando un valore di ID da varie origini:

Gli esempi dipendono dal fatto che si usi il modello di programmazione Python v1 o v2.

Trigger della coda e ricerca dell'ID da JSON

L'esempio seguente illustra un'associazione di input di Azure Cosmos DB. La funzione legge un singolo documento e aggiorna il relativo valore di testo.

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

Trigger HTTP e ricerca dell'ID da una stringa di query

Nell'esempio seguente viene illustrata una funzione che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

Nessun esempio equivalente per v2 al momento.

Trigger HTTP e ricerca dell'ID dai dati della route

Nell'esempio seguente viene illustrata una funzione che recupera un singolo documento. La funzione viene attivata da una richiesta HTTP che usa i dati della route per specificare l'ID e il valore della chiave di partizione da cercare. Questo ID e il valore della chiave di partizione sono usati per recuperare un documento ToDoItem dal database e dalla raccolta specificati.

Nessun esempio equivalente per v2 al momento.

Trigger della coda e recupero di più documenti con SqlQuery

L'esempio seguente illustra una funzione python di associazione di input di Azure Cosmos DB che usa l'associazione. La funzione recupera più documenti specificati da una query SQL mediante un trigger di coda per personalizzare i parametri di query.

Il trigger di coda fornisce un parametro departmentId. Un messaggio nella coda di { "departmentId" : "Finance" } restituirà tutti i record per il reparto finanziario.

Nessun esempio equivalente per v2 al momento.

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano attributi per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Proprietà dell'attributo Descrizione
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB sottoposto a query. Per altre informazioni, vedere Connections.
DatabaseName Il nome del database di Azure Cosmos DB con il contenitore monitorato.
ContainerName Nome del contenitore monitorato.
PartitionKey Specifica il valore della chiave di partizione per la ricerca. Può includere i parametri di associazione. È necessario per le ricerche nei contenitori partizionati.
Id ID del documento da recuperare. Questa proprietà supporta le espressioni di associazione. Non impostare entrambe le proprietà Id e SqlQuery. Se non si imposta una delle due proprietà, verrà recuperato l'intero contenitore.
SqlQuery Query SQL di Azure Cosmos DB usata per recuperare più documenti. La proprietà supporta le associazioni del runtime, come nell'esempio seguente: SELECT * FROM c where c.departmentId = {departmentId}. Non impostare entrambe le proprietà Id e SqlQuery. Se non si imposta una delle due proprietà, verrà recuperato l'intero contenitore.
PreferredLocations (Facoltativo) Definisce le posizioni preferite (aree) per gli account di database con replica geografica nel servizio Azure Cosmos DB. I valori devono essere delimitati da virgole. Ad esempio: East US,South Central US,North Europe.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Le funzioni Python v2 vengono definite usando l'elemento cosmos_db_input Decorator, che supporta queste proprietà, a seconda della versione dell'estensione:

Proprietà Descrizione
arg_name Il nome della variabile usato nel codice funzione che rappresenta l'elenco di documenti con le modifiche.
database_name Il nome del database di Azure Cosmos DB con la raccolta monitorata.
container_name Nome della raccolta di Azure Cosmos DB monitorata.
connection Il stringa di connessione di Azure Cosmos DB monitorato.
partition_key Chiave di partizione di Azure Cosmos DB monitorata.
id ID del documento da recuperare.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

Dalla libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBInput sui parametri letti da Azure Cosmos DB. L'annotazione supporta le proprietà seguenti:

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al input.cosmosDB() metodo . Le typeproprietà , directione name non si applicano al modello v4.

La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file function.json , in cui le proprietà differiscono per la versione dell'estensione:

Proprietà di function.json Descrizione
type Deve essere impostato su cosmosDB.
direction Deve essere impostato su in.
name Il nome della variabile usato nel codice funzione che rappresenta l'elenco di documenti con le modifiche.
connection Nome di un'impostazione o di un contenitore di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB monitorato. Per altre informazioni, vedere Connections.
databaseName Il nome del database di Azure Cosmos DB con il contenitore monitorato.
containerName Nome del contenitore monitorato.
partitionKey Specifica il valore della chiave di partizione per la ricerca. Può includere i parametri di associazione. È necessario per le ricerche nei contenitori partizionati.
id ID del documento da recuperare. Questa proprietà supporta le espressioni di associazione. Non impostare entrambe le proprietà id e sqlQuery. Se non si imposta una delle due proprietà, verrà recuperato l'intero contenitore.
sqlQuery Query SQL di Azure Cosmos DB usata per recuperare più documenti. La proprietà supporta le associazioni del runtime, come nell'esempio seguente: SELECT * FROM c where c.departmentId = {departmentId}. Non impostare entrambe le proprietà id e sqlQuery. Se non si imposta una delle due proprietà, verrà recuperato l'intero contenitore.
preferredLocations (Facoltativo) Definisce le posizioni preferite (aree) per gli account di database con replica geografica nel servizio Azure Cosmos DB. I valori devono essere delimitati da virgole. Ad esempio: East US,South Central US,North Europe.

Per esempi completi, vedere la sezione di esempio.

Utilizzo

Quando la funzione viene chiusa correttamente, tutte le modifiche apportate al documento di input vengono salvate automaticamente in modo permanente.

Il tipo di parametro supportato dall'associazione di input di Cosmos DB dipende dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Quando si vuole che la funzione elabori un singolo documento, l'associazione di input di Cosmos DB può essere associata ai tipi seguenti:

Tipo Descrizione
Tipi serializzabili JSON Funzioni tenta di deserializzare i dati JSON del documento in un tipo POCO (Plain-Old CLR Object).

Quando si vuole che la funzione elabori più documenti da una query, l'associazione di input di Cosmos DB può essere associata ai tipi seguenti:

Tipo Descrizione
IEnumerable<T>dove T è un tipo serializzabile JSON Enumerazione delle entità restituite dalla query. Ogni voce rappresenta un documento.
CosmosClient1 Un client connesso all'account Cosmos DB.
Database1 Un client connesso al database Cosmos DB.
Contenitore1 Un client connesso al contenitore Cosmos DB.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

Dalla libreria di runtime delle funzioni Java, l'annotazione @CosmosDBInput espone i dati di Azure Cosmos DB alla funzione. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>.

Accedere al documento usando context.extraInputs.get().

Gli aggiornamenti ai documenti non vengono eseguiti automaticamente al termine della funzione. Per aggiornare i documenti in una funzione, usare un'associazione di output. Per altri dettagli, vedere l'esempio di PowerShell.

I dati sono resi disponibili per la funzione tramite un DocumentList parametro . Le modifiche apportate al documento non vengono rese persistenti automaticamente.

Connessioni

Le connectionStringSetting/connection proprietà e leaseConnectionStringSetting/leaseConnection sono riferimenti alla configurazione dell'ambiente che specifica come l'app deve connettersi ad Azure Cosmos DB. Possono specificare:

Se il valore configurato è sia una corrispondenza esatta per una singola impostazione che una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Il stringa di connessione per l'account di database deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla proprietà di connessione della configurazione dell'associazione.

Connessioni basate su identità

Se si usa la versione 4.x o successiva dell'estensione, invece di usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità Microsoft Entra. A tale scopo, è necessario definire le impostazioni in un prefisso comune che esegue il mapping alla proprietà connection nella configurazione del trigger e dell'associazione.

In questa modalità, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
Endpoint dell'account <CONNECTION_NAME_PREFIX>__accountEndpoint URI dell'endpoint dell'account Azure Cosmos DB. <https:// database_account_name.documents.azure.com:443/>

È possibile impostare proprietà aggiuntive per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

Cosmos DB non usa il controllo degli accessi in base al ruolo di Azure per le operazioni dei dati. Usa invece un sistema RBAC predefinito di Cosmos DB basato su concetti simili. Sarà necessario creare un'assegnazione di ruolo che fornisca l'accesso all'account di database in fase di esecuzione. I ruoli di gestione degli accessi in base al ruolo di Azure, ad esempio Proprietario, non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione Azure Cosmos DB in condizioni di normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio1
Trigger2 Collaboratore dati predefinito di Cosmos DB
Associazione di input Lettore dati predefinito di Cosmos DB
Associazione di output Collaboratore dati predefinito di Cosmos DB

1 Questi ruoli non possono essere usati in un'assegnazione di ruolo di controllo degli accessi in base al ruolo di Azure. Per informazioni dettagliate su come assegnare questi ruoli, vedere la documentazione del sistema RBAC predefinito di Cosmos DB.

2 Quando si usa l'identità, Cosmos DB considera la creazione del contenitore come operazione di gestione. Non è disponibile come operazione del piano dati per il trigger. È necessario assicurarsi di creare i contenitori necessari per il trigger (incluso il contenitore di lease) prima di configurare la funzione.

Passaggi successivi