Menggunakan perintah ekstensi MongoDB untuk mengelola data yang disimpan di Azure Cosmos DB untuk MongoDB
BERLAKU UNTUK: MongoDB
Dokumen berikut berisi perintah tindakan kustom yang khusus untuk Azure Cosmos DB untuk MongoDB. Perintah ini dapat digunakan untuk membuat dan mendapatkan sumber daya database yang khusus untuk model kapasitas DB Azure Cosmos.
Dengan menggunakan Azure Cosmos DB untuk MongoDB, Anda dapat menikmati manfaat bersama Dari Azure Cosmos DB. Manfaat ini termasuk, tetapi tidak terbatas pada:
- Distribusi global
- Sharding otomatis
- Ketersediaan tinggi
- Jaminan latensi
- Enkripsi saat tidak aktif
- Pencadangan
Anda dapat menikmati manfaat ini sambil mempertahankan investasi Anda dalam aplikasi MongoDB yang ada. Anda dapat berkomunikasi dengan Azure Cosmos DB untuk MongoDB dengan menggunakan salah satu driver klien MongoDB sumber terbuka. Azure Cosmos DB for MongoDB memungkinkan penggunaan driver klien yang ada dengan mematuhi protokol kawat MongoDB.
Dukungan protokol MongoDB
Azure Cosmos DB for MongoDB kompatibel dengan server MongoDB versi 4.0, 3.6, dan 3.2. Untuk informasi selengkapnya, lihat fitur dan sintaks yang didukung dalam versi 4.0, 3.6, dan 3.2.
Perintah ekstensi berikut membuat dan memodifikasi sumber daya khusus Azure Cosmos DB melalui permintaan database:
- Membuat database
- Perbarui database
- Mendapatkan database
- Membuat koleksi
- Perbarui koleksi
- Mendapatkan koleksi
Membuat database
Perintah buat ekstensi database membuat database MongoDB baru. Nama database dapat digunakan dari konteks database yang ditetapkan oleh use database
perintah. Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Deskripsi |
---|---|---|
customAction |
string |
Nama perintah kustom. Nilainya harus CreateDatabase . |
offerThroughput |
int |
Throughput yang disediakan yang Anda tetapkan di database. Parameter ini bersifat opsional. |
autoScaleSettings |
Object |
Diperlukan untuk mode Autoscale. Obyek ini memuat setelan yang terkait dengan mode kapasitas SkalaOtomatis. Anda dapat menyiapkan maxThroughput nilai, yang menjelaskan jumlah Unit Permintaan tertinggi yang dapat ditingkatkan koleksinya menjadi dinamis. |
Output
Jika perintah berhasil, perintah akan mengembalikan respons berikut:
{ "ok" : 1 }
Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Membuat database
Untuk membuat database bernama "test"
yang menggunakan semua nilai default, gunakan perintah berikut ini:
use test
db.runCommand({customAction: "CreateDatabase"});
Perintah ini membuat database tanpa throughput tingkat database. Operasi ini berarti bahwa koleksi dalam database ini perlu menentukan jumlah throughput yang perlu Anda gunakan.
Contoh: Membuat database dengan throughput
Untuk membuat database bernama "test"
dan menentukan throughput tingkat database yang disediakan dari 1000 RUs, gunakan perintah berikut:
use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });
Perintah ini membuat database dan mengatur throughput ke dalamnya. Semua koleksi dalam database ini berbagi throughput yang ditetapkan, kecuali koleksi dibuat dengan tingkat throughput tertentu.
Contoh: Membuat database dengan throughput Skala Otomatis
Untuk membuat database bernama dan "test"
menentukan throughput maks SkalaOtomatis 20.000 RU/dk di tingkat database,gunakan perintah berikut:
use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
Perbarui database
Perintah ekstensi database pembaruan memperbarui properti yang terkait dengan database yang ditentukan. Mengubah database Anda dari throughput yang disediakan menjadi skala otomatis dan sebaliknya hanya didukung dalam portal Azure. Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Deskripsi |
---|---|---|
customAction |
string |
Nama perintah kustom. Nilainya harus UpdateDatabase . |
offerThroughput |
int |
Throughput baru yang disediakan yang ingin Anda atur di database jika database menggunakan throughput tingkat database |
autoScaleSettings |
Object |
Diperlukan untuk mode Autoscale. Obyek ini memuat setelan yang terkait dengan mode kapasitas SkalaOtomatis. Anda dapat menyiapkan maxThroughput nilai, yang menjelaskan jumlah Unit Permintaan tertinggi yang dapat ditingkatkan database menjadi dinamis. |
Perintah ini menggunakan database yang ditentukan dalam konteks sesi. Database ini sama dengan yang Anda gunakan dalam use <database>
perintah. Saat ini, nama database tidak dapat diubah menggunakan perintah ini.
Output
Jika perintah berhasil, perintah akan mengembalikan respons berikut:
{ "ok" : 1 }
Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Memperbarui throughput yang disediakan yang terkait dengan database
Untuk memperbarui throughput database yang disediakan dengan nama ke "test"
1200 RUs, gunakan perintah berikut:
use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });
Contoh: Memperbarui throughput Skala otomatis yang terkait dengan database
Untuk memperbarui throughput database yang disediakan dengan nama "test"
menjadi 20.000 RUs, atau untuk mengubahnya ke tingkat throughput Autoscale,gunakan perintah berikut:
use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });
Mendapatkan database
Perintah dapatkan ekstensi database mengembalikan objek database. Nama database digunakan dari konteks database tempat perintah dijalankan.
{
customAction: "GetDatabase"
}
Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Deskripsi |
---|---|---|
customAction |
string |
Nama perintah kustom. Nilainya harus GetDatabase . |
Output
Jika perintah berhasil, respons berisi dokumen dengan bidang berikut:
Bidang | Jenis | Deskripsi |
---|---|---|
ok |
int |
Status respons. 1 == sukses. 0 == kegagalan. |
database |
string |
Nama database. |
provisionedThroughput |
int |
Throughput yang diprovisi yang ditetapkan di database apabila database menggunakan throughput tingkat database manual |
autoScaleSettings |
Object |
Objek ini berisi parameter kapasitas yang terkait dengan database jika menggunakan mode Skala Otomatis. Nilai menjelaskan maxThroughput jumlah Unit Permintaan tertinggi yang dapat ditingkatkan database menjadi dinamis. |
Jika perintah gagal, respons perintah kustom default akan dikembalikan. Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Mendapatkan database
Untuk mendapatkan objek database untuk database bernama "test"
, gunakan perintah berikut ini:
use test
db.runCommand({customAction: "GetDatabase"});
Jika database tidak memiliki throughput terkait, outputnya adalah:
{ "database" : "test", "ok" : 1 }
Jika database memiliki throughput manual tingkat database yang terkait dengannya, output akan memperlihatkan provisionedThroughput
nilai:
{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }
Jika database memiliki throughput Autoscale tingkat database yang terkait dengannya, output akan menampilkan , yang menjelaskan RU/ s minimum untuk database, dan objek provisionedThroughput
autoScaleSettings
maxThroughput
termasuk , yang menjelaskan RU / s maksimum untuk database.
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
Buat koleksi
Perintah buat ekstensi koleksi membuat koleksi MongoDB baru. Nama database digunakan dari konteks database yang ditetapkan oleh perintah use database
. Format perintah CreateCollection adalah sebagai berikut:
{
customAction: "CreateCollection",
collection: "<Collection Name>",
shardKey: "<Shard key path>",
// Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" to use Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting.
offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}
Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Wajib | Deskripsi |
---|---|---|---|
customAction |
string |
Wajib diisi | Nama perintah kustom. Nilainya harus CreateCollection . |
collection |
string |
Wajib | Nama koleksi. Tidak ada karakter atau spasi khusus yang diperbolehkan. |
offerThroughput |
int |
Opsional | Throughput yang disediakan untuk ditetapkan di database. Jika parameter ini tidak disediakan, parameter defaultnya adalah minimum, 400 RU/dtk. * Untuk menentukan throughput di luar 10.000 RU / s, shardKey parameter diperlukan. |
shardKey |
string |
Diperlukan untuk koleksi dengan throughput besar | Jalan menuju Kunci Shard untuk koleksi pecahan. Parameter ini diperlukan jika Anda menetapkan lebih dari 10.000 RU/d dalam offerThroughput . Jika ditentukan, semua dokumen yang disisipkan memerlukan kunci dan nilai ini. |
autoScaleSettings |
Object |
Diperlukan untuk mode Autoscale | Obyek ini memuat setelan yang terkait dengan mode kapasitas SkalaOtomatis. Anda dapat menyiapkan maxThroughput nilai, yang menjelaskan jumlah Unit Permintaan tertinggi bahwa koleksi dapat ditingkatkan menjadi dinamis. |
indexes |
Array |
Konfigurasikan indeks secara opsional. Parameter ini hanya didukung untuk 3,6+ akun. | Ketika hadir, indeks pada _id diperlukan. Setiap entri dalam larik harus menyertakan kunci dari satu atau lebih bidang, nama, dan mungkin berisi opsi indeks. Misalnya, untuk membuat indeks unik majemuk pada bidang a dan b gunakan entri ini: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true} . |
Output
Mengembalikan respons perintah kustom default. Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Membuat koleksi dengan konfigurasi minimum
Untuk membuat koleksi baru dengan nama "testCollection"
dan nilai default, gunakan perintah berikut ini:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});
Operasi ini menghasilkan koleksi tetap, tidak terjaga, baru dengan 400RU/dtk dan indeks pada bidang yang _id
dibuat secara otomatis. Jenis konfigurasi ini juga berlaku saat membuat koleksi baru melalui insert()
fungsi . Contohnya:
use test
db.newCollection.insert({});
Contoh: Membuat koleksi yang tidak di-shard
Untuk membuat koleksi yang tidak di-shard dengan nama "testCollection"
dan throughput yang disediakan dari 1000 RU, gunakan perintah berikut:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});
Anda dapat membuat koleksi hingga 10.000 RU/dk offerThroughput
sebagai tanpa perlu menentukan kunci shard. Untuk koleksi dengan throughput yang lebih besar, lihat bagian berikutnya.
Contoh: Membuat koleksi pecahan
Untuk membuat koleksi yang dipecah dengan nama "testCollection"
dan throughput yang disediakan 11.000 RU, dan shardkey
properti "a.b", gunakan perintah berikut:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });
Perintah ini sekarang memerlukan shardKey
parameter, karena lebih dari 10.000 RU / s ditentukan dalam offerThroughput
.
Contoh: Membuat koleksi Skala Otomatis yang tidak dihapus
Untuk membuat koleksi tanpa pecahan bernama 'testCollection'
yang menggunakan kapasitas throughput Autoscale yang diatur ke 4.000 RU/s, gunakan perintah berikut:
use test
db.runCommand({
customAction: "CreateCollection", collection: "testCollection",
autoScaleSettings:{
maxThroughput: 4000
}
});
Untuk nilainya autoScaleSettings.maxThroughput
, Anda dapat menentukan rentang dari 4.000 RU/dtk hingga 10.000 RU/dtk tanpa kunci shard. Untuk throughput autoscale yang lebih tinggi, Anda perlu menentukan shardKey
parameternya.
Contoh: Membuat koleksi Skala Otomatis yang dipecah
Untuk membuat koleksi sharded yang dinamai 'testCollection'
dengan kunci shard yang dipanggil 'a.b'
, dan itu menggunakan kapasitas throughput Autoscale disetel ke 20.000 RU / s, gunakan perintah berikut:
use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});
Perbarui koleksi
Perintah ekstensi koleksi pembaruan memperbarui properti yang terkait dengan koleksi yang ditentukan. Mengubah koleksi Anda dari throughput yang disediakan menjadi skala otomatis dan sebaliknya hanya didukung dalam portal Azure.
{
customAction: "UpdateCollection",
collection: "<Name of the collection that you want to update>",
// Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" if using Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting. Changing between Autoscale and Provisioned throughput is only supported in the Azure Portal.
offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}
Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Deskripsi |
---|---|---|
customAction |
string |
Nama perintah kustom. Nilainya harus UpdateCollection . |
collection |
string |
Nama koleksi. |
offerThroughput |
int |
Throughput yang disediakan untuk disetel pada koleksi. |
autoScaleSettings |
Object |
Diperlukan untuk mode Autoscale. Obyek ini memuat setelan yang terkait dengan mode kapasitas SkalaOtomatis. Nilai menjelaskan maxThroughput jumlah Unit Permintaan tertinggi yang dapat ditingkatkan koleksinya menjadi dinamis. |
indexes |
Array |
Konfigurasikan indeks secara opsional. Parameter ini hanya didukung untuk 3,6+ akun. Saat ada, kumpulan indeks yang ditentukan (termasuk indeks penurunan) menggantikan indeks koleksi yang ada. Indeks pada _id diperlukan. Setiap entri dalam larik harus menyertakan kunci dari satu atau lebih bidang, nama, dan mungkin berisi opsi indeks. Misalnya, untuk membuat indeks unik majemuk pada bidang a dan b gunakan entri ini: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true} . |
Output
Mengembalikan respons perintah kustom default. Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Memperbarui throughput yang disediakan yang terkait dengan koleksi
Untuk memperbarui throughput dari koleksi yang disediakan dengan nama ke "testCollection"
1200 RUs, gunakan perintah berikut:
use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });
Mendapatkan koleksi
Perintah dapatkan koleksi kustom mengembalikan objek koleksi.
{
customAction: "GetCollection",
collection: "<Name of the collection>"
}
Tabel berikut ini menjelaskan parameter dalam perintah:
Bidang | Jenis | Deskripsi |
---|---|---|
customAction |
string |
Nama perintah kustom. Nilainya harus GetCollection . |
collection |
string |
Nama koleksi. |
Output
Jika perintah berhasil, respons berisi dokumen dengan bidang berikut
Bidang | Jenis | Deskripsi |
---|---|---|
ok |
int |
Status respons. 1 == sukses. 0 == kegagalan. |
database |
string |
Nama database. |
collection |
string |
Nama koleksi. |
shardKeyDefinition |
document |
Dokumen spesifikasi indeks digunakan sebagai kunci shard. Bidang ini adalah parameter respons opsional. |
provisionedThroughput |
int |
Throughput yang disediakan untuk disetel pada koleksi. Bidang ini adalah parameter respons opsional. |
autoScaleSettings |
Object |
Objek ini berisi parameter kapasitas yang terkait dengan database jika menggunakan mode Skala Otomatis. Nilai menjelaskan maxThroughput jumlah Unit Permintaan tertinggi yang dapat ditingkatkan koleksinya menjadi dinamis. |
Jika perintah gagal, respons perintah kustom default akan dikembalikan. Lihat output default perintah kustom untuk parameter dalam output.
Contoh: Mendapatkan koleksi
Untuk mendapatkan objek koleksi untuk koleksi bernama "testCollection"
, gunakan perintah berikut:
use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});
Jika koleksi memiliki kapasitas throughput terkait dengannya, itu termasuk provisionedThroughput
nilai, dan outputnya adalah:
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 400,
"ok" : 1
}
Jika koleksi memiliki throughput Autoscale terkait, koleksi menyertakan autoScaleSettings
objek dengan maxThroughput
parameter , yang menentukan throughput maksimum yang ditingkatkan koleksi menjadi dinamis. Selain itu, ini juga mencakup provisionedThroughput
nilai, yang mendefinisikan throughput minimum yang dikurangi koleksi ini jika tidak ada permintaan dalam koleksi:
{
"database" : "test",
"collection" : "testCollection",
"provisionedThroughput" : 1000,
"autoScaleSettings" : {
"maxThroughput" : 10000
},
"ok" : 1
}
Jika kumpulan berbagi throughput tingkat database,baik pada mode Autoscale atau manual, outputnya adalah:
{ "database" : "test", "collection" : "testCollection", "ok" : 1 }
{
"database" : "test",
"provisionedThroughput" : 2000,
"autoScaleSettings" : {
"maxThroughput" : 20000
},
"ok" : 1
}
Paralelisasi aliran perubahan
Saat menggunakan aliran perubahan dalam skala besar, yang terbaik adalah menyebarkan beban secara merata. Perintah berikut mengembalikan satu atau beberapa token resume aliran perubahan - masing-masing sesuai dengan data dari satu shard/partisi fisik (beberapa pecahan/partisi logis dapat ada pada satu partisi fisik). Setiap token resume menyebabkan watch() hanya mengembalikan data dari shard/partisi fisik tersebut.
Gunakan db.collection.watch()
pada setiap token resume (satu utas per token), untuk menskalakan aliran perubahan secara efisien.
{
customAction: "GetChangeStreamTokens",
collection: "<Name of the collection>",
startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}
Contoh: Mendapatkan token aliran
Jalankan perintah kustom untuk mendapatkan token resume untuk setiap pecahan / partisi fisik.
use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})
Jalankan alur/process watch() untuk setiap token resume yang dikembalikan dari perintah kustom GetChangeStreamTokens. Berikut adalah contoh untuk satu utas.
db.test_coll.watch([{ $match: { "operationType": { $in: ["insert", "update", "replace"] } } }, { $project: { "_id": 1, "fullDocument": 1, "ns": 1, "documentKey": 1 } }],
{fullDocument: "updateLookup",
resumeAfter: { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDb250aW51YXRpb24iOlt7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbndkFLbiIsInZhbHVlIjoiXCIxODQ0XCIifX1dfQ=="), "_kind" : NumberInt(1)}})
Dokumen (nilai) di bidang resumeAfter mewakili token resume. Perintah watch()
mengembalikan kurser untuk semua dokumen yang disisipkan, diperbarui, atau diganti dari partisi fisik tersebut sejak perintah kustom GetChangeStreamTokens dijalankan. Sampel data yang dikembalikan disertakan di sini.
{
"_id": {
"_data": BinData(0,
"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDfdsfdsfdsft7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbnVhdGlvbiIsInZhbHVlIjoiXCIxOTgwXCIifX1dfQ=="),
"_kind": 1
},
"fullDocument": {
"_id": ObjectId("60da41ec9d1065b9f3b238fc"),
"name": John,
"age": 6
},
"ns": {
"db": "test-db",
"coll": "test_coll"
},
"documentKey": {
"_id": ObjectId("60da41ec9d1065b9f3b238fc")
}
}
Setiap dokumen yang dikembalikan menyertakan token resume (semuanya sama untuk setiap halaman). Token resume ini harus disimpan dan digunakan kembali jika alur/proses mati. Token resume ini diambil dari tempat anda tinggalkan, dan menerima data hanya dari partisi fisik tersebut.
Output default perintah kustom
Jika tidak ditentukan, respons kustom berisi dokumen dengan bidang berikut:
Bidang | Jenis | Deskripsi |
---|---|---|
ok |
int |
Status respons. 1 == sukses. 0 == kegagalan. |
code |
int |
Hanya dikembalikan ketika perintah gagal (yaitu, ok == 0). Berisi kode kesalahan MongoDB. Bidang ini adalah parameter respons opsional. |
errMsg |
string |
Hanya dikembalikan ketika perintah gagal (yaitu, ok == 0). Memuat pesan galat yang cocok untuk pengguna. Bidang ini adalah parameter respons opsional. |
Contohnya:
{ "ok" : 1 }
Langkah berikutnya
Selanjutnya Anda dapat melanjutkan untuk mempelajari konsep Azure Cosmos DB berikut: