Pemicu dan pengikatan Azure Cosmos DB untuk Azure Functions 2.x dan gambaran umum yang lebih tinggi

• Versi 1
• Versi 2 dan yang lebih tinggi

Set artikel ini menjelaskan cara bekerja dengan pengikatan Azure Cosmos DB di Azure Functions 2.x dan yang lebih tinggi. Azure Functions mendukung pengikatan pemicu, input, dan output untuk Azure Cosmos DB.

Perbuatan	Jenis
Menjalankan fungsi saat dokumen Azure Cosmos DB dibuat atau dimodifikasi	Pemicu
Membaca dokumen Azure Cosmos DB	Pengikatan masukan
Menyimpan perubahan ke dokumen Azure Cosmos DB	Pengikatan output

Catatan

Referensi ini untuk Azure Functions versi 2.x dan yang lebih tinggi. Untuk informasi tentang cara menggunakan pengikatan ini di Functions 1.x, lihat Pengikatan Azure Cosmos DB untuk Azure Functions 1.x.

Pengikatan ini awalnya bernama DocumentDB. Di Azure Functions versi 2.x dan yang lebih tinggi, pemicu, pengikatan, dan paket semuanya bernama Azure Cosmos DB.

API yang didukung

Pengikatan Azure Cosmos DB hanya didukung untuk digunakan dengan Azure Cosmos DB untuk NoSQL. Dukungan untuk Azure Cosmos DB for Table disediakan dengan menggunakan pengikatan penyimpanan Tabel, dimulai dengan ekstensi 5.x. Untuk semua API Azure Cosmos DB lainnya, Anda harus mengakses database dari fungsi Anda dengan menggunakan klien statis untuk API Anda, termasuk Azure Cosmos DB untuk MongoDB, Azure Cosmos DB untuk Cassandra, dan Azure Cosmos DB untuk Apache Gremlin.

Menginstal ekstensi

Paket NuGet ekstensi yang Anda instal bergantung pada mode C# yang Anda gunakan di aplikasi fungsi Anda:

Model pekerja terisolasi

Functions dijalankan dalam proses pekerja C# yang terisolasi. Untuk mempelajari selengkapnya, lihat Panduan untuk menjalankan C# Azure Functions dalam proses pekerja yang terisolasi.

Model dalam proses

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.

Functions berjalan dalam proses yang sama dengan host Functions. Untuk mempelajari lebih lanjut, lihat Mengembangkan fungsi pustaka kelas C# dengan menggunakan Azure Functions.

Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Untuk memperbarui ekstensi pengikatan yang ada untuk aplikasi skrip C# yang berjalan di portal tanpa harus menerbitkan ulang aplikasi fungsi Anda, lihat Memperbarui ekstensi Anda.

Proses untuk menginstal ekstensi bervariasi tergantung pada versi ekstensi:

Ekstensi 4.x+

Bagian ini menjelaskan penggunaan pustaka kelas. Untuk pembuatan skrip C#, Anda harus menginstal bundel ekstensi, versi 4.x.

Versi ekstensi pengikatan Azure Cosmos DB ini memperkenalkan kemampuan untuk terhubung menggunakan identitas alih-alih rahasia. Untuk tutorial cara mengonfigurasi aplikasi fungsi Anda dengan identitas terkelola, lihat tutorial membuat aplikasi fungsi dengan koneksi berbasis identitas.

Versi ini juga mengubah jenis yang dapat Anda ikat, mengganti jenis dari SDK Microsoft.Azure.DocumentDB v2 dengan jenis yang lebih baru dari SDK Microsoft.Azure.Cosmos v3. Pelajari lebih lanjut perbedaan jenis baru ini dan cara memigrasikannya dari contoh panduan migrasi SDK, pemicu, pengikatan input,dan pengikatan output.

Versi ekstensi ini tersedia sebagai paket NuGet, versi 4.x.

Functions 2.x+

Bagian ini menjelaskan penggunaan pustaka kelas. Untuk pembuatan skrip C#, Anda harus menginstal bundel ekstensi, versi 2.x atau 3.x.

Bekerja dengan pemicu dan pengikatan mengharuskan Anda mereferensikan paket NuGet yang sesuai. Instal paket NuGet, versi 3.x.

Ekstensi 4.x+

Versi ekstensi pengikatan Azure Cosmos DB ini memperkenalkan kemampuan untuk terhubung menggunakan identitas alih-alih rahasia. Untuk tutorial cara mengonfigurasi aplikasi fungsi Anda dengan identitas terkelola, lihat tutorial membuat aplikasi fungsi dengan koneksi berbasis identitas.

Tambahkan ekstensi ke proyek Anda dengan menginstal paket NuGet, versi 4.x.

Jika Anda menulis aplikasi menggunakan F#, Anda juga harus mengonfigurasi ekstensi ini sebagai bagian dari konfigurasi startup aplikasi. Dalam panggilan ke ConfigureFunctionsWorkerDefaults() atau ConfigureFunctionsWebApplication(), tambahkan delegasi yang mengambil IFunctionsWorkerApplication parameter. Kemudian dalam isi delegasi tersebut, panggil ConfigureCosmosDBExtension() pada objek:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Functions 2.x+

Tambahkan ekstensi ke proyek Anda dengan menginstal paket NuGet, versi 3.x.

Memasang bundel

Ekstensi pengikatan Azure Cosmos DB adalah bagian dari bundel ekstensi, yang ditentukan dalam file proyek host.json Anda. Anda mungkin perlu mengubah bundel ini untuk mengubah versi pengikatan, atau jika bundel belum terinstal. Untuk mempelajari lebih lanjut, lihat bundel ekstensi.

Karena perubahan skema di Azure Cosmos DB SDK, versi 4.x dari ekstensi Azure Cosmos DB memerlukan azure-functions-java-library V3.0.0 untuk fungsi Java.

Bundel v4.x

Versi bundel ini berisi versi 4.x dari ekstensi pengikatan Azure Cosmos DB yang memperkenalkan kemampuan untuk terhubung menggunakan identitas alih-alih rahasia. Untuk tutorial cara mengonfigurasi aplikasi fungsi Anda dengan identitas terkelola, lihat tutorial membuat aplikasi fungsi dengan koneksi berbasis identitas.

Anda dapat menambahkan versi ekstensi ini dari bundel ekstensi pratinjau v4 dengan menambahkan atau mengganti kode berikut dalam file host.json Anda:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

Untuk mempelajari selengkapnya, lihat Perbarui ekstensi Anda.

Bundel v2.x dan v3.x

Anda dapat menginstal versi ekstensi ini di aplikasi fungsi dengan mendaftarkan bundel ekstensi, versi 2.x atau 3.x.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Jenis pengikatan

Jenis pengikatan yang didukung untuk .NET bergantung pada versi ekstensi dan mode eksekusi C#, yang dapat menjadi salah satu hal berikut:

Model pekerja terisolasi

Pustaka kelas proses pekerja terisolasi yang dikompilasi fungsi C# berjalan dalam proses yang diisolasi dari runtime.

Model dalam proses

Pustaka kelas dalam proses adalah kompilasi fungsi #C yang berjalan pada proses yang sama seperti runtime Functions.

Pilih versi untuk melihat detail jenis pengikatan untuk mode dan versi.

Ekstensi 4.x+

Ekstensi Azure Cosmos DB mendukung jenis parameter sesuai dengan tabel di bawah ini.

Skenario pengikatan	Jenis parameter
Pemicu Cosmos DB (dokumen tunggal)	JSON tipeyang dapat diserialisasikan 1
Pemicu Cosmos DB (batch dokumen)	IEnumerable<T>di mana T adalah JSON tipeyang dapat diserialisasikan 1
Input Cosmos DB (dokumen tunggal)	JSON tipeyang dapat diserialisasikan 1
Input Cosmos DB (kueri mengembalikan beberapa dokumen)	CosmosClient IEnumerable<T> di mana T adalah JSON tipeyang dapat diserialisasikan 1
Output Cosmos DB (dokumen tunggal)	JSON tipeyang dapat diserialisasikan 1
Output Cosmos DB (beberapa dokumen)	ICollector<T> atau IAsyncCollector<T> di mana T adalah JSON tipeyang dapat diserialisasikan 1

¹ Dokumen yang berisi data JSON dapat dideserialisasi ke dalam jenis objek CLR (POCO) lama biasa yang diketahui.

Functions 2.x+

Versi ekstensi yang lebih lama mengekspos jenis yang diekspos dari namespace Microsoft.Azure.Documents yang sekarang tidak digunakan lagi. Jenis yang lebih baru dari Microsoft.Azure.Cosmos eksklusif untuk ekstensi 4.x dan yang lebih tinggi.

Ekstensi 4.x+

Proses pekerja yang terisolasi mendukung jenis parameter sesuai dengan tabel di bawah ini. Dukungan untuk pengikatan ke jenis dari Microsoft.Azure.Cosmossedang dalam pratinjau.

Pemicu Cosmos DB

Saat Anda ingin fungsi memproses satu dokumen, pemicu Cosmos DB dapat mengikat ke jenis berikut:

Tipe	Deskripsi
Jenis yang bisa diserialisasikan JSON	Functions mencoba mendeserialisasi data JSON dokumen dari umpan perubahan Cosmos DB menjadi jenis objek CLR (POCO) yang sudah lama.

Saat Anda ingin fungsi memproses batch dokumen, pemicu Cosmos DB dapat mengikat ke jenis berikut:

Tipe	Deskripsi
IEnumerable<T>di mana T adalah jenis JSON yang dapat diserialisasikan	Enumerasi entitas yang termasuk dalam batch. Setiap entri mewakili satu dokumen dari umpan perubahan Cosmos DB.

Pengikatan input Cosmos DB

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

Tipe	Deskripsi
Jenis yang bisa diserialisasikan JSON	Fungsi mencoba mendeserialisasi data JSON dokumen ke dalam jenis objek CLR (POCO) yang sudah lama biasa.

Saat Anda ingin fungsi memproses beberapa dokumen dari kueri, pengikatan input Cosmos DB dapat mengikat ke jenis berikut:

Tipe	Deskripsi
IEnumerable<T>di mana T adalah jenis JSON yang dapat diserialisasikan	Enumerasi entitas yang dikembalikan oleh kueri. Setiap entri mewakili satu dokumen.
CosmosClient1	Klien yang terhubung ke akun Cosmos DB.
Database1	Klien yang terhubung ke database Cosmos DB.
Kontainer1	Klien yang terhubung ke kontainer Cosmos DB.

¹ Untuk menggunakan jenis ini, Anda perlu mereferensikan Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 atau yang lebih baru dan dependensi umum untuk pengikatan jenis SDK.

Pengikatan output Cosmos DB

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 CosmosClient dengan jenis lain dari Microsoft.Azure.Cosmos secara langsung. Lihat Mendaftarkan klien Azure untuk contoh penggunaan injeksi dependensi untuk membuat jenis klien dari Azure SDK.

Functions 2.x+

Versi ekstensi yang lebih lama dalam proses pekerja yang terisolasi hanya mendukung pengikatan ke jenis JSON yang dapat diserialisasikan. Opsi tambahan tersedia untuk ekstensi 4.x dan yang lebih tinggi.

Kode pengecualian dan pengembalian

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

Pengaturan host.json

Bagian ini menjelaskan pengaturan konfigurasi yang tersedia untuk pengikatan ini dalam versi 2.x dan yang lebih tinggi. Pengaturan dalam file host.json berlaku untuk semua fungsi dalam instans aplikasi fungsi. Contohnya file host.json di bawah ini hanya berisi pengaturan versi 2.x+ untuk pengikatan ini. Untuk informasi selengkapnya tentang pengaturan konfigurasi aplikasi fungsi dalam versi 2.x dan seterusnya, lihat referensi host.json untuk Azure Functions.

Ekstensi 4.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Properti	Default	Deskripsi
connectionMode	Gateway	Mode koneksi yang digunakan oleh fungsi saat menyambungkan ke layanan Azure Cosmos DB. Opsinya adalah Direct dan Gateway
userAgentSuffix	n/a	Menambahkan nilai string yang ditentukan ke semua permintaan yang dibuat oleh pemicu atau pengikatan ke layanan. Ini memudahkan Anda melacak aktivitas di Azure Monitor, berdasarkan aplikasi fungsi tertentu dan pemfilteran berdasarkan User Agent.

Functions 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Properti	Default	Deskripsi
connectionMode	Gateway	Mode koneksi yang digunakan oleh fungsi saat menyambungkan ke layanan Azure Cosmos DB. Opsinya adalah Direct dan Gateway
protokol	Https	Protokol koneksi yang digunakan oleh fungsi saat tersambung ke layanan Azure Cosmos DB. Baca di sini untuk penjelasan kedua mode tersebut.
leasePrefix	n/a	Awalan sewa untuk digunakan di semua fungsi dalam aplikasi.

Langkah berikutnya

• Menjalankan fungsi saat dokumen Azure Cosmos DB dibuat atau dimodifikasi (Pemicu)
• Membaca dokumen Azure Cosmos DB (pengikatan Input)
• Menyimpan perubahan pada dokumen Azure Cosmos DB (Pengikatan output)