Bagikan melalui


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

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