البرنامج التعليمي: إنشاء واجهة برمجة تطبيقات لحساب Cassandra في Azure Cosmos DB باستخدام تطبيق Java لتخزين بيانات المفتاح/القيمة

مقالة
08/15/2024

ينطبق على: كاساندرا

بصفتك مطورًا، قد يكون لديك تطبيقات تستخدم أزواج المفتاح/القيمة. يمكنك استخدام واجهة برمجة تطبيقات لحساب Cassandra في Azure Cosmos DB لتخزين بيانات المفتاح/القيمة. يصف هذا البرنامج التعليمي كيفية استخدام تطبيق Java لإنشاء واجهة برمجة تطبيقات لحساب Cassandra في Azure Cosmos DB، وإضافة قاعدة بيانات (تسمى أيضا مساحة مفتاح)، وإضافة جدول. يستخدم تطبيق Java برنامج تشغيل Java لإنشاء قاعدة بيانات مستخدم تحتوي على تفاصيل مثل معرف المستخدم واسم المستخدم ومدينة المستخدم.

يشمل البرنامج التعليمي المهام التالية:

إنشاء حساب قاعدة بيانات Cassandra
الحصول على سلسلة اتصال الحساب
إنشاء مشروع مخضرم والتبعيات
إضافة قاعدة بيانات وجدول
تشغيل التطبيق

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

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.
احصل على أحدث إصدار من Java Development Kit (JDK).
قم بتنزيل وتثبيت أرشيف Maven الثنائي.
- على Ubuntu، يمكنك تشغيل apt-get install maven لتثبيت Maven.

أنشئ «حساب قاعدة البيانات».

من قائمة مدخل Azure أو الصفحة الرئيسية، حدد Create a resource.
في الصفحة جديد، ابحث عن Azure Cosmos DB وحدده.
في صفحة Azure Cosmos DB ، حدد Create.
في صفحة API ، حدد Create ضمن قسم Cassandra .

تحدد واجهة API نوع الحساب المقرر إنشاؤه. يوفر Azure Cosmos DB خمس واجهات برمجة تطبيقات: NoSQL لقواعد بيانات المستندات، وGremlin لقواعد بيانات الرسم البياني، وMongoDB لقواعد بيانات المستندات، وAzure Table، وCassandra. يجب إنشاء حساب منفصل لكل API.

حدد Cassandra، لأنه في هذا التشغيل السريع تقوم بإنشاء جدول يعمل مع واجهة برمجة التطبيقات ل Cassandra.

تعرف على المزيد حول واجهة برمجة التطبيقات ل Cassandra.

في صفحة إنشاء حساب Azure Cosmos DB، أدخل الإعدادات الأساسية لحساب Azure Cosmos DB الجديد.

الإعداد	قيمة	‏‏الوصف
الاشتراك	اشتراكك	حدد اشتراك Azure الذي تريد استخدامه لحساب Azure Cosmos DB هذا.
مجموعة الموارد	إنشاء و الجديدة في ثم أدخل نفس اسم الحساب	حدد إنشاء جديد. ثم أدخل اسم مجموعة موارد جديدة لحسابك. للبساطة، استخدم نفس اسم حساب Azure Cosmos DB.
اسم الحساب	أدخل اسماً فريداً	أدخل اسماً فريداً لتعريف حساب Azure Cosmos DB الخاص بك. سيكون حساب URI الخاص بك cassandra.cosmos.azure.com وسيُلحق باسم حسابك الفريد. لا يمكن أن يستخدم اسم الحساب سوى الأحرف الصغيرة والأرقام والواصلات (-)، ويجب أن يتراوح طولها بين 3 و31 حرفًا.
الموقع	المنطقة الأقرب إلى مستخدميك	حدد موقعًا جغرافيًّا لاستضافة حساب Azure Cosmos DB. استخدم الموقع الأقرب إلى المستخدمين لمنحهم أسرع وصول إلى البيانات.
وضع السعة	معدل النقل المقدم أو بلا خادم	حدد "Provisioned throughput" لإنشاء حساب في وضع معدل النقل المتوفر. حدد Serverless لإنشاء حساب في وضع دون خادم.
تطبيق خصم طبقة Azure Cosmos DB المجاني	تطبيق أو عدم تطبيق	مع Azure Cosmos DB الطبقة الحرة، سوف تحصل على أول 1000 RU / ثانية و25 غيغابايت من التخزين مجانًا في حساب. تعرف على المزيد حول الطبقة المجانية.
ضع حدُا لمعدل نقل الحساب	حدد للحد من معدل نقل الحساب	وهذا مفيد إذا كنت تريد تحديد إجمالي معدل نقل الحساب إلى قيمة معينة.

إشعار

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

صفحة الحساب الجديدة ل Azure Cosmos DB ل Apache Cassandra

في علامة تبويب Global Distributionكوّن التفاصيل التالية. يمكنك ترك القيم الافتراضية لغرض هذه البداية السريعة:

الإعداد	قيمة	‏‏الوصف
التكرار الجغرافي	تعطيل	تمكين التوزيع العمومي على حسابك أو تعطيله عن طريق إقران منطقتك بمنطقة زوج. يمكنك إضافة المزيد من المناطق إلى حسابك لاحقًا.
كتابات متعددة المناطق	تعطيل	تتيح لك إمكانية الكتابة متعددة المناطق الاستفادة من الإنتاجية المقدمة لقواعد البيانات والحاويات الخاصة بك في جميع أنحاء العالم.
مجموعات التوافر	تعطيل	مناطق التوفر هي مواقع معزولة داخل منطقة Azure. تتكون كل منطقة من مركز بيانات واحد أو أكثر مزود بمصدر طاقة وتبريد وشبكات مستقلة.

إشعار

الخيارات التالية غير متوفرة إذا قمت بتحديد دون خادمباعتبارهاوضع السعة:

تطبيق خصم من الدرجة المجانية
Geo-redundancy
كتابات متعددة المناطق

اختياريًا يمكنك تكوين تفاصيل إضافية في علامات التبويب التالية:
- شبكة الاتصال - تكوين الوصول من شبكة اتصال ظاهرية.
- نهج النسخ الاحتياطي - تكوين نهج النسخ الاحتياطي الدوري أو المستمر.
- التشفير - استخدم إما مفتاحًا مُدارًا بواسطة الخدمة أو مفتاحًا مُدارًا من قِبل العميل.
- العلامات - العلامات هي أزواج الاسم/القيم التي تمكنك من تصنيف الموارد وعرض الفوترة الموحدة من خلال تطبيق نفس العلامة على موارد متعددة ومجموعات موارد متعددة.
حدد "Review + create".
راجع الإعدادات، ثم حدد Create. يستغرق إنشاء جهاز ظاهر بضع دقائق. انتظر حتى يتم عرض صفحة المدخل، اكتمل النشر.
حدد الانتقال إلى المورد للانتقال إلى صفحة حساب Azure Cosmos DB.

احصل على تفاصيل الاتصال بحسابك

احصل على معلومات سلسلة الاتصال من مدخل Microsoft Azure، وانسخها في ملف تكوين Java. تمكن سلسلة الاتصال تطبيقك من الاتصال بقاعدة البيانات المستضافة.

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

إنشاء المشروع والتبعيات

تتم استضافة مشروع نموذج Java الذي تستخدمه في هذه المقالة في GitHub. يمكنك تشغيل الخطوات في هذا المستند أو تنزيل العينة من مستودع azure-cosmos-db-cassandra-java-getting-started .

بعد تنزيل الملفات، قم بتحديث معلومات سلسلة الاتصال داخل java-examples\src\main\resources\config.properties الملف وتشغيلها.

cassandra_host=<FILLME_with_CONTACT POINT> 
cassandra_port = 10350 
cassandra_username=<FILLME_with_USERNAME> 
cassandra_password=<FILLME_with_PRIMARY PASSWORD>

استخدم الخطوات التالية لبناء العينة من البداية:

من المحطة الطرفية أو موجه الأوامر، قم بإنشاء مشروع Maven جديد يسمى Cassandra-demo.

mvn archetype:generate -DgroupId=com.azure.cosmosdb.cassandra -DartifactId=cassandra-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

cassandra-demo حدد موقع المجلد. باستخدام محرر نص، افتح pom.xml الملف الذي تم إنشاؤه.

أضف تبعيات Cassandra وأنشئ المكونات الإضافية المطلوبة من قبل مشروعك، كما هو موضح في ملف pom.xml .
ضمن cassandra-demo\src\main المجلد ، أنشئ مجلدا جديدا باسم resources. ضمن مجلد الموارد، أضف ملفي config.properties وlog4j.properties:
- يخزن ملف config.properties نقطة نهاية الاتصال والقيم الرئيسية لواجهة برمجة التطبيقات لحساب Cassandra.
- يحدد ملف log4j.properties مستوى التسجيل المطلوب للتفاعل مع واجهة برمجة التطبيقات ل Cassandra.
استعرض وصولا src/main/java/com/azure/cosmosdb/cassandra/ إلى المجلد. ضمن مجلد cassandra، أنشئ مجلدا آخر باسم utils. يخزن المجلد الجديد فئات الأداة المساعدة المطلوبة للاتصال بواجهة برمجة التطبيقات لحساب Cassandra.

أضف فئة CassandraUtils لإنشاء نظام المجموعة وفتح جلسات Cassandra وإغلاقها. يتصل نظام المجموعة بواجهة برمجة التطبيقات لحساب Cassandra في Azure Cosmos DB ويعيد جلسة عمل للوصول إليها. استخدم فئة التكوينات لقراءة معلومات سلسلة الاتصال من ملف config.properties.
يُنشئ نموذج Java قاعدة بيانات بمعلومات المستخدم مثل اسم المستخدم ومعرف المستخدم ومدينة المستخدم. تحتاج إلى تحديد أساليب الحصول والتعيين للوصول إلى تفاصيل المستخدم في الوظيفة الرئيسية.

أنشئ فئة User.java ضمن المجلد src/main/java/com/azure/cosmosdb/cassandra/ باستخدام أساليب الجلب والتعيين.

إضافة قاعدة بيانات وجدول

يصف هذا القسم كيفية إضافة قاعدة بيانات (مسافة مفتاح) وجدول باستخدام CQL.

ضمن src\main\java\com\azure\cosmosdb\cassandra المجلد ، أنشئ مجلدا جديدا باسم repository.

UserRepository إنشاء فئة Java وإضافة التعليمات البرمجية التالية إليها:

package com.azure.cosmosdb.cassandra.repository; 
import java.util.List; 
import com.datastax.driver.core.BoundStatement; 
import com.datastax.driver.core.PreparedStatement; 
import com.datastax.driver.core.Row; 
import com.datastax.driver.core.Session; 
import org.slf4j.Logger; 
import org.slf4j.LoggerFactory; 

/** 
 * Create a Cassandra session 
 */ 
public class UserRepository { 

    private static final Logger LOGGER = LoggerFactory.getLogger(UserRepository.class); 
    private Session session; 
    public UserRepository(Session session) { 
        this.session = session; 
    } 

    /** 
    * Create keyspace uprofile in cassandra DB 
     */ 

    public void createKeyspace() { 
         final String query = "CREATE KEYSPACE IF NOT EXISTS uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"; 
        session.execute(query); 
        LOGGER.info("Created keyspace 'uprofile'"); 
    } 

    /** 
     * Create user table in cassandra DB 
     */ 

    public void createTable() { 
        final String query = "CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)"; 
        session.execute(query); 
        LOGGER.info("Created table 'user'"); 
    } 
}

src\main\java\com\azure\cosmosdb\cassandra حدد موقع المجلد، وأنشئ مجلدا فرعيا جديدا باسم examples.

UserProfile إنشاء فئة Java. تحتوي هذه الفئة على الأسلوب الرئيسي الذي يستدعي الأسلوبين createKeyspace وcreateTable اللذين حددتهما سابقًا:

package com.azure.cosmosdb.cassandra.examples; 
import java.io.IOException; 
import com.azure.cosmosdb.cassandra.repository.UserRepository; 
import com.azure.cosmosdb.cassandra.util.CassandraUtils; 
import com.datastax.driver.core.PreparedStatement; 
import com.datastax.driver.core.Session; 
import org.slf4j.Logger; 
import org.slf4j.LoggerFactory; 

/** 
 * Example class which will demonstrate following operations on Cassandra Database on CosmosDB 
 * - Create Keyspace 
 * - Create Table 
 * - Insert Rows 
 * - Select all data from a table 
 * - Select a row from a table 
 */ 

public class UserProfile { 

    private static final Logger LOGGER = LoggerFactory.getLogger(UserProfile.class); 
    public static void main(String[] s) throws Exception { 
        CassandraUtils utils = new CassandraUtils(); 
        Session cassandraSession = utils.getSession(); 

        try { 
            UserRepository repository = new UserRepository(cassandraSession); 
            //Create keyspace in cassandra database 
            repository.createKeyspace(); 
            //Create table in cassandra database 
            repository.createTable(); 

        } finally { 
            utils.close(); 
            LOGGER.info("Please delete your table after verifying the presence of the data in portal or from CQL"); 
        } 
    } 
}

تشغيل التطبيق

افتح موجه الأوامر أو نافذة المحطة الطرفية. الصق مجموعة التعليمة البرمجية التالية.

هذه التعليمة البرمجية تغير الدليل (cd) إلى مسار المجلد حيث أنشأت المشروع. ثم يقوم بتشغيل mvn clean install الأمر لإنشاء الملف داخل المجلد cosmosdb-cassandra-examples.jar الهدف. أخيرًا، يقوم بتشغيل تطبيق Java.
```
cd cassandra-demo

mvn clean install 

java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile 
```
تعرض نافذة المحطة إخطارات بأن مفتاح المسافة والجدول قد تم إنشاؤهما.
الآن، في مدخل Microsoft Azure، افتح Data Explorer للتأكد من إنشاء مساحة المفاتيح والجدول.

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

في هذا البرنامج التعليمي، تعلمت كيفية إنشاء واجهة برمجة تطبيقات لحساب Cassandra في Azure Cosmos DB وقاعدة بيانات وجدول باستخدام تطبيق Java. يمكنك الآن المتابعة إلى المقالة التالية:

تحميل نموذج البيانات إلى واجهة برمجة التطبيقات لجدول Cassandra.

مشاركة عبر