Pengikatan output Azure Cosmos DB untuk Azure Functions 2.x dan yang lebih tinggi

Artikel
10/05/2023

Pengikatan output Azure Cosmos DB memungkinkan Anda menulis dokumen baru ke database Azure Cosmos DB menggunakan SQL API.

Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

Fungsi C# dapat dibuat dengan menggunakan salah satu mode C# berikut:

Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi LTS dan non-LTS .NET dan .NET Framework. Ekstensi untuk fungsi proses pekerja yang terisolasi menggunakan Microsoft.Azure.Functions.Worker.Extensions.* namespace layanan.
Model dalam proses: Fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions. Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Ekstensi untuk fungsi dalam proses menggunakan Microsoft.Azure.WebJobs.Extensions.* namespace layanan.

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

Contoh

Kecuali dinyatakan lain, contoh pada artikel ini menargetkan versi 3.x dari ekstensi Azure Cosmos DB. Untuk digunakan dengan ekstensi versi 4.x, Anda perlu mengganti string collection dalam properti dan nama atribut dengan container dan connection_string_setting dengan connection.

Model pekerja terisolasi
Model dalam proses

Kode berikut menjelaskan jenis MyDocument:

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

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Dalam contoh berikut, jenis pengembalian adalah IReadOnlyList<T>, yang merupakan daftar dokumen yang dimodifikasi dari parameter ikatan pemicu:

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

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

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

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

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

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Bagian ini berisi contoh-contoh berikut:

Pemicu antrean, tulis satu dokumen
Pemicu antrean, tulis satu dokumen (ekstensi v4)
Pemicu antrean, tulis dokumen menggunakan IAsyncCollector

Contohnya mengacu pada jenis ToDoItem sederhana:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Pemicu antrean, tulis satu dokumen

Contoh berikut memperlihatkan fungsi C# yang menambahkan dokumen ke database, menggunakan data yang disediakan dalam pesan dari penyimpanan Antrean.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

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

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

Pemicu antrean, tulis satu dokumen (ekstensi v4)

Aplikasi yang menggunakan ekstensi Azure Cosmos DB versi 4.x atau yang lebih tinggi akan memiliki properti atribut yang berbeda yang ditunjukkan di bawah ini. Contoh berikut memperlihatkan fungsi C# yang menambahkan dokumen ke database, menggunakan data yang disediakan dalam pesan dari penyimpanan Antrean.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

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

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

Pemicu antrean, tulis dokumen menggunakan IAsyncCollector

Contoh berikut memperlihatkan fungsi C# yang menambahkan kumpulan dokumen ke database, menggunakan data yang disediakan dalam JSON pesan antrean.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

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

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

Pemicu antrean, simpan pesan ke database melalui nilai yang dikembalikan
Pemicu HTTP, simpan satu dokumen ke database melalui nilai yang dikembalikan
Pemicu HTTP, simpan satu dokumen ke database melalui OutputBinding
Pemicu HTTP, simpan beberapa dokumen ke database melalui OutputBinding

Pemicu antrean, simpan pesan ke database melalui nilai yang dikembalikan

Contoh berikut memperlihatkan fungsi Java yang menambahkan dokumen ke database dengan data dari pesan di penyimpanan Antrean.

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

Pemicu HTTP, simpan satu dokumen ke database melalui nilai yang dikembalikan

Contoh berikut ini menunjukkan fungsi Java yang tanda tangannya dianotasikan dengan @CosmosDBOutput dan memiliki nilai hasil berjenis String. Dokumen JSON yang dikembalikan oleh fungsi akan secara otomatis ditulis ke koleksi Azure Cosmos DB yang sesuai.

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

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

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

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

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

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

        return jsonDocument;
    }

Pemicu HTTP, simpan satu dokumen ke database melalui OutputBinding

Contoh berikut menunjukkan fungsi Java yang menulis dokumen ke Azure Cosmos DB melalui OutputBinding<T> parameter output. Dalam contoh ini, parameter outputItem perlu dianotasikan dengan @CosmosDBOutput, bukan tanda tangan fungsi. Menggunakan OutputBinding<T> memungkinkan fungsi Anda memanfaatkan pengikatan untuk menulis dokumen ke Azure Cosmos DB sambil juga memungkinkan mengembalikan nilai yang berbeda ke pemanggil fungsi, seperti dokumen JSON atau XML.

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

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

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

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

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

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

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

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

Pemicu HTTP, simpan beberapa dokumen ke database melalui OutputBinding

Contoh berikut menunjukkan fungsi Java yang menulis beberapa dokumen ke Azure Cosmos DB melalui OutputBinding<T> parameter output. Dalam contoh ini, parameter outputItem dianotasikan dengan @CosmosDBOutput, bukan tanda tangan fungsi. Parameter output, outputItem, memiliki daftar objek ToDoItem sebagai jenis parameter templatnya. Menggunakan OutputBinding<T> memungkinkan fungsi Anda memanfaatkan pengikatan untuk menulis dokumen ke Azure Cosmos DB sambil juga memungkinkan mengembalikan nilai yang berbeda ke pemanggil fungsi, seperti dokumen JSON atau XML.

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

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

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

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

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

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

          items.add(item);
        }

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

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

Di pustaka runtime fungsi Java, gunakan @CosmosDBOutput anotasi pada parameter yang akan ditulis ke Azure Cosmos DB. Jenis parameter anotasi harus OutputBinding<T>, di mana T merupakan jenis Java asli atau POJO.

Model v4
Model v3

Contoh berikut menunjukkan fungsi TypeScript yang dipicu antrean penyimpanan untuk antrean yang menerima JSON dalam format berikut:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Fungsi ini membuat dokumen Azure Cosmos DB dalam format berikut untuk setiap baris:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Berikut adalah kode TypeScript:

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

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

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

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

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

Untuk menghasilkan beberapa dokumen, kembalikan array alih-alih satu objek. Contohnya:

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

Model v4
Model v3

Contoh berikut menunjukkan antrean penyimpanan yang memicu fungsi JavaScript untuk antrean yang menerima JSON dalam format berikut:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Fungsi ini membuat dokumen Azure Cosmos DB dalam format berikut untuk setiap baris:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Berikut kode JavaScript:

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

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

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

Untuk menghasilkan beberapa dokumen, kembalikan array alih-alih satu objek. Contohnya:

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

Contoh berikut ini menunjukkan pengikatan output Azure Cosmos DB dalam file function.json dan fungsi JavaScript yang menggunakan pengikatan. Fungsi ini menggunakan pengikatan input antrean untuk antrean yang menerima JSON dalam format berikut:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Fungsi ini membuat dokumen Azure Cosmos DB dalam format berikut untuk setiap baris:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Berikut data pengikatan dalam file function.json:

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

Bagian konfigurasi menjelaskan properti ini.

Berikut kode JavaScript:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Untuk menyisipkan secara massal, bentuk objek terlebih dahulu, lalu jalankan fungsi pembuatan string. Berikut kode JavaScript:

    module.exports = async function (context) {

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

Contoh berikut menunjukkan cara menulis data ke Azure Cosmos DB menggunakan pengikatan output. Pengikatan dideklarasikan dalam file konfigurasi fungsi (functions.json), dan mengambil data dari pesan antrean dan menulis ke dokumen Azure Cosmos DB.

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

Dalam file run.ps1, objek yang dikembalikan dari fungsi dipetakan ke objek EmployeeDocument, yang disimpan dalam database.

param($QueueItem, $TriggerMetadata) 

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

Contoh berikut menunjukkan cara menulis dokumen ke database Azure Cosmos DB sebagai output fungsi. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

import logging
import azure.functions as func

app = func.FunctionApp()

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

Definisi pengikatan ditentukan dalam function.json, tempat jenis diatur ke cosmosDB.

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

Untuk menulis ke database, berikan objek dokumen ke metode set parameter database.

import azure.functions as func

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

    request_body = req.get_body()

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

    return 'OK'

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk menentukan fungsi. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.

Properti atribut	Deskripsi
Koneksi	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
DatabaseName	Nama database Azure Cosmos DB dengan koleksi sedang dalam pemantauan.
ContainerName	Nama kontainer yang sedang dipantau.
CreateIfNotExists	Nilai boolean untuk menunjukkan apakah kontainer dibuat saat tidak ada. Default-nya false karena kontainer baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
PartitionKey	Jika `CreateIfNotExists`-nya true, nilai tersebut menetapkan jalur kunci partisi untuk kontainer yang dibuat. Mungkin termasuk parameter pengikatan.
ContainerThroughput	Jika `CreateIfNotExists`-nya true, nilai tersebut menetapkan throughput kontainer yang dibuat.
PreferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.

Properti atribut	Deskripsi
ConnectionStringSetting	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
DatabaseName	Nama database Azure Cosmos DB dengan koleksi sedang dipantau.
CollectionName	Nama koleksi sedang dipantau.
CreateIfNotExists	Nilai boolean untuk menunjukkan apakah kumpulan dibuat saat tidak ada. Default-nya salah karena kumpulan baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
PartitionKey	Jika `CreateIfNotExists` adalah true, maka menetapkan jalur kunci partisi untuk kumpulan yang dibuat. Mungkin termasuk parameter pengikatan.
CollectionThroughput	Jika `CreateIfNotExists` adalah true, maka menetapkan throughput kumpulan yang dibuat.
PreferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.
UseMultipleWriteLocations	(Opsional) Saat diatur ke `true` bersama dengan `PreferredLocations`, mendukung penulisan multi-wilayah di layanan Azure Cosmos DB.

Properti atribut	Deskripsi
Koneksi	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
DatabaseName	Nama database Azure Cosmos DB dengan koleksi sedang dalam pemantauan.
ContainerName	Nama kontainer yang sedang dipantau.
CreateIfNotExists	Nilai boolean untuk menunjukkan apakah kontainer dibuat saat tidak ada. Default-nya false karena kontainer baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
PartitionKey	Jika `CreateIfNotExists`-nya true, nilai tersebut menetapkan jalur kunci partisi untuk kontainer yang dibuat. Mungkin termasuk parameter pengikatan.
ContainerThroughput	Jika `CreateIfNotExists`-nya true, nilai tersebut menetapkan throughput kontainer yang dibuat.
PreferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.

Properti atribut	Deskripsi
ConnectionStringSetting	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
DatabaseName	Nama database Azure Cosmos DB dengan koleksi sedang dipantau.
CollectionName	Nama koleksi sedang dipantau.
CreateIfNotExists	Nilai boolean untuk menunjukkan apakah kumpulan dibuat saat tidak ada. Default-nya salah karena kumpulan baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
PartitionKey	Jika `CreateIfNotExists` adalah true, maka menetapkan jalur kunci partisi untuk kumpulan yang dibuat. Mungkin termasuk parameter pengikatan.
CollectionThroughput	Jika `CreateIfNotExists` adalah true, maka menetapkan throughput kumpulan yang dibuat.
PreferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.
UseMultipleWriteLocations	(Opsional) Saat diatur ke `true` bersama dengan `PreferredLocations`, mendukung penulisan multi-wilayah di layanan Azure Cosmos DB.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada cosmos_db_output:

Properti	Deskripsi
`arg_name`	Nama variabel yang digunakan dalam kode fungsi yang mewakili daftar dokumen dengan perubahan.
`database_name`	Nama database Azure Cosmos DB dengan koleksi sedang dipantau.
`collection_name`	Nama koleksi Azure Cosmos DB yang sedang dipantau.
`create_if_not_exists`	Nilai Boolean yang menunjukkan apakah database dan koleksi harus dibuat jika tidak ada.
`connection_string_setting`	String koneksi Azure Cosmos DB yang sedang dipantau.

Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .

Anotasi

Dari pustaka runtime bahasa umum fungsi Java, gunakan anotasi @CosmosDBOutput pada parameter yang menulis ke Azure Cosmos DB. Anotasi mendukung properti berikut ini:

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

Model v4
Model v3

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke output.cosmosDB() metode . Properti type, direction, dan name tidak berlaku untuk model v4.

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json, di mana properti berbeda menurut versi ekstensinya:

Ekstensi 4.x+
Functions 2.x+

Properti function.json	Deskripsi
koneksi	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
databaseName	Nama database Azure Cosmos DB dengan koleksi sedang dalam pemantauan.
containerName	Nama kontainer yang sedang dipantau.
createIfNotExists	Nilai boolean untuk menunjukkan apakah kontainer dibuat saat tidak ada. Default-nya false karena kontainer baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
partitionKey	Jika `createIfNotExists`-nya true, nilai tersebut menetapkan jalur kunci partisi untuk kontainer yang dibuat. Mungkin termasuk parameter pengikatan.
containerThroughput	Jika `createIfNotExists`-nya true, nilai tersebut menetapkan throughput kontainer yang dibuat.
preferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.

Properti function.json	Deskripsi
connectionStringSetting	Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan.
databaseName	Nama database Azure Cosmos DB dengan koleksi sedang dipantau.
collectionName	Nama koleksi sedang dipantau.
createIfNotExists	Nilai boolean untuk menunjukkan apakah kumpulan dibuat saat tidak ada. Default-nya salah karena kumpulan baru dibuat dengan throughput yang dipesan, yang memiliki implikasi biaya. Untuk informasi lebih lanjut, lihat halaman harga.
partitionKey	Jika `createIfNotExists` adalah true, maka menetapkan jalur kunci partisi untuk kumpulan yang dibuat. Mungkin termasuk parameter pengikatan.
collectionThroughput	Jika `createIfNotExists` adalah true, maka menetapkan throughput kumpulan yang dibuat.
preferredLocations	(Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,`East US,South Central US,North Europe`.
useMultipleWriteLocations	(Opsional) Saat diatur ke `true` bersama dengan `preferredLocations`, mendukung penulisan multi-wilayah di layanan Azure Cosmos DB.

Lihat Bagian contoh untuk contoh lengkapnya.

Penggunaan

Secara default, saat menulis ke parameter output dalam fungsi Anda, dokumen dibuat di database Anda. Anda harus menentukan ID dokumen dokumen output dengan menentukan id properti dalam objek JSON yang diteruskan ke parameter output.

Catatan

Saat Anda menentukan ID dokumen yang sudah ada, dokumen akan ditimpa oleh dokumen output baru.

Jenis parameter yang didukung oleh pengikatan output Cosmos DB tergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.

Saat Anda ingin fungsi menulis ke satu dokumen, pengikatan output Cosmos DB dapat mengikat ke jenis berikut:

Tipe	Deskripsi
Jenis yang bisa diserialisasikan JSON	Objek yang mewakili konten JSON dokumen. Fungsi mencoba menserialisasikan jenis objek CLR (POCO) lama biasa ke dalam data JSON.

Saat Anda ingin fungsi menulis ke beberapa dokumen, pengikatan output Cosmos DB dapat mengikat ke jenis berikut:

Tipe	Deskripsi
`T[]` di mana `T` adalah jenis JSON yang dapat diserialisasikan	Array yang berisi beberapa dokumen. Setiap entri mewakili satu dokumen.

Untuk skenario output lainnya, buat dan gunakan jenis dari Microsoft.Azure.Cosmos secara langsung.

Koneksi

Properti connectionStringSetting/connection dan leaseConnectionStringSetting/leaseConnection adalah referensi ke konfigurasi lingkungan yang menentukan cara aplikasi akan terhubung ke Azure Cosmos DB. Properti ini mungkin menentukan:

Nama pengaturan aplikasi yang berisi string koneksi
Nama awalan bersama untuk beberapa pengaturan aplikasi, bersama-sama menentukan koneksi berbasis identitas. Opsi ini hanya tersedia untuk versi connection dan leaseConnection dari ekstensi versi 4.x atau yang lebih tinggi.

Jika nilai yang dikonfigurasi adalah kecocokan persis untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lainnya, kecocokan persis akan digunakan.

String koneksi

String koneksi untuk akun database Anda harus disimpan dalam pengaturan aplikasi dengan nama yang cocok dengan nilai yang ditentukan oleh properti koneksi dari konfigurasi pengikatan.

Koneksi berbasis identitas

Jika Anda menggunakan ekstensi versi 4.x atau yang lebih tinggi, alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. Untuk melakukannya, Anda akan menentukan pengaturan dengan awalan umum yang dipetakan ke properti koneksi dalam pemicu dan konfigurasi pengikatan.

Dalam mode ini, ekstensi tersebut memerlukan properti berikut:

Properti	Templat variabel lingkungan	Deskripsi	Contoh nilai
Titik Akhir Akun	`<CONNECTION_NAME_PREFIX>__accountEndpoint`	URI titik akhir akun Azure Cosmos DB.	https://<database_account_name>.documents.azure.com:443/

Properti tambahan dapat diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential dan clientID properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan oleh pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.

Memberikan izin kepada identitas

Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.

Cosmos DB tidak menggunakan Azure RBAC untuk operasi data. Sebaliknya, ia menggunakan sistem RBAC bawaan Cosmos DB yang dibangun berdasarkan konsep serupa. Anda perlu membuat penetapan peran yang menyediakan akses ke akun database Anda saat runtime. Peran Azure RBAC Management seperti Pemilik tidak cukup. Tabel berikut ini memperlihatkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Azure Cosmos DB dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

Jenis pengikatan	Contoh peran bawaan¹
Pemicu²	Kontributor Data Bawaan Cosmos DB
Pengikatan masukan	Pembaca Data Bawaan Cosmos DB
Pengikatan output	Kontributor Data Bawaan Cosmos DB

¹ Peran ini tidak dapat digunakan dalam penetapan peran Azure RBAC. Lihat dokumentasi sistem RBAC bawaan Cosmos DB untuk detail tentang cara menetapkan peran ini.

² Saat menggunakan identitas, Cosmos DB memperlakukan pembuatan kontainer sebagai operasi manajemen. Ini tidak tersedia sebagai operasi data-plane untuk pemicu. Anda harus memastikan bahwa Anda membuat kontainer yang diperlukan oleh pemicu (termasuk kontainer sewa) sebelum menyiapkan fungsi Anda.

Kode pengecualian dan pengembalian

Pengikatan	Referensi
Azure Cosmos DB	Daftar Kode Status HTTP untuk Azure Cosmos DB

Share via

Pengikatan output Azure Cosmos DB untuk Azure Functions 2.x dan yang lebih tinggi

Contoh

Pemicu antrean, tulis satu dokumen

Pemicu antrean, tulis satu dokumen (ekstensi v4)

Pemicu antrean, tulis dokumen menggunakan IAsyncCollector

Pemicu antrean, simpan pesan ke database melalui nilai yang dikembalikan

Pemicu HTTP, simpan satu dokumen ke database melalui nilai yang dikembalikan

Pemicu HTTP, simpan satu dokumen ke database melalui OutputBinding

Pemicu HTTP, simpan beberapa dokumen ke database melalui OutputBinding

Atribut

Dekorator

Anotasi

Konfigurasi

Penggunaan

Koneksi

String koneksi

Koneksi berbasis identitas

Memberikan izin kepada identitas

Kode pengecualian dan pengembalian

Langkah berikutnya

Sumber Daya Tambahan: