التشغيل السريع: إنشاء تطبيق Java لإدارة Azure Cosmos DB لبيانات Apache Cassandra (برنامج تشغيل v4)

مقالة
08/15/2024

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

في هذا التشغيل السريع، يمكنك إنشاء Azure Cosmos DB لحساب Apache Cassandra، واستخدام تطبيق Cassandra Java المستنسخ من GitHub لإنشاء قاعدة بيانات Cassandra وحاوية باستخدام برامج تشغيل v4.x Apache Cassandra ل Java. Azure Cosmos DB عبارة عن خدمة قاعدة بيانات متعددة النماذج تتيح لك إنشاء قواعد بيانات المستندات والجدول والقيمة الرئيسية والرسم البياني والاستعلام عنها بسرعة مع إمكانات التوزيع العام والقياس الأفقي.

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

حساب Azure مع اشتراك نشط. أنشئ حسابًا مجانًا. أو جرب Azure Cosmos DB مجاناً بدون اشتراك Azure.
مجموعة التطوير المساعدة للغة Java للبرمجة (JDK) 8. وجّه متغير البيئة JAVA_HOME إلى المجلد الذي تم تثبيت JDK فيه.
أرشيف Maven ثنائي. على Ubuntu، شغل apt-get install maven لتثبيت Maven.
Git. على Ubuntu، شغل sudo apt-get install git لتثبيت Git.

إشعار

هذا تشغيل سريع بسيط يستخدم الإصدار 4 من برنامج التشغيل مفتوح المصدر Apache Cassandra. في معظم الحالات، يجب أن تكون قادرا على توصيل تطبيق Java تابع ل Apache Cassandra ب Azure Cosmos DB ل Apache Cassandra دون أي تغييرات على التعليمات البرمجية الموجودة لديك. ومع ذلك، نوصي بإضافة ملحق Java المخصص، الذي يتضمن النُّهج المخصصة لإعادة المحاولة وموازنة التحميل، بالإضافة إلى إعدادات الاتصال الموصى به، للحصول على تجربة عامة أفضل. يُخصص هذا لمعالجة تقييد المعدل والفشل على مستوى التطبيقات في Azure Cosmos DB عند الحاجة. يمكنك العثور على عينة شاملة تنفذ التمديد هنا.

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

قبل أن تتمكن من إنشاء قاعدة بيانات المستندات، تحتاج إلى إنشاء حساب Cassandra باستخدام Azure Cosmos DB.

من قائمة مدخل 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.

استنساخ نموذج التطبيق

الآن دعنا ننتقل إلى العمل مع التعليمة البرمجية. لنقم باستنساخ تطبيق Cassandra من GitHub، وتعيين سلسلة الاتصال، وتشغيله. سترى مدى سهولة العمل مع البيانات برمجيًا.

افتح موجه الأوامر. أنشئ مجلدًا جديدًا باسم git-samples. ثم أغلق موجه الأوامر.
```
md "C:\git-samples"
```
افتح نافذة git طرفية، مثل git bash، واستخدم الأمر cd للتغيير إلى المجلد الجديد لتثبيت عينة التطبيق.
```
cd "C:\git-samples"
```
قم بتشغيل الأمر التالي لاستنساخ مستودع النموذج. يقوم هذا الأمر بإنشاء نسخة من نموذج التطبيق على جهاز الكمبيوتر الخاص بك.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
```

مراجعة الرمز

هذه الخطوة اختيارية. إذا كنت مهتمًا بمعرفة كيفية إنشاء التعليمات البرمجية لموارد قاعدة البيانات، فإنه يمكنك مراجعة الأجزاء التالية. أو يمكنك تخطي هذا الأمر والمتابعة إلى تحديث سلسلة اتصالك. هذه القصاصات البرمجية مأخوذة جميعها من الملف src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

CqlSession يتصل ب Azure Cosmos DB ل Apache Cassandra ويعيد جلسة للوصول (Clusterالكائن من برنامج تشغيل v3 قديم الآن). تم تعيين مضيف Cassandra والمنفذ واسم المستخدم وكلمة المرور باستخدام صفحة سلسلة الاتصال في مدخل Microsoft Azure.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

القصاصات البرمجية التالية من الملف src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

إسقاط مساحة المفتاح إذا كانت موجودة مسبقًا من تشغيل سابق.

public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

يتم إنشاء مفتاح جديد.

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

يتم إنشاء جدول جديد.

  public void createTable() {
      String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
      session.execute(query);
      LOGGER.info("Created table '"+table+"'");
  }

أدرج كيانات المستخدمين باستخدام كائن عبارة معد مسبقًا.

public String prepareInsertStatement() {
    final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
    return insertStatement;
}

public void insertUser(String preparedStatement, int id, String name, String city) {
    PreparedStatement prepared = session.prepare(preparedStatement);
    BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
    session.execute(bound);
}

استعلم للحصول على جميع معلومات المستخدم.

public void selectAllUsers() {
    final String query = "SELECT * FROM "+keyspace+"."+table+"";
    List<Row> rows = session.execute(query).all();

    for (Row row : rows) {
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
}

استعلم للحصول على معلومات مستخدم واحد.

public void selectUser(int id) {
    final String query = "SELECT * FROM "+keyspace+"."+table+" where user_id = 3";
    Row row = session.execute(query).one();

    LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
}

تحديث سلسلة الاتصال

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

في حسابك في Azure Cosmos DB في مدخل Azure، حدد سلسلة الاتصال.
استخدم الزر الموجود على الجانب الأيمن من الشاشة لنسخ القيمة CONTACT POINT.
افتح الملف config.properties من المجلد C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.
ألصق قيمة نقطة الاتصال من المدخل عبر <Cassandra endpoint host> على السطر 2.

يجب أن يبدو السطر 2 من config.properties الآن مشابهًا لـ

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
عُد إلى المدخل وانسخ قيمة USERNAME. ألصق القيمة USERNAME من المدخل عبر <cassandra endpoint username> على السطر 4.

يجب أن يبدو السطر 4 من config.properties الآن مشابهًا

cassandra_username=cosmos-db-quickstart
عُد إلى المدخل وانسخ القيمة PASSWORD. ألصق القيمة PASSWORD من المدخل عبر <cassandra endpoint password> على السطر 5.

يجب أن يبدو السطر 5 من config.properties الآن مشابهًا

cassandra_password=2Ggkr662ifxz2Mg...==
في السطر 6، إذا كنت ترغب في استخدام شهادة TLS/SSL معينة، فعليك استبدال <SSL key store file location> بموقع شهادة TLS/SSL. إذا لم يتم تقديم قيمة، فسيتم استخدام شهادة JDK المثبتة على <JAVA_HOME>/jre/lib/security/cacerts.
إذا غيرت السطر 6 لاستخدام شهادة TLS/SSL معينة، فعليك تحديث السطر 7 لاستخدام كلمة المرور لهذه الشهادة.
لاحظ أنك ستحتاج إلى إضافة المنطقة الافتراضية (على سبيل المثالWest US) لنقطة الاتصال، على سبيل المثال.

region=West US

وذلك لأن برنامج تشغيل v.4x لا يسمح إلا بوحدة واحدة محلية للتحكم في المجال أن تقترن مع نقطة الاتصال. إذا كنت تريد إضافة منطقة أخرى غير المنطقة الافتراضية (وهي المنطقة التي تم منحها عند إنشاء حساب Azure Cosmos DB لأول مرة)، فستحتاج إلى استخدام اللاحقة الإقليمية عند إضافة نقطة اتصال، على سبيل المثال host-westus.cassandra.cosmos.azure.com.
احفظ الملف config.properties.

تشغيل تطبيق Java

في نافذة المحطة الطرفية git، cd إلى المجلد azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
في نافذة المحطة الطرفية git، استخدم الأمر التالي لإنشاء الملف cosmosdb-cassandra-examples.jar.
```
mvn clean install
```
في نافذة Git الطرفية، شغّل الأوامر التالية لبدء تطبيق Java.
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
تعرض نافذة المحطة إخطارات بأن مفتاح المسافة والجدول قد تم إنشاؤهما. ثم تقوم بتحديد جميع المستخدمين في الجدول وإرجاعهم وتعرض الإخراج، ثم تحدد صفًّا حسب المعرف وتعرض القيمة.

اضغط Ctrl+C لإيقاف تنفيذ البرنامج وإغلاق نافذة وحدة التحكم.
في مدخل Microsoft Azure، افتح Data Explorer للاستعلام عن هذه البيانات الجديدة، وتعديلها، والعمل عليها.

مراجعة اتفاقيات مستوى الخدمة في مدخل Azure

يراقب مدخل Azure معدل نقل حساب Azure Cosmos DB والتخزين والتوافر وزمن الانتقال والاتساق. المخططات الخاصة بالمقاييس المقترنة بـ اتفاقية مستوى خدمة Azure Cosmos DB (SLA) تعرض قيمة اتفاقية مستوى الخدمة مقارنة بالأداء الفعلي. هذه المجموعة من المقاييس تجعل مراقبة اتفاقيات مستوى الخدمة الخاصة بك شفافة.

لمراجعة المقاييس واتفاقيات مستوى الخدمة:

حدد Metrics في قائمة التنقل لحساب Azure Cosmos DB.
حدد علامة تبويب مثل زمن الانتقال، وحدد إطارًا زمنيًا على اليسار. قارن الأسطر الفعلية واتفاقية مستوى الخدمة على المخططات.
راجع المقاييس في علامات التبويب الأخرى.

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

عند الانتهاء من تطبيقك وحساب Azure Cosmos DB، يمكنك حذف موارد Azure التي أنشأتها حتى لا تتحمل المزيد من الرسوم. لحذف الموارد:

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

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

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

استيراد بيانات Cassandra إلى Azure Cosmos DB

مشاركة عبر

التشغيل السريع: إنشاء تطبيق Java لإدارة Azure Cosmos DB لبيانات Apache Cassandra (برنامج تشغيل v4)

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

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

استنساخ نموذج التطبيق

مراجعة الرمز

تحديث سلسلة الاتصال

تشغيل تطبيق Java

مراجعة اتفاقيات مستوى الخدمة في مدخل Azure

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

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

الملاحظات

الموارد الإضافية