Menggunakan perintah ekstensi MongoDB untuk mengelola data yang disimpan di Azure Cosmos DB untuk MongoDB

Artikel
05/23/2023

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 Azure Cosmos DB. Manfaat ini termasuk, tetapi tidak terbatas pada:

Distribusi global
Sharding otomatis
Ketersediaan tinggi
Jaminan latensi
Enkripsi saat istirahat
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 untuk MongoDB memungkinkan penggunaan driver klien yang ada dengan mematuhi protokol kawat MongoDB.

Dukungan protokol MongoDB

Azure Cosmos DB untuk 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 bahwa database dapat ditingkatkan 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 Autoscale 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 bahwa database dapat ditingkatkan 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 provisionedThroughputautoScaleSettingsmaxThroughput 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	Diperlukan	Deskripsi
`customAction`	`string`	Diperlukan	Nama perintah kustom. Nilainya harus `CreateCollection`.
`collection`	`string`	Diperlukan	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 di-shard, baru dengan 400RU/dtk dan indeks pada _id bidang yang 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 sebesar 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 Autoscale yang tidak di-shard

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 bahwa koleksi dapat ditingkatkan menjadi dinamis.
`indexes`	`Array`	Konfigurasikan indeks secara opsional. Parameter ini hanya didukung untuk 3,6+ akun. Saat ada, kumpulan indeks yang ditentukan (termasuk indeks yang dijatuhkan) 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 bahwa koleksi dapat ditingkatkan 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 untuk itu, itu termasuk provisionedThroughput nilai, dan outputnya adalah:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 400,
        "ok" : 1
}

Jika koleksi memiliki throughput Skala Otomatis 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 menentukan 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 dari 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:

Menggunakan perintah ekstensi MongoDB untuk mengelola data yang disimpan di Azure Cosmos DB untuk MongoDB

Dukungan protokol MongoDB

Membuat database

Output

Contoh: Membuat database

Contoh: Membuat database dengan throughput

Contoh: Membuat database dengan throughput Skala Otomatis

Perbarui database

Output

Contoh: Memperbarui throughput yang disediakan yang terkait dengan database

Contoh: Memperbarui throughput Autoscale yang terkait dengan database

Mendapatkan database

Output

Contoh: Mendapatkan database

Buat koleksi

Output

Contoh: Membuat koleksi dengan konfigurasi minimum

Contoh: Membuat koleksi yang tidak di-shard

Contoh: Membuat koleksi pecahan

Contoh: Membuat koleksi Autoscale yang tidak di-shard

Contoh: Membuat koleksi Skala Otomatis yang dipecah

Perbarui koleksi

Output

Contoh: Memperbarui throughput yang disediakan yang terkait dengan koleksi

Mendapatkan koleksi

Output

Contoh: Mendapatkan koleksi

Paralelisasi aliran perubahan

Contoh: Mendapatkan token aliran

Output default dari perintah kustom

Langkah berikutnya

Sumber Daya Tambahan: