Azure Cosmos DB ل NoSQL: أمثلة Java SDK v4
ينطبق على: 
NoSQL
هام
للتعرّف على المزيد حول Java SDK v4، يرجى الاطلاع على ملاحظات الإصدار بشأن Azure Cosmos DB Java SDK v4، ومستودع Maven، ونصائح أداء Azure Cosmos DB Java SDK v4، ودليل استكشاف الأخطاء وإصلاحها لـAzure Cosmos DB Java SDK v4. إذا كنت تستخدم حاليّاً إصداراً أقدم من الإصدار 4، فراجع دليل الترحيل إلى حزمة تطوير برامج Java Azure Cosmos DB - الإصدار 4 للمساعدة على الترقية إلى الإصدار 4.
هام
إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.
- يمكنك تنشيط مزايا المشتركين في Visual Studio: يمنحك اشتراكك في Visual Studio أرصدة كل شهر يمكنك استخدامها مع خدمات Azure المدفوعة.
بدلاً من ذلك، يمكنك تجربة قاعدة بيانات Azure Cosmos مجاناً دون اشتراك Azure، مجاناً دون التزامات. بدلاً من ذلك، يمكنك إنشاء حساب Azure Cosmos DB مجاني ، مع أول 1000 RU/s و 25GB من التخزين مجاناً. يمكنك أيضًا استخدام محاكي Azure Cosmos DB مع عنوان URL المستخدم https://localhost:8081. لاستخدام المفتاح مع المحاكي، راجع مصادقة الطلبات.
تم تضمين أحدث نماذج التطبيقات التي تؤدي عمليات CRUD والعمليات الشائعة الأخرى على موارد Azure Cosmos DB في مستودع GitHub azure-cosmos-java-sql-api-samples. توفر هذه المقالة:
- روابط إلى المهام في كل من ملفات الأمثلة عن مشروع Java.
- روابط إلى المحتوى المرجعي API ذات الصلة.
المتطلبات المسبقه
تحتاج إلى ما يلي لتشغيل نموذج التطبيق هذا:
- Java Development Kit 8
- Azure Cosmos DB Java SDK v4
يمكنك اختياريًا استخدام Maven للحصول على أحدث ثنائيات Azure Cosmos DB Java SDK v4 للاستخدام في المشروع الخاص بك. يضيف Maven تلقائيًا أي تبعيات ضرورية. وبخلاف ذلك، يمكنك تنزيل التبعيات المدرجة في ملف pom.xml وإضافتها إلى مسار البناء لديك مباشرةً.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-cosmos</artifactId>
<version>LATEST</version>
</dependency>
تشغيل نماذج التطبيقات
استنساخ مستودع النموذج:
$ git clone https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples.git
$ cd azure-cosmos-java-sql-api-samples
يمكنك تشغيل العينات باستخدام إما IDE (Eclipse أو IntelliJ أو VS Code) أو من سطر الأوامر باستخدام Maven.
يجب تعيين متغيرات البيئة هذه
ACCOUNT_HOST=your account hostname;ACCOUNT_KEY=your account primary key
من أجل إعطاء عينات القراءة / الكتابة الوصول إلى حسابك.
لتشغيل نموذج، حدد الفئة الرئيسية الخاصة به
com.azure.cosmos.examples.sample.synchronicity.MainClass
حيث يمكن أن يصبح مسارsample.synchronicity.MainClass ما يلي
- crudquickstart.sync.SampleCRUDQuickstart
- crudquickstart.async.SampleCRUDQuickstartAsync
- indexmanagement.sync.SampleIndexManagement
- indexmanagement.async.SampleIndexManagementAsync
- storedprocedure.sync.SampleStoredProcedure
- storedprocedure.async.SampleStoredProcedureAsync
- changefeed.SampleChangeFeedProcessor (Changefeed يحتوي على عينة متزامنة فقط، وليس نموذج متزامن.) ... وما إلى ذلك ...
إشعار
كل عينة مكتفية ذاتيًا؛ فهي تعين نفسها وتنظف بعد نفسها. تعمل النماذج على إصدار استدعاءات متعددة لإنشاء CosmosContainer أو CosmosAsyncContainer. في كل مرة يتم فيها ذلك، يتم فوترة الاشتراك لمدة ساعة واحدة من الاستخدام لمستوى الأداء للمجموعة التي تم إنشاؤها.
أمثلة قاعدة البيانات
تعرض ملفات Database CRUD Sampleللمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية. للتعرف على قواعد بيانات Azure Cosmos DB قبل تشغيل العينات التالية، راجع المقالة المفاهيمية للعمل مع قواعد البيانات والحاويات والعناصر .
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء قاعدة بيانات | CosmosClient.createDatabaseIfNotExists CosmosAsyncClient.createDatabaseIfNotExists |
| قراءة قاعدة البيانات عن طريق المعرف | CosmosClient.getDatabase CosmosAsyncClient.getDatabase |
| قراءة كل قواعد البيانات | CosmosClient.readAllDatabases CosmosAsyncClient.readAllDatabases |
| احذف قاعدة بيانات | CosmosDatabase.delete CosmosAsyncDatabase.delete |
أمثلة المجموعة
تعرض ملفات Collection CRUD Samples للمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية. للتعرف على مجموعات Azure Cosmos DB قبل تشغيل العينات التالية، راجع المقالة المفاهيمية للعمل مع قواعد البيانات والحاويات والعناصر .
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
| تغيير الأداء المهيئ للمجموعة | CosmosContainer.replaceThroughput CosmosAsyncContainer.replaceProvisionedThroughput |
| الحصول على مجموعة حسب ID | CosmosDatabase.getContainer CosmosAsyncDatabase.getContainer |
| قراءة جميع المجموعات في قاعدة بيانات | CosmosDatabase.readAllContainers CosmosAsyncDatabase.readAllContainers |
| حذف مجموعة | CosmosContainer.delete CosmosAsyncContainer.delete |
أمثلة مجموعة التحجيم التلقائي
للتعرّف على المزيد عن التحجيم التلقائي قبل تشغيل هذه النماذج، يمكنك إلقاء نظرة على هذه الإرشادات المتعلقة بتمكين التحجيم التلقائي في حسابك وفي قواعد البيانات والحاويات الخاصة بك.
تعرض ملفات نماذج قاعدة البيانات ذات التحجيم التلقائي للمزامنةوعدم المزامنة كيفية تنفيذ المهمة التالية.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء قاعدة بيانات بأقصى إنتاجية محددة باستخدام ميزة التحجيم التلقائي | CosmosClient.createDatabase CosmosAsyncClient.createDatabase |
تعرض ملفات نماذج مجموعة التحجيم التلقائي للمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة بأقصى معدل نقل محدد باستخدام ميزة التحجيم التلقائي | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
| تغيير الحد الأقصى لإنتاجية التحجيم التلقائي المهيئ في أي مجموعة | CosmosContainer.replaceThroughput CosmosAsyncContainer.replaceThroughput |
| قراءة تهيئة إنتاج مجموعة باستخدام التحجيم التلقائي | CosmosContainer.readThroughput CosmosAsyncContainer.readThroughput |
أمثلة لمجموعات التخزين التحليلي
توضح ملفات نماذج لمجموعات التخزين التحليلي CRUD للمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية. للتعرف على مجموعات Azure Cosmos DB قبل تشغيل العينات التالية، اقرأ عن Azure Cosmos DB Synapse وAnalytics Store.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
أمثلة العناصر
توضح ملفات نماذج المستند CRUD للمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية. للتعرف على مستندات Azure Cosmos DB قبل تشغيل العينات التالية، راجع المقالة المفاهيمية للعمل مع قواعد البيانات والحاويات والعناصر .
إشعار
يجب تحديد مفتاح قسم عند تنفيذ عمليات مقابل عنصر معين.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مستند | CosmosContainer.createItem CosmosAsyncContainer.createItem |
| اقرأ مستندًا بواسطة ID | CosmosContainer.readItem CosmosAsyncContainer.readItem |
| استعلام عن المستندات | CosmosContainer.queryItems CosmosAsyncContainer.queryItems |
| استبدل مستند | CosmosContainer.replaceItem CosmosAsyncContainer.replaceItem |
| حدث أو أدرج (Upsert) مستند | CosmosContainer.upsertItem CosmosAsyncContainer.upsertItem |
| حذف مستند | CosmosContainer.deleteItem CosmosAsyncContainer.deleteItem |
| استبدال مستند من خلال الفحص ETag الشرطي | CosmosItemRequestOptions.setIfMatchETag (مزامنة) CosmosItemRequestOptions.setIfMatchETag (عدم المزامنة) |
| اقرأ المستند فقط في حالة تغير المستند | CosmosItemRequestOptions.setIfNoneMatchETag (مزامنة) CosmosItemRequestOptions.setIfNoneMatchETag (عدم المزامنة) |
| تحديث جزئي للمستند | CosmosContainer.patchItem |
| تحديث مجمع للمستند | نماذج مجمعة |
| دفعة معاملات | عينات الدفعة |
فهرسة الأمثلة
يوضح ملف نماذج Collection CRUD كيفية إجراء المهام التالية. وللتعرف على الفهرسة في قاعدة بيانات Azure Cosmos قبل تشغيل النماذج الآتية، راجع المقالة المفاهيمية سياسات الفهرسة وأنواع الفهرسة ومسارات الفهرسة.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| تضمين مسارات مستندات محددة في الفهرس | IndexingPolicy.ExcludedPaths |
| استبعاد مسارات مستندات محددة من الفهرس | IndexingPolicy.ExcludedPaths |
| إنشاء فهرس مركب | IndexingPolicy.setCompositeIndexes CompositePath |
| إنشاء فهرس جيوفضائي | فهرسةPolicy.setSpatialIndexes SpatialSpec SpatialType |
للحصول على مزيد من المعلومات حول الفهرسة، راجع سياسات الفهرسة في خدمة Azure Cosmos DB.
أمثلة الاستعلام
توضح ملفات نماذج الاستعلام للمزامنةوعدم المزامنة كيفية تنفيذ المهام التالية باستخدام قواعد استعلام SQL. للتعرف على مرجع استعلام SQL في Azure Cosmos DB قبل تشغيل العينات التالية، راجع أمثلة على استعلام SQL لـ Azure Cosmos DB.
أمثلة عن تغذية التغييرات
يوضح ملف نموذج معالج موجز التغييرات كيفية تنفيذ المهام التالية. وللتعرّف على موجز التغييرات في خدمة Azure Cosmos DB قبل تشغيل النماذج التالية، راجع قراءة موجز التغييرات في Azure Cosmos DB ومعالج موجز التغيير.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| وظائف موجز التغييرات الأساسية | ChangeFeedProcessor.changeFeedProcessorBuilder |
| قراءة موجز التغييرات من البداية | ChangeFeedProcessorOptions.setStartFromBeginning() |
أمثلة برمجة من جانب الخادم
يوضح ملف نموذج الإجراء المخزّن كيفية تنفيذ المهام التالية. للتعرّف على برمجة جانب الخادم في Azure Cosmos DB قبل تشغيل العينات التالية، راجع الإجراءات المُخزّنة، والمشغّلات، والوظائف المعرّفة من قبل المستخدم.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء إجراء مخزّن | CosmosScripts.createStoredProcedure |
| قم بتنفيذ إجراء مخزن | CosmosStoredProcedure.execute |
| حذف إجراء مخزّن | CosmosStoredProcedure.delete |
الخطوات التالية
هل تحاول القيام بتخطيط السعة للترحيل إلى Azure Cosmos DB؟ يمكنك استخدام معلومات حول نظام مجموعة قاعدة البيانات الموجودة لديك لـ تخطيط السعة.
- في حال كان كل ما تعرفه هو عدد vcores والخوادم في مجموعة قاعدة البيانات الحالية، فاقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs
- إذا كان كل ما تعرفه هو عدد vcores والخوادم الموجودة في مجموعة قاعدة البيانات، اقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs