Azure Cosmos DB SQL API: أمثلة على Java SDK v4
ينطبق على: 
واجهة برمجة تطبيقات SQL
هام
للتعرّف على المزيد حول Java SDK v4، يرجى الاطلاع على ملاحظات الإصدار بشأن Azure Cosmos DB Java SDK v4، ومستودع Maven، ونصائح أداء Azure Cosmos DB Java SDK v4، ودليل استكشاف الأخطاء وإصلاحها لـAzure Cosmos DB Java SDK v4. إذا كنت تستخدم حالياً إصداراً أقدم من v4، فراجع دليل الترحيل إلى Azure Cosmos DB Java SDK v4 للحصول على تعليمات حول الترقية إلى الإصدار v4.
هام
إذا لم يكن لديك اشتراك Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.
- يمكنك تنشيط مزايا المشتركين في Visual Studio: يمنحك اشتراكك في Visual Studio أرصدة كل شهر يمكنك استخدامها مع خدمات Azure المدفوعة.
يمكنك تجربة Azure Cosmos DB مجاناً دون اشتراك Azure، مجاناً و دون الحاجة إلى أي التزام. بدلاً من ذلك، يمكنك إنشاء حساب Azure Cosmos DB مجاني ، مع أول 400 RU/s و 5GB من التخزين مجانًا. يمكنك أيضًا استخدام محاكي 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، أو VSCODE) أو من سطر الأوامر باستخدام 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. في كل مرة يتم فيها ذلك، يتم فوترة الاشتراك لمدة ساعة واحدة من الاستخدام لمستوى الأداء للمجموعة التي تم إنشاؤها.
أمثلة قاعدة البيانات
يوضح ملف نماذج Database CRUD كيفية إجراء المهام التالية. للتعرف على قاعدة بيانات Azure Cosmos قبل تشغيل النماذج التالية، راجع المقالة المفاهيمية العمل مع قواعد البيانات، والحاويات، والعناصر.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء قاعدة بيانات | CosmosClient.createDatabaseIfNotExists |
| قراءة قاعدة بيانات حسب المعرّف | CosmosClient.getDatabase |
| قراءة كل قواعد البيانات | CosmosClient.readAllDatabases |
| حذف قاعدة بيانات | CosmosDatabase.delete |
أمثلة المجموعة
يوضح ملف نماذج Collection CRUD كيفية إجراء المهام التالية. للتعرف على مجموعات Azure Cosmos قبل تشغيل النماذج التالية، راجع المقالة المفاهيمية العمل مع قواعد البيانات، والحاويات، والعناصر.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة | CosmosDatabase.createContainerIfNotExists |
| تغيير الأداء المهيئ للمجموعة | CosmosContainer.replaceProvisionedThroughput |
| الحصول على مجموعة حسب ID | CosmosDatabase.getContainer |
| قراءة جميع المجموعات في قاعدة بيانات | CosmosDatabase.readAllContainers |
| حذف مجموعة | CosmosContainer.delete |
أمثلة مجموعة التحجيم التلقائي
للتعرّف على المزيد عن التحجيم التلقائي قبل تشغيل هذه النماذج، يمكنك إلقاء نظرة على هذه الإرشادات المتعلقة بتمكين التحجيم التلقائي في حسابك وفي قواعد البيانات والحاويات الخاصة بك.
يوضح ملف نماذج على autoscale Database CRUD كيفية إجراء المهام التالية.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء قاعدة بيانات بأقصى إنتاجية محددة باستخدام ميزة التحجيم التلقائي | CosmosClient.createDatabase ThroughputProperties.createAutoscaledThroughput |
يوضح ملف نماذج على autoscale Collection CRUD كيفية إجراء المهام التالية.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة بأقصى معدل نقل محدد باستخدام ميزة التحجيم التلقائي | CosmosDatabase.createContainerIfNotExists |
| تغيير الحد الأقصى لإنتاجية التحجيم التلقائي المهيئ في أي مجموعة | CosmosContainer.replaceThroughput |
| قراءة تهيئة إنتاج مجموعة باستخدام التحجيم التلقائي | CosmosContainer.readThroughput |
أمثلة لمجموعات التخزين التحليلي
يوضح ملف نماذج على Analytical storage Collection CRUD كيفية إجراء المهام التالية. للتعرف على مجموعات Azure Cosmos قبل تشغيل العينات التالية، اقرأ عن Azure Cosmos DB Synapse وAnalytical Store.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مجموعة | CosmosDatabase.createContainerIfNotExists |
أمثلة المستند
يوضح ملف Document CRUD Samples كيفية إجراء المهام التالية. للتعرف على مستندات Azure Cosmos قبل تشغيل النماذج التالية، راجع المقالة المفاهيمية العمل مع قواعد البيانات، والحاويات، والعناصر.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مستند | CosmosContainer.createItem |
| اقرأ مستندًا بواسطة ID | CosmosContainer.readItem |
| استعلام عن المستندات | CosmosContainer.queryItems |
| استبدال مستند | CosmosContainer.replaceItem |
| تحديث أو أدرج (Upsert) مستند | CosmosContainer.upsertItem |
| حذف مستند | CosmosContainer.deleteItem |
| استبدال مستند من خلال الفحص ETag الشرطي | AccessCondition.setType AccessCondition.setCondition |
| اقرأ المستند فقط في حالة تغير المستند | AccessCondition.setType AccessCondition.setCondition |
| تحديث جزئي للمستند | CosmosContainer.patchItem |
فهرسة الأمثلة
يوضح ملف نماذج Collection CRUD كيفية إجراء المهام التالية. للتعرف على الفهرسة في قاعدة بيانات Azure Cosmos قبل تشغيل النماذج التالية، راجع المقالات المفاهيمية لـ سياسات الفهرسة, أنواع الفهرسة، ومسارات الفهرسة.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| استبعاد مستند من الفهرس | ExcludedIndex IndexingPolicy |
| استخدام الفهرسة البطيئة | IndexingPolicy.IndexingMode |
| تضمين مسارات مستندات محددة في الفهرس | IndexingPolicy.IncludedPaths |
| استبعاد مسارات مستندات محددة من الفهرس | IndexingPolicy.ExcludedPaths |
| إنشاء فهرس مركب | IndexingPolicy.setCompositeIndexes CompositePath |
| فرض عملية مسح نطاق على مسار مفهرس مجزأ | FeedOptions.EnableScanInQuery |
| استخدام فهارس النطاقات على سلاسل | IndexingPolicy.IncludedPaths RangeIndex |
| إجراء تحويل فهرس | - |
| إنشاء فهرس جيوفضائي | IndexingPolicy.setSpatialIndexes SpatialSpec SpatialType |
للحصول على مزيد من المعلومات حول الفهرسة، راجع سياسات الفهرسة في خدمة Azure Cosmos DB.
أمثلة الاستعلام
يوضح ملف Query Samples كيفية القيام بالمهام التالية باستخدام قواعد استعلام SQL. للتعرّف على مرجع استعلام SQL في خدمة Azure Cosmos DB قبل تشغيل النماذج التالية، راجع نماذج استعلامات SQL لخدمة Azure Cosmos DB.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| استعلام عن كافة المستندات | CosmosContainer.queryItems |
| استعلام عن المساواة باستخدام == | CosmosContainer.queryItems |
| استعلام عن عدم المساواة باستخدام! = وNOT | CosmosContainer.queryItems |
| استعلام باستخدام مشغلي النطاق مثل >، <، >=، <= | CosmosContainer.queryItems |
| استعلام باستخدام عوامل تشغيل النطاق مقابل السلاسل | CosmosContainer.queryItems |
| استعلام باستخدام رتب حسب | CosmosContainer.queryItems |
| استعلام باستخدام التمييز | CosmosContainer.queryItems |
| استعلام باستخدام وظائف مجمعة | CosmosContainer.queryItems |
| التعامل مع المستندات الثانوية | CosmosContainer.queryItems |
| استعلام باستخدام علامات الربط داخل المستند | CosmosContainer.queryItems |
| استعلام باستخدام عوامل السلسلة، والرياضيات، والمصفوفات | CosmosContainer.queryItems |
| استعلام ذو معلمات SQL باستخدام SqlQuerySpec | CosmosContainer.queryItems |
| استعلام باستخدام الترحيل الصريح | CosmosContainer.queryItems |
| استعلام عن مجموعات مقسمة بالتوازي | CosmosContainer.queryItems |
| الاستعلام باستخدام مرتب حسب للمجموعات المقسمة | CosmosContainer.queryItems |
أمثلة لموجز التغييرات
يوضح ملف نموذج معالج موجز التغييرات كيفية تنفيذ المهام التالية. وللتعرّف على موجز التغييرات في خدمة Azure Cosmos DB قبل تشغيل النماذج التالية، راجع قراءة موجز التغييرات في Azure Cosmos DB ومعالج موجز التغيير.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| وظائف موجز التغييرات الأساسية | ChangeFeedProcessor.changeFeedProcessorBuilder |
| قراءة موجز التغيير من وقت محدد | ChangeFeedProcessor.changeFeedProcessorBuilder |
| قراءة موجز التغييرات من البداية | - |
أمثلة برمجة من جانب الخادم
يوضح ملف نموذج الإجراء المخزّن كيفية تنفيذ المهام التالية. للتعرّف على البرمجة من جانب الخادم في خدمة Azure Cosmos DB قبل تشغيل النماذج التالية، راجعالإجراءات المخزّنة والمشغّلات والوظائف المعرّفة بواسطة المستخدم.
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء إجراء مخزّن | CosmosScripts.createStoredProcedure |
| قم بتنفيذ إجراء مخزن | CosmosStoredProcedure.execute |
| حذف إجراء مخزّن | CosmosStoredProcedure.delete |
أمثلة إدارة المستخدم
يوضح ملف نموذج إدارة المستخدم كيفية القيام بالمهام التالية:
| المهمة | مرجع واجهة برمجة التطبيقات |
|---|---|
| إنشاء مستخدم | - |
| تعيين أذونات على مجموعة أو مستند | - |
| الحصول على قائمة بأذونات المستخدم | - |
الخطوات التالية
هل تحاول القيام بتخطيط السعة للترحيل إلى Azure Cosmos DB؟ يمكنك استخدام معلومات حول مجموعة قاعدة البيانات الموجودة لتخطيط السعة.
- إذا كان كل ما تعرفه هو عدد vcores والخوادم في مجموعة قاعدة البيانات الموجودة، فاقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs
- إذا كنت تعرف المعدلات النموذجية للطلب لحمل العمل الحالي في قاعدة بياناتك، فاقرأ عن تقدير وحدات الطلب باستخدام مخطط السعة من Azure Cosmos DB