Quickstart: Use Azure DocumentDB with MongoDB driver for Java

• TypeScript
• JavaScript
• Python
• C#‎
• Java
• ذهب

في هذا البدء السريع، تقوم بإنشاء تطبيق Azure DocumentDB الأساسي باستخدام جافا. Azure DocumentDB هو مخزن بيانات NoSQL يسمح للتطبيقات بتخزين المستندات في السحابة والوصول إليها باستخدام برامج تشغيل MongoDB الرسمية. يوضح هذا الدليل كيفية إنشاء المستندات وأداء المهام الأساسية في مجموعة Azure DocumentDB باستخدام جافا.

مرجع | APIالشيفرة | المصدريةالحزمة (مافن)

Prerequisites

• اشتراك Azure

  • إذا لم يكن لديك اشتراك Azure، فقم بإنشاء حساب مجاني

• Java 21 أو أحدث

إنشاء عنقود Azure DocumentDB

للبدء، تحتاج أولا إلى إنشاء مجموعة Azure DocumentDB، والتي تعد الأساس لتخزين وإدارة بيانات NoSQL الخاصة بك.

1. تسجيل الدخول إلى بوابة Azure (https://portal.azure.com).

2. من قائمة مدخل Microsoft Azure أو الصفحة الرئيسية، حدد إنشاء مورد.

3. في الصفحة الجديدة ، ابحث عن Azure DocumentDB واختر ذلك.

   

4. في صفحة مجموعة إنشاء Azure DocumentDB وداخل قسم الأساسيات ، اختر خيار التكوين داخل قسم مستوى العنقود .

   

5. في صفحة المقياس ، قم بتكوين هذه الخيارات ثم اختر الحفظ لاستمرار تغييراتك في مستوى العنقود.

   	القيمة‬
   طبقة نظام المجموعة	M30 tier, 2 vCore, 8-GiB RAM
   التخزين لكل جزء	128 GiB

   

6. في قسم الأساسيات، قم بتكوين الخيارات التالية:

   	القيمة‬
   اشتراك	حدد اشتراك Azure الخاص بك
   مجموعة الموارد	إنشاء مجموعة موارد جديدة أو تحديد مجموعة موارد موجودة
   اسم شبكة نظام المجموعة	توفير اسم فريد عالميا
   Location	تحديد منطقة Azure مدعومة لاشتراكك
   نسخة MongoDB	تحديد 8.0
   "Admin username"	إنشاء اسم مستخدم للوصول إلى المجموعة كمسؤول مستخدم
   كلمة المرور	استخدم كلمة مرور فريدة مرتبطة باسم المستخدم

   

   Tip

   سجل القيم التي تستخدمها لاسم المستخدموكلمة المرور. تستخدم هذه القيم لاحقا في هذا الدليل. لمزيد من المعلومات حول القيم الصحيحة، انظر حدود التجمع.

7. حدد Next: Networking.

8. في قسم قواعد جدار الحماية في تبويب الشبكات ، قم بتكوين هذه الخيارات:

   	القيمة‬
   أسلوب الاتصال	Public access
   السماح بالوصول العام من خدمات وموارد Azure داخل Azure إلى هذا العنقود	Enabled

9. أضف قاعدة جدار حماية لجهاز العميل الحالي الخاص بك لمنح الوصول إلى العنقود عن طريق اختيار + إضافة عنوان IP الحالي للعميل.

   

   Tip

   في العديد من بيئات الشركة، يتم إخفاء عناوين IP لجهاز المطور بسبب VPN أو إعدادات شبكة الشركة الأخرى. في هذه الحالات، يمكنك السماح مؤقتا بالوصول إلى جميع عناوين IP بإضافة 0.0.0.0 - 255.255.255.255 نطاق عناوين IP كقاعدة جدار حماية. استخدم قاعدة جدار الحماية هذه مؤقتا فقط كجزء من اختبار وتطوير الاتصال.

10. حدد "Review + create".

11. راجع الإعدادات التي تقدمها، ثم حدد إنشاء. يستغرق بضع دقائق لإنشاء المجموعة. انتظر حتى يكتمل نشر الموارد.

12. وأخيرا، اختر Go to resource للانتقال إلى عنقود Azure DocumentDB في البوابة.

الحصول على بيانات اعتماد نظام المجموعة

احصل على بيانات الاعتماد التي تستخدمها للاتصال بالعنقود.

1. في صفحة المجموعة، اختر خيار سلاسل الاتصال في قائمة الموارد.

2. في قسم سلاسل الاتصال ، قم بنسخ أو تسجيل القيمة من حقل سلسلة الاتصال .

Important

لا تتضمن سلسلة الاتصال في البوابة الإلكترونية قيمة كلمة المرور. يجب استبدال العنصر النائب <password> ببيانات الاعتماد التي أدخلتها عند إنشاء نظام المجموعة أو إدخال كلمة المرور بشكل تفاعلي.

تهيئة المشروع

أنشئ مشروع Maven جديد في دليلك الحالي.

1. ابدأ في دليل فارغ.

2. افتح طرفية في الدليل الحالي.

3. أنشئ مشروع Maven جديد باستخدام نموذج البدء السريع.

   mvn archetype:generate -DgroupId=com.example -DartifactId=azure-documentdb-java-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   

4. انتقل إلى مجلد المشروع الذي تم إنشاؤه.

   cd azure-documentdb-java-quickstart
   

5. ابن المشروع لضمان إنشاؤه بنجاح.

   mvn compile
   

تثبيت مكتبة العميل

مكتبة العميل متاحة عبر Maven، كأداة mongodb-driver-sync أثرية.

1. أضف اعتماد برنامج تشغيل MongoDB جافا إلى ملفك pom.xml .

   <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-driver-sync</artifactId>
       <version>5.2.0</version>
   </dependency>
   

2. افتح وراجع ملف pom.xml للتحقق من وجود إدخال الاعتماد.

3. استيراد الحزم المطلوبة إلى كود التطبيق الخاص بك:

   import com.mongodb.client.MongoClient;
   import com.mongodb.client.MongoClients;
   import com.mongodb.client.MongoCollection;
   import com.mongodb.client.MongoDatabase;
   import com.mongodb.client.model.Filters;
   import com.mongodb.client.model.ReplaceOptions;
   import org.bson.Document;
   import org.bson.conversions.Bson;
   
   import java.util.Arrays;
   import java.util.List;
   

نموذج الكائن

Name	Description
MongoClient	النوع المستخدم للاتصال ب MongoDB.
MongoDatabase	يمثل قاعدة بيانات في نظام المجموعة.
MongoCollection<Document>	يمثل مجموعة داخل قاعدة بيانات في نظام المجموعة.

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

• مصادقة العميل
• الحصول على مجموعة
• أنشئ مستند
• استرجاع مستند
• الاستعلام عن المستندات

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

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

أولا، اتصل بالعميل باستخدام سلسلة اتصال أساسية.

1. أنشئ الطريقة الرئيسية وقم بإعداد سلسلة الاتصال. استبدل <your-cluster-name>، <your-username>، و <your-password> بمعلومات العنقود الفعلية الخاصة بك.

   public class App {
       public static void main(String[] args) {
           // Connection string for Azure DocumentDB cluster
           String connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";
   

2. أنشئ عميل MongoDB وتحقق من الاتصال.

           // Create a new client and connect to the server
           try (MongoClient mongoClient = MongoClients.create(connectionString)) {
   
               // Ping the server to verify connection
               MongoDatabase database = mongoClient.getDatabase("admin");
               database.runCommand(new Document("ping", 1));
   
               System.out.println("Successfully connected and pinged Azure DocumentDB");
   

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

الآن، احصل على قاعدة بياناتك ومجموعتك. إذا لم تكن قاعدة البيانات والمجموعة موجودة بالفعل، استخدم برنامج التشغيل لإنشاؤها تلقائيا.

1. احصل على مرجع لقاعدة البيانات.

               // Get database reference
               MongoDatabase adventureWorksDatabase = mongoClient.getDatabase("adventureworks");
               System.out.println("Connected to database: " + adventureWorksDatabase.getName());
   

2. احصل على مرجع للمجموعة داخل قاعدة البيانات.

               // Get collection reference
               MongoCollection<Document> productsCollection = adventureWorksDatabase.getCollection("products");
               System.out.println("Connected to collection: products");
   

إنشاء مستند

ثم، أنشئ بعض المستندات الجديدة ضمن مجموعتك. قم بترقية الوثائق لضمان استبدال أي مستندات موجودة إذا كانت موجودة بالفعل بنفس المعرف الفريد.

1. أنشئ نماذج مستندات المنتج باستخدام فئة المستندات.

               // Create sample products
               List<Document> products = Arrays.asList(
                   new Document("_id", "00000000-0000-0000-0000-000000004018")
                       .append("name", "Windry Mittens")
                       .append("category", "apparel-accessories-gloves-and-mittens")
                       .append("quantity", 121)
                       .append("price", 35.00)
                       .append("sale", false),
                   new Document("_id", "00000000-0000-0000-0000-000000004318")
                       .append("name", "Niborio Tent")
                       .append("category", "gear-camp-tents")
                       .append("quantity", 140)
                       .append("price", 420.00)
                       .append("sale", true)
               );
   

2. أدخل المستندات باستخدام عمليات upsert.

               // Insert documents with upsert
               for (Document product : products) {
                   Bson filter = Filters.eq("_id", product.getString("_id"));
                   ReplaceOptions options = new ReplaceOptions().upsert(true);
   
                   productsCollection.replaceOne(filter, product, options);
                   System.out.println("Upserted product: " + product.getString("name"));
               }
   

استرجاع مستند

بعد ذلك، قم بإجراء عملية قراءة نقطية لاسترجاع مستند معين من مجموعتك.

1. حدد الفلتر للعثور على مستند معين حسب معرف.

               // Retrieve a specific document by ID
               Bson filter = Filters.eq("_id", "00000000-0000-0000-0000-000000004018");
   

2. نفذ الاستعلام واسترج النتيجة.

               Document retrievedProduct = productsCollection.find(filter).first();
   
               if (retrievedProduct != null) {
                   System.out.println("Retrieved product: " + retrievedProduct.getString("name") + 
                                    " - $" + retrievedProduct.getDouble("price"));
               } else {
                   System.out.println("Product not found");
               }
   

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

وأخيرا، استعلام عدة مستندات باستخدام لغة الاستعلام MongoDB (MQL).

1. حدد استعلاما للعثور على مستندات تطابق معايير محددة.

               // Query for products on sale
               Bson saleFilter = Filters.eq("sale", true);
   

2. كرر عبر المؤشر لاسترجاع جميع المستندات المطابقة.

               System.out.println("Products on sale:");
               for (Document product : productsCollection.find(saleFilter)) {
                   System.out.printf("- %s: $%.2f (Category: %s)%n",
                       product.getString("name"),
                       product.getDouble("price"),
                       product.getString("category"));
               }
   
           } catch (Exception e) {
               System.err.println("An error occurred: " + e.getMessage());
               e.printStackTrace();
           }
       }
   }
   

استكشف بياناتك باستخدام كود Visual Studio

استخدم امتداد DocumentDB في كود Visual Studio لأداء العمليات الأساسية لقواعد البيانات، بما في ذلك الاستعلام، والإدراج، والتحديث، وحذف البيانات.

1. فتح Visual Studio Code.

2. انتقل إلى عرض الامتدادات وابحث عن المصطلح DocumentDB. حدد موقع امتداد DocumentDB ل VS Code .

3. اختر زر التثبيت الخاص بالامتداد. انتظر حتى يكتمل التثبيت. أعد تحميل كود فيجوال ستوديو إذا طلب منك ذلك.

4. انتقل إلى امتداد DocumentDB باختيار الأيقونة المقابلة في شريط النشاط.

5. في صفحة DocumentDB Connections ، اختر + اتصال جديد....

6. في الحوار، اختر Service Discovery ثم Azure DocumentDB - Azure Service Discovery.

7. اختر اشتراك Azure الخاص بك ومجموعة Azure DocumentDB التي أنشأتها حديثا.

   Tip

   في العديد من بيئات الشركة، يتم إخفاء عناوين IP لجهاز المطور بسبب VPN أو إعدادات شبكة الشركة الأخرى. في هذه الحالات، يمكنك السماح مؤقتا بالوصول إلى جميع عناوين IP بإضافة 0.0.0.0 - 255.255.255.255 نطاق عناوين IP كقاعدة جدار حماية. استخدم قاعدة جدار الحماية هذه مؤقتا فقط كجزء من اختبار وتطوير الاتصال. لمزيد من المعلومات، راجع تكوين جدار الحماية.

8. في نافذة DocumentDB Connections ، قم بتوسيع العقدة الخاصة بمجموعتك وانتقل إلى عقد المستندات والمجموعات الحالية.

9. افتح قائمة السياق للمجموعة ثم اختر DocumentDB Scrapbook > New DocumentDB Scrapbook.

10. أدخل أوامر لغة الاستعلام (MQL) التالية من MongoDB ثم اختر تشغيل الكل. راقب مخرجات الأوامر.

    db.products.find({
      price: { $gt: 200 },
      sale: true
    })
    .sort({ price: -1 })
    .limit(3)
    

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

عندما تنتهي من مجموعة Azure DocumentDB، يمكنك حذف الموارد التي أنشأتها في Azure حتى لا تتحمل المزيد من الرسوم.

1. في شريط البحث في مدخل Microsoft Azure، ابحث عن Resource groups وحددها.

   

2. في القائمة، حدد مجموعة الموارد التي استخدمتها لهذا التشغيل السريع.

   

3. في صفحة مجموعة الموارد، حدد "Delete resource group".

4. في مربع حوار تأكيد الحذف، أدخل اسم مجموعة الموارد لتأكيد أنك تنوي حذفها. وأخيرا، حدد حذف لحذف مجموعة الموارد نهائيا.

   

محتوى ذو صلة

• ما هو Azure DocumentDB؟