Mulai cepat: Driver Azure Cosmos DB for MongoDB untuk Node.js
BERLAKU UNTUK: MongoDB
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.
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.
Buka terminal di direktori akar proyek.
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
Gunakan
azd init
untuk menginisialisasi proyek.azd init --template cosmos-db-mongodb-nodejs-quickstart
Catatan
Mulai cepat ini menggunakan repositori GitHub azure-samples/cosmos-db-mongodb-nodejs-quickstart . Azure Developer CLI akan secara otomatis mengkloning proyek ini ke komputer Anda jika belum ada.
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
.Sebarkan akun Azure Cosmos DB menggunakan
azd up
. Templat Bicep juga menyebarkan aplikasi web sampel.azd up
Selama proses provisi, pilih langganan dan lokasi yang Anda inginkan. Tunggu hingga proses provisi selesai. Prosesnya dapat memakan waktu sekitar lima menit.
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.
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 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 juga mungkin belum ada dalam layanan. Koleksi divalidasi di sisi server saat Anda mencoba untuk menggunakannya.
Contoh kode
- Autentikasi klien
- Dapatkan instans database
- Dapatkan instans koleksi
- Menggunakan metode berantai
- Buat indeks
- Membuat dokumen
- Mendapatkan dokumen
- Jalankan Kueri
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 menggunakan sharding.
Mengautentikasi klien
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');
Tentukan instans baru dari kelas
MongoClient,
menggunakan konstruktor danprocess.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.createIndex
untuk 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 mengeluarkan kueri yang seharusnya hanya mengembalikan dokumen tunggal tersebut. Dengan setiap langkah, contoh menghasilkan informasi ke konsol tentang langkah-langkah yang 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.
Untuk menghapus grup sumber daya tersebut, gunakan perintah az group delete
.
az group delete --name $resourceGroupName
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.