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.
Catatan
Contoh cuplikan kode tersedia di GitHub sebagai proyek JavaScript.
API untuk dokumentasi | referensi MongoDB Paket MongoDB (NuGet)
Prasyarat
- Akun Azure dengan langganan aktif. Buat akun secara gratis.
- Node.js LTS
- Azure Command-Line Interface (CLI) atau Azure PowerShell
Pemeriksaan prasyarat
- Di terminal atau jendela perintah, jalankan
node --version
untuk memeriksa apakah Node.js adalah salah satu versi LTS. - Jalankan
az --version
(Azure CLI) atauGet-Module -ListAvailable AzureRM
(Azure PowerShell) untuk memeriksa apakah Anda telah menginstal alat baris perintah Azure yang sesuai.
Menyiapkan
Bagian ini memandikan Anda membuat akun Azure Cosmos DB dan menyiapkan proyek yang menggunakan paket npm MongoDB.
Membuat akun Azure Cosmos DB
Mulai cepat ini akan membuat satu akun Azure Cosmos DB menggunakan API untuk MongoDB.
Buat variabel shell untuk accountName, resourceGroupName, dan location.
# Variable for resource group name resourceGroupName="msdocs-cosmos-quickstart-rg" location="westus" # Variable for account name with a randomnly generated suffix let suffix=$RANDOM*$RANDOM accountName="msdocs-$suffix"
Jika Anda belum melakukannya, masuk ke Azure CLI menggunakan perintah
az login
.Gunakan perintah
az group create
untuk membuat grup sumber daya baru di langganan Anda.az group create \ --name $resourceGroupName \ --location $location
az cosmosdb create
Gunakan perintah untuk membuat akun Azure Cosmos DB for MongoDB baru dengan pengaturan default.az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --locations regionName=$location --kind MongoDB
Mendapatkan string koneksi MongoDB
Temukan API untuk MongoDB string koneksi dari daftar string koneksi untuk akun dengan
az cosmosdb keys list
perintah .az cosmosdb keys list --type connection-strings \ --resource-group $resourceGroupName \ --name $accountName
Rekam nilai KUNCI PRIMER. Anda akan menggunakan info masuk ini nanti.
Membuat aplikasi JavaScript yang baru
Buat aplikasi JavaScript yang baru di folder kosong menggunakan terminal pilihan Anda. Gunakan perintah npm init
untuk memulai perintah untuk membuat file package.json
. Terima default untuk perintah.
npm init
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
Mengonfigurasi variabel lingkungan
Untuk menggunakan nilai STRING KONEKSI dalam kode Anda, atur nilai ini di lingkungan lokal yang menjalankan aplikasi. Untuk mengatur variabel lingkungan, gunakan terminal pilihan Anda untuk menjalankan perintah berikut:
$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"
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
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 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.
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.