التشغيل السريع: مكتبة Azure Cosmos DB ل NoSQL ل Java
ينطبق على: NoSQL
ابدأ مع مكتبة عميل Azure Cosmos DB ل NoSQL ل Java للاستعلام عن البيانات في حاوياتك وتنفيذ العمليات الشائعة على العناصر الفردية. اتبع هذه الخطوات لنشر الحد الأدنى من الحل إلى البيئة الخاصة بك باستخدام Azure Developer CLI.
الوثائق | المرجعية لواجهة برمجة التطبيقات حزمة التعليمات البرمجية | المصدر لمكتبة (Maven) | Azure Developer CLI
المتطلبات الأساسية
- حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
- حساب GitHub
- حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
- Azure Developer CLI
- Docker Desktop
الإعداد
نشر حاوية تطوير هذا المشروع إلى البيئة الخاصة بك. ثم استخدم Azure Developer CLI (azd
) لإنشاء حساب Azure Cosmos DB ل NoSQL ونشر نموذج تطبيق حاوية. يستخدم نموذج التطبيق مكتبة العميل لإدارة البيانات النموذجية وإنشاءها وقراءتها والاستعلام عن البيانات.
هام
تتضمن حسابات GitHub استحقاق التخزين والساعات الأساسية دون أي تكلفة. لمزيد من المعلومات، راجع التخزين المضمن والساعات الأساسية لحسابات GitHub.
افتح محطة طرفية في الدليل الجذر للمشروع.
المصادقة على Azure Developer CLI باستخدام
azd auth login
. اتبع الخطوات المحددة بواسطة الأداة للمصادقة على CLI باستخدام بيانات اعتماد Azure المفضلة لديك.azd auth login
استخدم
azd init
لتهيئة المشروع.azd init --template cosmos-db-nosql-java-quickstart
إشعار
يستخدم هذا التشغيل السريع مستودع GitHub لقالب azure-samples/cosmos-db-nosql-java-quickstart . سيقوم Azure Developer CLI تلقائيا باستنساخ هذا المشروع إلى جهازك إذا لم يكن موجودا بالفعل.
أثناء التهيئة، قم بتكوين اسم بيئة فريد.
تلميح
سيتم أيضا استخدام اسم البيئة كاسم مجموعة الموارد الهدف. لهذا التشغيل السريع، ضع في اعتبارك استخدام
msdocs-cosmos-db
.انشر حساب Azure Cosmos DB باستخدام
azd up
. تنشر قوالب Bicep أيضا نموذج تطبيق ويب.azd up
أثناء عملية التوفير، حدد اشتراكك والموقع المطلوب. انتظر حتى اكتمال عملية التوفير. قد تستغرق العملية حوالي خمس دقائق.
بمجرد توفير موارد 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.
استخدم عنوان URL في وحدة التحكم للانتقال إلى تطبيق الويب الخاص بك في المستعرض. لاحظ إخراج التطبيق قيد التشغيل.
تثبيت مكتبة العميل
تتوفر مكتبة العميل من خلال Maven، كحزمة azure-spring-data-cosmos
.
انتقل إلى
/src/web
المجلد وافتح ملف pom.xml .إذا لم يكن موجودا بالفعل، أضف إدخالا للحزمة
azure-spring-data-cosmos
.<dependency> <groupId>com.azure</groupId> <artifactId>azure-spring-data-cosmos</artifactId> </dependency>
أضف أيضا تبعية أخرى للحزمة
azure-identity
إذا لم تكن موجودة بالفعل.<dependency> <groupId>com.azure</groupId> <artifactId>azure-identity</artifactId> </dependency>
نموذج الكائن
Name | الوصف |
---|---|
EnableCosmosRepositories |
هذا النوع هو مصمم أسلوب يستخدم لتكوين مستودع للوصول إلى Azure Cosmos DB ل NoSQL. |
CosmosRepository |
هذه الفئة هي فئة العميل الأساسية وتستخدم لإدارة البيانات داخل حاوية. |
CosmosClientBuilder |
هذه الفئة هي مصنع يستخدم لإنشاء عميل يستخدمه المستودع. |
Query |
هذا النوع هو مصمم أسلوب يستخدم لتحديد الاستعلام الذي ينفذه المستودع. |
أمثلة على التعليمات البرمجية
يستخدم نموذج التعليمات البرمجية في القالب قاعدة بيانات باسم cosmicworks
وحاوية باسم products
. products
تحتوي الحاوية على تفاصيل مثل الاسم والفئة والكمية والمعرف الفريد وعلامة البيع لكل منتج. تستخدم الحاوية الخاصية /category
كمفتاح قسم منطقي.
مصادقة العميل
يجب التصريح بطلبات التطبيق إلى معظم خدمات Azure. DefaultAzureCredential
استخدم النوع كطريقة مفضلة لتنفيذ اتصال بدون كلمة مرور بين تطبيقاتك وAzure Cosmos DB ل NoSQL. DefaultAzureCredential
يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل.
هام
يمكنك أيضا تخويل الطلبات إلى خدمات Azure باستخدام كلمات المرور أو سلسلة الاتصال أو بيانات الاعتماد الأخرى مباشرة. ومع ذلك، ينبغي استخدام هذا النهج بحذر. يجب أن يكون المطورون مجتهدا لعدم كشف هذه الأسرار في موقع غير آمن. يمكن لأي شخص لديه حق الوصول إلى كلمة المرور أو المفتاح السري المصادقة على خدمة قاعدة البيانات. DefaultAzureCredential
يوفر مزايا إدارة وأمان محسنة على مفتاح الحساب للسماح بالمصادقة بدون كلمة مرور دون مخاطر تخزين المفاتيح.
أولا، ينشئ هذا النموذج فئة جديدة ترث من AbstractCosmosConfiguration
لتكوين الاتصال ب Azure Cosmos DB ل NoSQL.
@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
داخل فئة التكوين، ينشئ هذا النموذج مثيلا جديدا من CosmosClientBuilder
الفئة ويكون المصادقة باستخدام مثيل DefaultAzureCredential
.
@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
DefaultAzureCredential azureTokenCredential = new DefaultAzureCredentialBuilder()
.build();
return new CosmosClientBuilder()
.endpoint(uri)
.credential(azureTokenCredential);
}
الحصول على قاعدة بيانات
في فئة التكوين، ينفذ النموذج أسلوبا لإرجاع اسم قاعدة البيانات الموجودة المسماة cosmicworks
.
@Override
protected String getDatabaseName() {
return "cosmicworks";
}
الحصول على حاوية
Container
استخدم مصمم الأسلوب لتكوين فئة لتمثيل العناصر في حاوية. تأليف الفئة لتضمين جميع الأعضاء الذين تريد تسلسلهم في JSON. في هذا المثال، يحتوي النوع على معرف فريد وحقول للفئة والاسم والكمية والسعر والخلوص.
@Container(containerName = "products", autoCreateContainer = false)
public class Item {
private String id;
private String name;
private Integer quantity;
private Boolean sale;
@PartitionKey
private String category;
إنشاء عنصر
إنشاء عنصر في الحاوية باستخدام repository.save
.
Item item = new Item(
"70b63682-b93a-4c77-aad2-65501347265f",
"gear-surf-surfboards",
"Yamba Surfboard",
12,
false
);
Item created_item = repository.save(item);
قراءة عنصر
تنفيذ عملية قراءة نقطة باستخدام كل من المعرف الفريد (id
) وحقول مفتاح القسم. استخدم repository.findById
لاسترداد العنصر المحدد بكفاءة.
PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("70b63682-b93a-4c77-aad2-65501347265f", partitionKey);
if (existing_item.isPresent()) {
// Do something
}
عناصر الاستعلام
قم بإجراء استعلام عبر عناصر متعددة في حاوية عن طريق تعريف استعلام في واجهة المستودع. يستخدم Query
هذا النموذج مزخرف الأسلوب لتعريف أسلوب ينفذ هذا الاستعلام ذات المعلمات:
SELECT * FROM products p WHERE p.category = @category
@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {
@Query("SELECT * FROM products p WHERE p.category = @category")
List<Item> getItemsByCategory(@Param("category") String category);
}
إحضار كافة نتائج الاستعلام باستخدام repository.getItemsByCategory
. التكرار الحلقي عبر نتائج الاستعلام.
List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
// Do something
}