Mulai cepat: Driver Azure Cosmos DB for MongoDB untuk Node.js

BERLAKU UNTUK: MongoDB

• .NET
• Python
• Java
• Node.js
• Go

Mulai menggunakan paket npm MongoDB untuk membuat database, koleksi, dan dokumen dalam sumber daya Azure Cosmos DB Anda. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Catatan

Contoh cuplikan kode tersedia di GitHub sebagai proyek JavaScript.

API untuk dokumentasi | referensi MongoDB Paket MongoDB (NuGet) paket/Microsoft.Azure.Cosmos) | Azure Developer CLI

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• Akun GitHub

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• Azure Developer CLI
• Desktop Docker

Menyiapkan

Sebarkan kontainer pengembangan proyek ini ke lingkungan Anda. Kemudian, gunakan Azure Developer CLI (azd) untuk membuat akun Azure Cosmos DB for MongoDB dan menyebarkan aplikasi sampel dalam kontainer. Aplikasi sampel menggunakan pustaka klien untuk mengelola, membuat, membaca, dan mengkueri data sampel.

Penting

Akun GitHub mencakup pemberian izin penyimpanan dan jam inti tanpa biaya. Untuk informasi selengkapnya, lihat penyimpanan dan jam inti yang disertakan untuk akun GitHub.

1. Buka terminal di direktori akar proyek.

2. Autentikasi ke Azure Developer CLI menggunakan azd auth login. Ikuti langkah-langkah yang ditentukan oleh alat untuk mengautentikasi ke CLI menggunakan kredensial Azure pilihan Anda.

   azd auth login
   

3. Gunakan azd init untuk menginisialisasi proyek.

   azd init
   

4. Selama inisialisasi, konfigurasikan nama lingkungan yang unik.

   Tip

   Nama lingkungan juga akan digunakan sebagai nama grup sumber daya target. Untuk mulai cepat ini, pertimbangkan untuk menggunakan msdocs-cosmos-db-.

5. Sebarkan akun Azure Cosmos DB menggunakan azd up. Templat Bicep juga menyebarkan aplikasi web sampel.

   azd up
   

6. Selama proses provisi, pilih langganan dan lokasi yang Anda inginkan. Tunggu hingga proses provisi selesai. Prosesnya dapat memakan waktu sekitar lima menit.

7. Setelah provisi sumber daya Azure Anda selesai, URL ke aplikasi web yang sedang berjalan disertakan dalam output.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Gunakan URL di konsol untuk menavigasi ke aplikasi web Anda di browser. Amati output aplikasi yang sedang berjalan.

   

---

Pasang paket

Tambahkan paket npm MongoDB ke proyek JavaScript. Gunakan perintah npm install package yang menentukan nama paket npm. Paket dotenv digunakan untuk membaca variabel lingkungan dari file .env selama pengembangan lokal.

npm install mongodb dotenv

Model objek

Sebelum Anda mulai membangun aplikasi, mari kita lihat hierarki sumber daya di Azure Cosmos DB. Azure Cosmos DB memiliki model objek tertentu yang digunakan untuk membuat dan mengakses sumber daya. Azure Cosmos DB membuat sumber daya dalam hierarki yang terdiri dari akun, database, koleksi, dan dokumen.

Diagram hierarki memperlihatkan akun Azure Cosmos DB di bagian atas. Akun ini memiliki dua pecahan database anak. Salah satu pecahan database mencakup dua pecahan koleksi anak. Shard database lainnya menyertakan satu simpul koleksi anak. Pecahan koleksi tunggal itu memiliki tiga shard dokumen anak.

Anda akan menggunakan kelas MongoDB berikut untuk berinteraksi dengan sumber daya ini:

• MongoClient - Kelas ini menyediakan representasi logis sisi klien untuk lapisan API untuk MongoDB di Azure Cosmos DB. Klien ini digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap layanan.
• Db - Kelas ini adalah referensi ke database yang mungkin, atau mungkin belum ada dalam layanan. Database divalidasi di sisi server saat Anda mencoba mengaksesnya atau melakukan operasi terhadapnya.
• Collection - Kelas ini adalah referensi ke koleksi yang mungkin juga belum ada dalam layanan. Koleksi divalidasi di sisi server saat Anda mencoba untuk menggunakannya.

Contoh kode

• Autentikasi klien
• Dapatkan instans database
• Dapatkan instans koleksi
• Instans terikat
• Buat indeks
• Membuat dokumen
• Mendapatkan dokumen
• Mengkueri dokumen

Kode sampel yang dijelaskan dalam artikel ini membuat database bernama adventureworks dengan koleksi bernama products. Koleksi products dirancang untuk berisi detail produk seperti nama, kategori, kuantitas, dan indikator penjualan. Setiap produk juga berisi pengidentifikasi unik.

Untuk prosedur ini, database tidak akan menggunakan sharding.

Mengautentikasi klien

1. Dari direktori proyek, buatlah file index.js. Di editor Anda, tambahkan pernyataan yang diperlukan untuk mereferensikan paket npm MongoDB dan DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Tentukan instans baru dari kelas MongoClient, menggunakan konstruktor dan process.env. untuk membaca variabel lingkungan yang Anda buat sebelumnya.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Untuk informasi selengkapnya tentang berbagai cara untuk membuat instans MongoClient, lihat Mulai Cepat Driver NodeJS MongoDB.

Menyiapkan operasi asinkron

Dalam file index.js, tambahkan kode berikut untuk mendukung operasi asinkron:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Cuplikan kode berikut harus ditambahkan ke fungsi utama untuk menangani sintaks asinkron/await.

Sambungkan ke database

MongoClient.connect Gunakan metode untuk menyambungkan ke sumber daya Azure Cosmos DB for MongoDB Anda. Metode sambungkan menampilkan referensi ke database.

// Use connect method to connect to the server
await client.connect();

Dapatkan instans database

Gunakan MongoClient.db untuk mendapatkan referensi ke database.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Mendapatkan instans koleksi

MongoClient.Db.collection mendapatkan referensi ke koleksi.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Instans terikat

Anda dapat menautkan klien, database, dan koleksi bersama-sama. Penautan lebih nyaman jika Anda perlu mengakses beberapa database atau koleksi.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Buat indeks

Gunakan Collection.createIndexuntuk membuat indeks pada properti dokumen yang ingin Anda gunakan untuk pengurutan dengan metode MongoDBFindCursor.sort.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Membuat dokumen

Buat dokumen dengan properti produk untuk database adventureworks:

• Properti _id untuk pengidentifikasi unik produk tersebut.
• Properti kategori. Properti ini dapat digunakan sebagai kunci partisi logis.
• Properti nama.
• Properti kuantitas inventaris.
• Properti penjualan, menunjukkan apakah produk sedang dijual atau tidak.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Buat dokumen dalam koleksi dengan memanggil Collection.UpdateOne. Dalam contoh ini, kami memilih untuk melakukan upsert alih-alih membuat dokumen baru jika Anda menjalankan kode sampel ini lebih dari sekali.

Mendapatkan dokumen

Di Azure Cosmos DB, Anda dapat melakukan operasi pembacaan poin yang lebih murah dengan menggunakan pengidentifikasi unik (_id) dan kunci partisi (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Mengkueri dokumen

Setelah menyisipkan item, Anda dapat menjalankan kueri untuk mendapatkan semua dokumen yang cocok dengan filter tertentu. Contoh ini menemukan semua dokumen yang cocok dengan kategori tertentu: gear-surf-surfboards. Setelah kueri ditentukan, panggil Collection.find untuk mendapatkan hasil FindCursor. Konversi kursor menjadi array untuk menggunakan metode array JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Pemecahan Masalah:

• Jika Anda mendapatkan kesalahan seperti The index path corresponding to the specified order-by item is excluded., pastikan Anda membuat indeks.

Menjalankan kode

Aplikasi ini membuat API untuk database dan koleksi MongoDB dan membuat dokumen lalu membaca dokumen yang sama persis kembali. Terakhir, contoh ini mengeluarkan kueri yang seharusnya hanya mengembalikan dokumen tunggal tersebut. Dengan setiap langkah, contoh tersebut menghasilkan informasi ke konsol tentang langkah-langkah yang telah dilakukan.

Untuk menjalankan aplikasi, gunakan terminal untuk menavigasi ke direktori aplikasi dan menjalankannya.

node index.js

Output aplikasi harus mirip dengan contoh ini:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Membersihkan sumber daya

Saat Anda tidak lagi memerlukan akun Azure Cosmos DB for MongoDB, Anda dapat menghapus grup sumber daya yang sesuai.

Azure CLI

Untuk menghapus grup sumber daya tersebut, gunakan perintah az group delete.

az group delete --name $resourceGroupName

PowerShell

Untuk menghapus grup sumber daya tersebut, gunakan cmdlet Remove-AzResourceGroup.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portal

1. Arahkan ke grup sumber daya yang Anda buat sebelumnya di portal Azure.

   Tip

   Di mulai cepat ini, kami merekomendasikan nama msdocs-cosmos-javascript-quickstart-rg.

2. Pilih Hapus grup sumber daya.

   

3. Pada dialog Apakah Anda yakin ingin menghapus, masukkan nama grup sumber daya, lalu pilih Hapus.

   

Langkah berikutnya

Dalam mulai cepat ini, Anda mempelajari cara membuat akun Azure Cosmos DB untuk MongoDB, membuat database, dan membuat koleksi menggunakan driver MongoDB. Anda sekarang dapat mendalami Azure Cosmos DB for MongoDB untuk mengimpor lebih banyak data, melakukan kueri kompleks, dan mengelola sumber daya Azure Cosmos DB MongoDB Anda.

Memigrasikan MongoDB ke Azure Cosmos DB untuk MongoDB secara offline