بدء استخدام Azure Cosmos DB ل MongoDB باستخدام JavaScript

ينطبق على: MongoDB

توضح هذه المقالة كيفية الاتصال ب Azure Cosmos DB ل MongoDB باستخدام حزمة MongoDB npm الأصلية. بمجرد الاتصال، يمكنك إجراء عمليات على قواعد البيانات والحاويات والعناصر.

إشعار

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

API للوثائق | المرجعية MongoDB حزمة MongoDB (npm)

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Node.js LTS
• واجهة سطر الأوامر من Azure (واجهة مستوى الاستدعاء) أو Azure PowerShell
• Azure Cosmos DB لمورد MongoDB

إنشاء تطبيق JavaScript الجديد

1. قم بإنشاء تطبيق JavaScript جديد في مجلد فارغ باستخدام terminal المفضل لديك. npm init استخدم الأمر لبدء المطالبات لإنشاء الملفpackage.json. اقبل الإعدادات الافتراضية للمطالبات.

   npm init
   

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

   npm install mongodb dotenv
   

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

   node index.js
   

الاتصال مع برنامج تشغيل MongoDB الأصلي إلى Azure Cosmos DB ل MongoDB

للاتصال بمحرك MongoDB الأصلي بـ Azure Cosmos DB، قم بإنشاء مثيل للفئة MongoClient. هذه الفئة هي نقطة البداية لتنفيذ جميع العمليات الخاصة بقواعد البيانات.

تحتوي الدالة الإنشائية الأكثر شيوعاً لدى CosmosClient على معلمتين:

المعلمة‬	قيمة المثال	‏‏الوصف
url	متغير البيئة COSMOS_CONNECTION_STRING	سلسلة الاتصال استخدام واجهة برمجة التطبيقات (API) ل MongoDB لجميع الطلبات
options	{ssl: true, tls: true, }	خيارات MongoDB للاتصال.

راجع دليل استكشاف الأخطاء وإصلاحها لمشكلات الاتصال.

الحصول على اسم المورد

Azure CLI

1. إنشاء متغير shell لدى resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. استخدم الأمر az cosmosdb list لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد وتخزينه في متغير accountName shell.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

بوويرشيل

1. إنشاء متغير shell لدى RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. استخدم الأمر cmdlet Get-AzCosmosDBAccountKey لاسترداد اسم حساب Azure Cosmos DB الأول في مجموعة الموارد الخاصة بك وتخزينه في متغير accountName shell.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

بوابة

تخطي هذه الخطوة واستخدام المعلومات للمدخل في الخطوة التالية.

استرداد سلسلة الاتصال الخاصة بك

Azure CLI

1. ابحث عن واجهة برمجة التطبيقات ل MongoDB سلسلة الاتصال من قائمة سلسلة الاتصال للحساب باستخدام az cosmosdb keys list الأمر .

   az cosmosdb keys list --type connection-strings \
       --resource-group $resourceGroupName \
       --name $accountName 
   

2. سجّل قيم المفتاح الأساسي. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوويرشيل

1. ابحث عن سلسلة الاتصال من قائمة سلاسل الاتصال والمفاتيح للحساب باستخدام Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. سجّل قيمة سلسلة الاتصال. سوف تستخدم بيانات الاعتماد هذه لاحقًا.

بوابة

تلميح

نوصي باستخدام اسم مجموعة الموارد msdocs-cosmosفي هذا الدليل.

1. قم بتسجيل الدخول إلى بوابة Azure.

2. انتقل إلى صفحة حساب Azure Cosmos DB ل MongoDB الموجودة.

3. من صفحة حساب Azure Cosmos DB ل MongoDB، حدد خيار قائمة التنقل سلسلة الاتصال.

4. سجّل القيمة من حقل PRIMARY CONNECTION STRING. يمكنك استخدام هذه القيمة في خطوة لاحقة.

   

تكوين متغيرات البيئة

لاستخدام قيم CONNECTION STRING داخل التعليمات البرمجية الخاصة بك، قم بتعيين هذه القيمة في البيئة المحلية التي تقوم بتشغيل التطبيق. لتعيين متغير البيئة، استخدم المحطة terminal المفضلة لديك لتشغيل الأوامر التالية:

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

‎.env

الملف .env هو طريقة قياسية لتخزين متغيرات البيئة في مشروع. أنشئ ملف .env في جذر المشروع الخاص بك. إضافة الأسطر التالية إلى الملف .env:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

إنشاء MongoClient بسلسلة الاتصال

1. أضف تبعيات للإشارة إلى حزم MongoDB وDotEnv npm.

   // Use official mongodb driver to connect to the server
   import { MongoClient } from '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);
   
   // connect to the server
   await client.connect();
   
   // client options
   const options = client.options;
   console.log(
     `Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`
   );
   

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

إغلاق اتصال MongoClient

عند الانتهاء من التطبيق الخاص بك مع الاتصال، تذكر إغلاقه. .close() يجب أن يكون الاستدعاء بعد إجراء جميع استدعاءات قاعدة البيانات.

client.close()

استخدام فئات عملاء MongoDB مع Azure Cosmos DB لواجهة برمجة التطبيقات ل MongoDB

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

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

يتم تمثيل كل نوع من الموارد من خلال فئة واحدة أو أكثر من فئات JavaScript المرتبطة. فيما يلي قائمة بالفئات الأكثر شيوعاً:

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

توضح لك الأدلة التالية كيفية استخدام كل فئة من هذه الفئات لإنشاء التطبيق الخاص بك.

الدليل:

• إدارة قواعد البيانات
• إدارة المجموعات
• إدارة المستندات
• استخدام الاستعلامات لإيجاد المستندات

(راجع أيضًا )

• حزمة (NuGet)
• مرجع واجهة برمجة التطبيقات

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

الآن بعد أن قمت بالاتصال بواجهة برمجة تطبيقات لحساب MongoDB، استخدم الدليل التالي لإنشاء قواعد البيانات وإدارتها.

إنشاء قاعدة بيانات في Azure Cosmos DB ل MongoDB باستخدام JavaScript