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

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) atau Get-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.

  1. 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"
    
  2. Jika Anda belum melakukannya, masuk ke Azure CLI menggunakan perintah az login.

  3. Gunakan perintah az group create untuk membuat grup sumber daya baru di langganan Anda.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. 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

  1. 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 
    
  2. 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 of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

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

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.

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.