Bagikan melalui


Pemicu dan pengikatan Azure Cosmos DB untuk Azure Functions 2.x dan gambaran umum 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:

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

Proses untuk menginstal ekstensi bervariasi tergantung pada versi ekstensi:

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

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.

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.

Jenis pengikatan

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

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

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

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.

1 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 jenis dari Microsoft.Azure.Cosmos secara langsung.

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.

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

Langkah berikutnya