Pemicu dan pengikatan Azure Cosmos DB untuk gambaran umum Azure Functions

Kumpulan artikel ini menjelaskan cara bekerja dengan pengikatan Azure Cosmos DB di Azure Functions. 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

Penting

Versi ekstensi pengikatan Azure Cosmos DB ini mendukung Azure Functions versi 4.x. Jika aplikasi Anda masih menggunakan runtime Functions versi 1.x, lihat Pengikatan Azure Cosmos DB untuk Azure Functions 1.x. Dalam runtime Functions v1.x, pengikatan ini awalnya bernama DocumentDB.

API yang didukung

Tabel ini menunjukkan cara menyambungkan ke berbagai API Azure Cosmos DB dari kode fungsi Anda:

API	Recommendation
Azure Cosmos DB untuk NoSQL	Menggunakan ekstensi pengikatan Azure Cosmos DB
Azure Cosmos DB untuk MongoDB	Gunakan SDK klien asli.
Azure Cosmos DB untuk Tabel	Gunakan ekstensi pengikatan Azure Tables versi 5.x atau yang lebih baru.
Azure Cosmos DB untuk Apache Cassandra	Gunakan SDK klien asli.
Azure Cosmos DB untuk Apache Gremlin (Graph API)	Menggunakan SDK klien asli
Azure Cosmos DB for PostgreSQL	Gunakan SDK klien asli.

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.

Fungsi 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

Fungsi 2.x+

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

Memasang bundel

Agar dapat menggunakan ekstensi pengikatan ini di aplikasi Anda, pastikan file host.json di akar proyek Anda berisi referensi ini extensionBundle :

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

Dalam contoh ini, version nilai [4.0.0, 5.0.0) menginstruksikan host Functions untuk menggunakan versi bundel yang setidaknya 4.0.0 tetapi kurang dari 5.0.0, yang mencakup semua versi potensial 4.x. Notasi ini secara efektif mempertahankan aplikasi Anda pada versi minor terbaru yang tersedia dari bundel ekstensi v4.x.

Jika memungkinkan, Anda harus menggunakan versi utama bundel ekstensi terbaru dan memungkinkan runtime untuk secara otomatis mempertahankan versi minor terbaru. Anda dapat melihat konten bundel terbaru pada halaman rilis bundel ekstensi. Untuk informasi selengkapnya, lihat Bundel ekstensi Azure Functions.

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.

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.

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

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

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

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

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

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

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

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

Jenis Pengikatan SDK

Dukungan Jenis SDK untuk Azure Cosmos ada di Pratinjau. Ikuti Pengikatan SDK Python untuk Sampel CosmosDB untuk mulai menggunakan Jenis SDK untuk Cosmos di Python.

Penting

Menggunakan pengikatan jenis SDK memerlukan model pemrograman Python v2.

---

Pengikatan	Jenis parameter	Contoh-contoh
Input CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	ContainerProxy, CosmosClient, DatabaseProxy

---

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 di versi 2.x dan yang lebih baru. Pengaturan dalam file host.json berlaku untuk semua fungsi dalam instans aplikasi fungsi. Untuk informasi selengkapnya tentang pengaturan konfigurasi aplikasi fungsi, lihat referensihost.json untuk Azure Functions.

Ekstensi 4.x+

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

Properti	Bawaan	Deskripsi
connectionMode	Gateway	Mode koneksi yang digunakan oleh fungsi saat menyambungkan ke layanan Azure Cosmos DB. Opsi: Direct terhubung langsung ke replika backend melalui TCP dan dapat memberikan latensi yang lebih rendah, dan Gateway merutekan permintaan melalui gateway ujung depan melalui HTTPS. Untuk informasi selengkapnya, lihat Mode koneksi Azure Cosmos DB SDK.
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.

Fungsi 2.x+

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

Properti	Bawaan	Deskripsi
connectionMode	Gateway	Mode koneksi yang digunakan oleh fungsi saat menyambungkan ke layanan Azure Cosmos DB. Opsi: Direct terhubung langsung ke replika backend melalui TCP dan dapat memberikan latensi yang lebih rendah, dan Gateway merutekan permintaan melalui gateway ujung depan melalui HTTPS. Untuk informasi selengkapnya, lihat Mode koneksi Azure Cosmos DB SDK.
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)