Azure Cosmos DB bemeneti kötés az Azure Functions 2.x és újabb verzióihoz

Az Azure Cosmos DB bemeneti adatkötése az SQL API-t használja egy vagy több Azure Cosmos DB-dokumentum lekérésére, majd átadja ezeket a függvény bemeneti paraméterének. A dokumentumazonosítót vagy lekérdezési paramétereket a függvényt meghívó eseményindító alapján alapján lehet meghatározni.

A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.

Megjegyzés:

A gyűjtemény particionálásakor a keresési műveleteknek meg kell adniuk a partíciókulcs értékét is.

Fontos

Ez a cikk lapokkal támogatja a Node.js programozási modell több verzióját. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további részletekért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.

Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.

A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.

Ez a cikk mindkét programozási modellt támogatja.

Példa

Ha másként nem jelezzük, a cikkben szereplő példák az Azure Cosmos DB-bővítmény 3.x-es verzióját célják. A 4.x-es verziójú bővítményhez a tulajdonság- és attribútumnevek sztringje collection helyett a következőt containerkell használnia: .

A C#-függvények a következő C#-módok egyikével hozhatók létre:

  • Izolált feldolgozómodell: Lefordított C# függvény, amely a futtatókörnyezettől elkülönített feldolgozói folyamatban fut. Izolált feldolgozói folyamat szükséges az LTS- és nem LTS-verziókon futó C#-függvények támogatásához .NET és .NET-keretrendszer. Az izolált feldolgozói folyamatfüggvények bővítményei névtereket használnak Microsoft.Azure.Functions.Worker.Extensions.* .
  • Folyamaton belüli modell: Lefordított C# függvény, amely ugyanabban a folyamatban fut, mint a Functions-futtatókörnyezet. A modell egy változatában a Functions C#-szkriptekkel futtatható, amely elsősorban a C#-portál szerkesztéséhez támogatott. A folyamaton belüli függvények bővítményei névtereket használnak Microsoft.Azure.WebJobs.Extensions.* .

Ez a szakasz olyan példákat tartalmaz, amelyekhez az Azure Cosmos DB-bővítmény 3.x-es verziója és az Azure Storage-bővítmény 5.x-es verziója szükséges. Ha még nincs jelen a függvényalkalmazásban, adjon hozzá hivatkozást a következő NuGet-csomagokhoz:

A példák egy egyszerű ToDoItem típusra vonatkoznak:

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

Üzenetsor-eseményindító, azonosító keresése a JSON-ból

Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy JSON-üzenet aktiválja a tárolási üzenetsorban. Az üzenetsor-eseményindító a JSON-t egy olyan típusú ToDoItemLookupobjektumba elemzi, amely tartalmazza a lekérni kívánt azonosítót és partíciókulcs-értéket. Az azonosító és a partíciókulcs értéke a megadott adatbázisból és gyűjteményből származó dokumentum visszaadására ToDoItem szolgál.

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

Ez a szakasz a következő példákat tartalmazza:

A példák egy egyszerű ToDoItem típusra vonatkoznak:

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

HTTP-eseményindító, azonosító keresése lekérdezési sztringből – Sztringparaméter

Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ez az azonosító- és partíciókulcs-érték a megadott adatbázisból és gyűjteményből származó dokumentum sztring formátumú lekérésére szolgál.

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

A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet olyan @CosmosDBInput függvényparamétereken, amelyek értéke az Azure Cosmos DB-ből származna. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>.

HTTP-eseményindító, azonosító keresése lekérdezési sztringből – POJO paraméter

Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. A dokumentumnak a megadott adatbázisból és gyűjteményből való lekéréséhez használt azonosító- és partíciókulcs-érték. A dokumentum ezután konvertálódik a ToDoItem korábban létrehozott POJO-példányra, és argumentumként továbbítja a függvénynek.

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

HTTP-eseményindító, azonosító keresése útvonaladatokból

Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparamétert használ a kereséshez szükséges azonosító és partíciókulcs értékének megadásához. Ez az azonosító- és partíciókulcs-érték egy dokumentum lekérésére szolgál a megadott adatbázisból és gyűjteményből, és visszaadja azt 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();
        }
    }
}

HTTP-eseményindító, azonosító keresése útvonaladatokból az SqlQuery használatával

Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparaméter használatával adja meg a megkeresendő azonosítót. Ez az azonosító egy dokumentum lekérésére szolgál a megadott adatbázisból és gyűjteményből, és az eredményhalmazt átalakítja egy ToDoItem[], mivel a lekérdezési feltételektől függően számos dokumentum visszaadható.

Megjegyzés:

Ha csak az azonosító alapján kell lekérdeznie, javasoljuk, hogy az előző példákhoz hasonlóan keressen fel egy pillantást, mivel kevesebb kérelemegységet fog használni. A pontolvasási műveletek (GET) hatékonyabbak, mint az azonosító szerinti lekérdezések.

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-eseményindító, több dokumentum lekérése útvonaladatokból az SqlQuery használatával

Az alábbi példa egy Java-függvényt mutat be, amely több dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparaméter desc használatával adja meg a mezőben keresni description kívánt sztringet. A keresési kifejezés dokumentumgyűjtemény lekérésére szolgál a megadott adatbázisból és gyűjteményből, átalakítja az eredményhalmazt egy ToDoItem[] értékre, és argumentumként továbbítja azt a függvénynek.

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

Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:

Üzenetsor-eseményindító, azonosító keresése a JSON-ból

Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.

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

HTTP-eseményindító, azonosító keresése lekérdezési sztringből

Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

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

HTTP-eseményindító, azonosító keresése útvonaladatokból

Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

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

Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával

Az alábbi példa egy TypeScript-függvényt mutat be, amely egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.

Az üzenetsor-eseményindító egy paramétert departmentIdbiztosít. Egy üzenetsor { "departmentId" : "Finance" } a pénzügyi részleg összes rekordját visszaadja.

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

Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:

Üzenetsor-eseményindító, azonosító keresése a JSON-ból

Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.

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

HTTP-eseményindító, azonosító keresése lekérdezési sztringből

Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

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

HTTP-eseményindító, azonosító keresése útvonaladatokból

Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

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

Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával

Az alábbi példa egy JavaScript-függvényt mutat be, amely egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.

Az üzenetsor-eseményindító egy paramétert departmentIdbiztosít. Egy üzenetsor { "departmentId" : "Finance" } a pénzügyi részleg összes rekordját visszaadja.

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

Üzenetsor-eseményindító, azonosító keresése a JSON-ból

Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot. A dokumentum egyedi azonosítója egy üzenetsor JSON-értékén keresztül van megadva.

Az Azure Cosmos DB bemeneti kötése elsőként szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.

{
  "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"
}

A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document  

HTTP-eseményindító, azonosító keresése lekérdezési sztringből

Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot egy webes API-ból. A dokumentum egyedi azonosítóját a HTTP-kérés lekérdezési paramétere "Id": "{Query.Id}" adja meg, a kötés tulajdonságában meghatározott módon.

Az Azure Cosmos DB bemeneti kötése elsőként szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.

{ 
  "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 
} 

A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.

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

HTTP-eseményindító, azonosító keresése útvonaladatokból

Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot egy webes API-ból. A dokumentum egyedi azonosítója egy útvonalparaméteren keresztül van megadva. Az útvonalparaméter a HTTP-kérelemkötés route tulajdonságában van definiálva, és az Azure Cosmos DB "Id": "{Id}" kötéstulajdonságában hivatkozik rá.

Az Azure Cosmos DB bemeneti kötése elsőként szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.

{ 
  "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 
} 

A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.

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

Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával

Az alábbi példa bemutatja, hogyan olvashat több Azure Cosmos DB-dokumentumot. A függvény konfigurációs fájlja (function.json) határozza meg a kötés tulajdonságait, amelyek tartalmazzák a sqlQuery. A tulajdonsághoz sqlQuery megadott SQL-utasítás kiválasztja a függvénynek biztosított dokumentumokat.

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

A run1.ps1 fájl rendelkezik a bejövő dokumentumokat beolvasó PowerShell-kóddal.

param($QueueItem, $Documents, $TriggerMetadata)

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

Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:

A példák attól függenek, hogy a v1 vagy v2 Python programozási modellt használja-e.

Üzenetsor-eseményindító, azonosító keresése a JSON-ból

Az alábbi példa egy Azure Cosmos DB bemeneti kötést mutat be. A függvény egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.

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

HTTP-eseményindító, azonosító keresése lekérdezési sztringből

Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

Jelenleg nincs egyenértékű minta a v2-hez.

HTTP-eseményindító, azonosító keresése útvonaladatokból

Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem a megadott adatbázisból és gyűjteményből.

Jelenleg nincs egyenértékű minta a v2-hez.

Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával

Az alábbi példa egy, a kötést használó Azure Cosmos DB bemeneti kötésű Python-függvényt mutat be. A függvény egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.

Az üzenetsor-eseményindító egy paramétert departmentIdbiztosít. Egy üzenetsor { "departmentId" : "Finance" } a pénzügyi részleg összes rekordját visszaadja.

Jelenleg nincs egyenértékű minta a v2-hez.

Attribútumok

A folyamaton belüli és az izolált feldolgozói folyamat C# kódtárai attribútumokkal határozzák meg a függvényt. A C#-szkript ehelyett egy function.json konfigurációs fájlt használ a C#-szkriptelési útmutatóban leírtak szerint.

Attribútumtulajdonság Leírás
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat a lekérdezett Azure Cosmos DB-fiókhoz. További információ: Csatlakozás.
DatabaseName Az Azure Cosmos DB-adatbázis neve a figyelt tárolóval.
ContainerName A figyelt tároló neve.
PartitionKey Megadja a keresés partíciókulcs-értékét. Tartalmazhat kötési paramétereket. A particionált tárolókban lévő keresésekhez szükséges.
Azonosító A lekérni kívánt dokumentum azonosítója. Ez a tulajdonság támogatja a kötési kifejezéseket. Ne állítsa be a tulajdonságokat és SqlQuery a Id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót.
SqlQuery Több dokumentum lekéréséhez használt Azure Cosmos DB SQL-lekérdezés. A tulajdonság támogatja a futtatókörnyezet-kötéseket, ahogyan ebben a példában is látható: SELECT * FROM c where c.departmentId = {departmentId}. Ne állítsa be a tulajdonságokat és SqlQuery a Id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót.
PreferredLocations (Nem kötelező) Meghatározza a földrajzilag replikált adatbázisfiókok előnyben részesített helyét (régióit) az Azure Cosmos DB szolgáltatásban. Az értékeket vesszővel kell elválasztani. For example, East US,South Central US,North Europe.

Dekorátorok

Csak a Python v2 programozási modellre vonatkozik.

A dekoratőrrel definiált Python v2-függvények esetében a következő tulajdonságok a cosmos_db_inputkövetkezők:

Property Leírás
arg_name A függvénykódban használt változónév, amely a módosításokat tartalmazó dokumentumok listáját jelöli.
database_name Az Azure Cosmos DB-adatbázis neve a figyelt gyűjteménysel.
collection_name A figyelt Azure Cosmos DB-gyűjtemény neve.
connection_string_setting A figyelt Azure Cosmos DB kapcsolati sztring.
partition_key A figyelt Azure Cosmos DB partíciókulcsa.
id A lekérni kívánt dokumentum azonosítója.

A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.

Jegyzetek

A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet az @CosmosDBInput Azure Cosmos DB-ből beolvasott paramétereken. A széljegyzet a következő tulajdonságokat támogatja:

Konfiguráció

Csak a Python v1 programozási modellre vonatkozik.

Az alábbi táblázat a metódusnak input.cosmosDB() átadott objektumon options beállítható tulajdonságokat ismerteti. A type, directionés name a tulajdonságok nem vonatkoznak a v4-modellre.

Az alábbi táblázat a function.json fájlban beállított kötéskonfigurációs tulajdonságokat ismerteti, ahol a tulajdonságok bővítményverziónként eltérnek:

function.json tulajdonság Leírás
type A beállításnak a cosmosDBkövetkezőnek kell lennie: .
direction A beállításnak a inkövetkezőnek kell lennie: .
név A függvénykódban használt változónév, amely a módosításokat tartalmazó dokumentumok listáját jelöli.
Kapcsolat Egy alkalmazásbeállítás vagy beállítástároló neve, amely meghatározza, hogyan csatlakozhat a figyelt Azure Cosmos DB-fiókhoz. További információ: Csatlakozás.
databaseName Az Azure Cosmos DB-adatbázis neve a figyelt tárolóval.
containerName A figyelt tároló neve.
partitionKey Megadja a keresés partíciókulcs-értékét. Tartalmazhat kötési paramétereket. A particionált tárolókban lévő keresésekhez szükséges.
id A lekérni kívánt dokumentum azonosítója. Ez a tulajdonság támogatja a kötési kifejezéseket. Ne állítsa be a tulajdonságokat és sqlQuery a id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót.
sqlQuery Több dokumentum lekéréséhez használt Azure Cosmos DB SQL-lekérdezés. A tulajdonság támogatja a futtatókörnyezet-kötéseket, ahogyan ebben a példában is látható: SELECT * FROM c where c.departmentId = {departmentId}. Ne állítsa be a tulajdonságokat és sqlQuery a id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót.
preferredLocations (Nem kötelező) Meghatározza a földrajzilag replikált adatbázisfiókok előnyben részesített helyét (régióit) az Azure Cosmos DB szolgáltatásban. Az értékeket vesszővel kell elválasztani. For example, East US,South Central US,North Europe.

A teljes példákért tekintse meg a Példa szakaszt .

Használat

Ha a függvény sikeresen kilép, a bemeneti dokumentum módosításai automatikusan megmaradnak.

A Cosmos DB bemeneti kötés által támogatott paramétertípus a Functions futtatókörnyezet verziójától, a bővítménycsomag verziójától és a használt C# módtól függ.

Ha azt szeretné, hogy a függvény egyetlen dokumentumot dolgoz fel, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:

Type Description
JSON szerializálható típusok A Functions megpróbálja deszerializálni a dokumentum JSON-adatait egy egyszerű régi CLR-objektum (POCO) típusba.

Ha azt szeretné, hogy a függvény több dokumentumot dolgoz fel egy lekérdezésből, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:

Type Description
IEnumerable<T>ahol T egy JSON szerializálható típus A lekérdezés által visszaadott entitások számbavétele. Minden bejegyzés egy dokumentumot jelöl.
CosmosClient1 A Cosmos DB-fiókhoz csatlakoztatott ügyfél.
1. adatbázis A Cosmos DB-adatbázishoz csatlakoztatott ügyfél.
1. tároló A Cosmos DB-tárolóhoz csatlakoztatott ügyfél.

1 Ezeknek a típusoknak a használatához hivatkoznia kell a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0-s vagy újabb verziójára, valamint az SDK-típuskötések gyakori függőségeire.

A Java-függvények futtatókörnyezeti kódtárában a @CosmosDBInput jegyzet az Azure Cosmos DB-adatokat teszi elérhetővé a függvény számára. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>.

A dokumentum elérése a következő használatával context.extraInputs.get(): .

Frissítések a dokumentumok nem lesznek automatikusan a függvény kilépésekor. A függvény dokumentumainak frissítéséhez használjon kimeneti kötést. További részletekért tekintse meg a PowerShell-példát .

A függvény egy paraméteren keresztül DocumentList teszi elérhetővé az adatokat. A dokumentum módosításai nem lesznek automatikusan megőrizve.

Connections

A connectionStringSetting/connection tulajdonságok a leaseConnectionStringSetting/leaseConnection környezetkonfigurációra mutató hivatkozások, amelyek meghatározzák, hogyan kell az alkalmazásnak csatlakoznia az Azure Cosmos DB-hez. A következőt határozhatják meg:

Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.

Kapcsolati sztring

Az adatbázisfiók kapcsolati sztring egy olyan alkalmazásbeállításban kell tárolni, amely a kötéskonfiguráció kapcsolattulajdonsága által megadott értéknek megfelelő névvel rendelkezik.

Identitásalapú kapcsolatok

Ha a bővítmény 4.x vagy újabb verzióját használja, ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Ehhez olyan közös előtagban kell meghatározni beállításokat, amely a trigger és a kötés konfigurációjában a kapcsolat tulajdonságra van leképezve.

Ebben a módban a bővítményhez a következő tulajdonságok szükségesek:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Fiókvégpont <CONNECTION_NAME_PREFIX>__accountEndpoint Az Azure Cosmos DB-fiók végpontjának URI-ja. <https:// database_account_name.documents.azure.com:443/>

További tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.

Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential tulajdonságokkal együtt clientID . Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.

Engedély megadása az identitáshoz

Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.

Fontos

A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.

A Cosmos DB nem használja az Azure RBAC-t adatműveletekhez. Ehelyett egy Cosmos DB beépített RBAC-rendszert használ, amely hasonló fogalmakra épül. Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít az adatbázisfiókhoz. Az Azure RBAC Management-szerepkörök, például a Tulajdonos nem elegendőek. Az alábbi táblázat azOkat a beépített szerepköröket mutatja be, amelyek az Azure Cosmos DB-bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.

Kötés típusa Példa beépített szerepkörök1
Trigger2 A Cosmos DB beépített adatszolgáltatója
Bemeneti kötés Cosmos DB beépített adatolvasó
Kimeneti kötés A Cosmos DB beépített adatszolgáltatója

1 Ezek a szerepkörök nem használhatók Azure RBAC-szerepkör-hozzárendelésben. A szerepkörök hozzárendelésével kapcsolatos részletekért tekintse meg a Cosmos DB beépített RBAC-rendszerdokumentációját .

2 Identitás használatakor a Cosmos DB felügyeleti műveletként kezeli a tároló létrehozását. Nem érhető el adatsík-műveletként az eseményindítóhoz. A függvény beállítása előtt meg kell győződnie arról, hogy az eseményindítóhoz szükséges tárolókat hozza létre (beleértve a bérlettárolót is).

További lépések