مشاركة عبر

التشغيل السريع: Azure Cosmos DB لبرنامج تشغيل MongoDB Node.js

  • مقالة

ينطبق على: MongoDB

ابدأ باستخدام حزمة MongoDB npm لإنشاء قواعد البيانات والمجموعات والمستندات داخل مورد Azure Cosmos DB. يُرجى اتباع هذه الخطوات لتثبيت الحزمة وتجربة التعليمات البرمجية للمهام الأساسية.

إشعار

تتوفر القصاصات البرمجية المثال على GitHub كمشروع JavaScript.

API للوثائق | المرجعية MongoDB حزم حزمة MongoDB (NuGet) / Microsoft.Azure.Cosmos) | Azure Developer CLI

المتطلبات الأساسية

الإعداد

نشر حاوية تطوير هذا المشروع إلى البيئة الخاصة بك. ثم استخدم Azure Developer CLI (azd) لإنشاء Azure Cosmos DB لحساب MongoDB ونشر نموذج تطبيق حاوية. يستخدم نموذج التطبيق مكتبة العميل لإدارة البيانات النموذجية وإنشاءها وقراءتها والاستعلام عن البيانات.

فتح في GitHub Codespaces

فتح في حاوية Dev

هام

تتضمن حسابات GitHub استحقاق التخزين والساعات الأساسية دون أي تكلفة. لمزيد من المعلومات، راجع التخزين المضمن والساعات الأساسية لحسابات GitHub.

  1. افتح محطة طرفية في الدليل الجذر للمشروع.

  2. المصادقة على Azure Developer CLI باستخدام azd auth login. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.

    azd auth login

  3. استخدم azd init لتهيئة المشروع.

    azd init

  4. أثناء التهيئة، قم بتكوين اسم بيئة فريد.

    تلميح

    سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام msdocs-cosmos-db.

  5. انشر حساب Azure Cosmos DB باستخدام azd up. تنشر قوالب Bicep أيضا نموذج تطبيق ويب.

    azd up

  6. أثناء عملية التوفير، حدد اشتراكك والموقع المطلوب. انتظر حتى اكتمال عملية التوفير. قد تستغرق العملية حوالي خمس دقائق.

  7. بمجرد توفير موارد Azure الخاصة بك، يتم تضمين عنوان URL لتطبيق الويب قيد التشغيل في الإخراج.

    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. استخدم عنوان URL في وحدة التحكم للانتقال إلى تطبيق الويب الخاص بك في المستعرض. لاحظ إخراج التطبيق قيد التشغيل.

    لقطة شاشة لتطبيق الويب قيد التشغيل.

تثبيت الحزمة

أضف حزمة MongoDB npm إلى مشروع JavaScript. استخدم الأمر npm install package الذي يحدد اسم حزمة npm. يتم استخدام الحزمة dotenv لقراءة متغيرات البيئة من ملف .env أثناء التطوير المحلي.

npm install mongodb dotenv

نموذج الكائن

قبل البدء في إنشاء التطبيق، لنلقِ نظرة على التدرج الهرمي للموارد في قاعدة بيانات Azure Cosmos DB. تحتوي قاعدة بيانات Azure Cosmos DB على نموذج كائن محدد يُستخدم لإنشاء الموارد والوصول إليها. تنشئ قاعدة بيانات Azure Cosmos DB موارد في تدرج هرمي يتكون من الحسابات وقواعد البيانات والحاويات والمستندات.

رسم تخطيطي لتدرج Azure Cosmos DB الهرمي بما في ذلك الحسابات وقواعد البيانات والمجموعات والمستندات.

ستستخدم فئات MongoDB التالية للتفاعل مع هذه الموارد:

  • MongoClient - توفر هذه الفئة تمثيلا منطقيا من جانب العميل لواجهة برمجة التطبيقات لطبقة MongoDB على Azure Cosmos DB. يتم استخدام كائن العميل لتكوين الطلبات وتنفيذها على الخدمة.
  • Db - هذه الفئة هي إشارة لإحدى قواعد البيانات التي قد تكون موجودة في الخدمة أو قد لا تكون موجودة حتى الآن. يتم التحقق من صحة قاعدة البيانات من جانب الخادم عند محاولة الوصول إليها أو إجراء عملية ضدها.
  • Collection - هذه الفئة هي إشارة إلى مجموعة قد لا تكون موجودة في الخدمة بعد. يتم التحقق من صحة المجموعة من جانب الخادم عندما تحاول استخدامها.

أمثلة على التعليمات البرمجية

ينشئ نموذج التعليمات البرمجية الموضح في هذه المقالة قاعدة بيانات مسماة adventureworks بحاوية مُسماة products. تم تصميم المجموعة products لتحتوي على تفاصيل المنتج مثل الاسم والفئة والكمية ومؤشر البيع. يحتوي كل منتج أيضًا على معرّف فريد.

لهذا الإجراء، لن تستخدم قاعدة البيانات التقسيم.

مصادقة العميل

  1. من دليل المشروع، قم بإنشاء ملف index.js. في المحرر الخاص بك، أضف يتطلب عبارات للإشارة إلى حزم MongoDB وDotEnv npm.

    // 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. حدد مثيلاً جديدًا للفئة MongoClient, باستخدام الدالة الإنشائية، وprocess.env. لقراءة متغير البيئة الذي أنشأته سابقًا.

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

لمزيد من المعلومات حول الطرق المختلفة لإنشاء مثيل MongoClient، راجع التشغيل السريع لبرنامج تشغيل MongoDB NodeJS.

إعداد العمليات غير المتزامنة

في الملف index.js، أضف التعليمات البرمجية التالية لدعم العمليات غير المتزامنة:

async function main(){

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

}

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

يجب إضافة القصاصات البرمجية التالية إلى الدالة الرئيسية من أجل التعامل مع بناء الجملة غير المتزامن/الانتظار.

الاتصال بقاعدة البيانات

MongoClient.connect استخدم الأسلوب للاتصال ب Azure Cosmos DB لمورد MongoDB. يقوم أسلوب الاتصال بإرجاع مرجع إلى قاعدة البيانات.

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

الحصول على مثيل قاعدة البيانات

استخدم MongoClient.db الحصول على مرجع إلى قاعدة بيانات.

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

الحصول على مثيل المجموعة

يحصل MongoClient.Db.collection على مرجع إلى مجموعة.

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

المثيلات المتسلسلة

يمكنك ربط العميل وقاعدة البيانات والمجموعة معًا. هذا التسلسل أكثر ملاءمة إذا كنت بحاجة إلى الوصول إلى قواعد بيانات أو مجموعات متعددة.

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

إنشاء فهرس

استخدم Collection.createIndex لإنشاء فهرس على خصائص المستند التي تنوي استخدامها للفرز باستخدام أسلوب MongoDBFindCursor.sort.

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

إنشاء مستند

أنشئ مستندًا بخصائص المنتجadventureworks لقاعدة البيانات:

  • خاصية _id للمعرف الفريد للمنتج.
  • * خاصية الفئة. يمكن استخدام هذه الخاصية كمفتاح القسم المنطقي.
  • * خاصية الاسم.
  • * خاصية كمية المخزون.
  • * خاصية البيع، مما يشير إلى ما إذا كان المنتج قيد البيع.
// 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`);

إنشاء مستند في المجموعة عن طريق استدعاء Collection.UpdateOne. في هذا المثال، اخترنا upsert بدلاً من إنشاء مستند جديد في حالة تشغيل نموذج التعليمات البرمجية هذا أكثر من مرة.

الحصول على مستند

في قاعدة بيانات Azure Cosmos DB، يمكنك إجراء عملية قراءة نقطة أقل تكلفة باستخدام كل من المعرّف الفريد (_id) ومفتاح القسم (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`);

مستندات الاستعلام

بعد إدراج مستند، يمكنك تشغيل استعلام للحصول على كافة المستندات التي تطابق عامل تصفية معينًا. يبحث هذا المثال عن كافة المستندات التي تطابق فئة محددة: gear-surf-surfboards. بمجرد تحديد الاستعلام، يمكنك Collection.find استدعاء FindCursor للحصول على نتيجة. قم بتحويل المؤشر إلى صفيف لاستخدام أساليب صفيف 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)}`));

استكشاف الأخطاء وإصلاحها:

  • إذا تلقيت خطأ مثل The index path corresponding to the specified order-by item is excluded.، فتأكد من إنشاء الفهرس.

تشغيل التعليمات البرمجية

ينشئ هذا التطبيق واجهة برمجة تطبيقات لقاعدة بيانات MongoDB ومجموعة وينشئ مستندا ثم يقرأ نفس المستند بالضبط مرة أخرى. وأخيرًا، يصدر المثال استعلامًا يجب أن يرجع هذا المستند الفردي فقط. مع كل خطوة، يقوم المثال بإخراج المعلومات إلى وحدة التحكم حول الخطوات التي نفذها.

لتشغيل التطبيق، استخدم terminal للانتقال إلى دليل التطبيق وتشغيل التطبيق.

node index.js

يجب أن يكون إخراج التطبيق مشابهًا لهذا المثال:

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

تنظيف الموارد

عندما لم تعد بحاجة إلى Azure Cosmos DB لحساب MongoDB، يمكنك حذف مجموعة الموارد المقابلة.

استخدم الأمر az group delete لحذف مجموعة الموارد.

az group delete --name $resourceGroupName

الخطوات التالية

في هذا التشغيل السريع، تعلمت كيفية إنشاء حساب Azure Cosmos DB لحساب MongoDB، وإنشاء قاعدة بيانات، وإنشاء مجموعة باستخدام برنامج تشغيل MongoDB. يمكنك الآن التعمق أكثر في Azure Cosmos DB ل MongoDB لاستيراد المزيد من البيانات وإجراء استعلامات معقدة وإدارة موارد Azure Cosmos DB MongoDB.

ترحيل MongoDB إلى Azure Cosmos DB ل MongoDB دون اتصال