التشغيل السريع: Azure Cosmos DB لمكتبة عميل Apache Cassandra ل Java

ينطبق على: ✅ Apache Cassanda

Important

هل تبحث عن حل قاعدة بيانات للسيناريوهات عالية النطاق مع اتفاقية مستوى خدمة التوفر (SLA) 99.999% والتحجيم التلقائي الفوري وتجاوز الفشل التلقائي عبر مناطق متعددة؟ ضع في اعتبارك Azure Cosmos DB ل NoSQL.

هل تتطلع إلى ترحيل تطبيق Apache Cassandra موجود؟ ضع في اعتبارك مثيل Azure المدار ل Apache Cassandra.

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

الوثائق | التعليمات البرمجية | المصدر للمكتبةحزمة (Maven)

Prerequisites

اشتراك Azure
- في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

أحدث إصدار من Azure CLI في Azure Cloud Shell.
- إذا كنت تفضل تشغيل أوامر مرجع CLI محليا، فقم بتسجيل الدخول إلى Azure CLI باستخدام az login الأمر .

Java 21 أو أحدث

الإعداد

أولا، إعداد الحساب وبيئة التطوير لهذا الدليل. يرشدك هذا القسم خلال عملية إنشاء حساب، والحصول على بيانات الاعتماد الخاصة به، ثم إعداد بيئة التطوير الخاصة بك.

إنشاء حساب

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

Azure CLI
مدخل Microsoft Azure

إذا لم يكن لديك بالفعل مجموعة موارد مستهدفة az group create ، فاستخدم الأمر لإنشاء مجموعة موارد جديدة في اشتراكك.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create استخدم الأمر لإنشاء Azure Cosmos DB جديد لحساب Apache Cassandra مع الإعدادات الافتراضية.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

إنشاء مساحة مفتاح جديدة باستخدام az cosmosdb cassandra keyspace create المسمى cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

إنشاء كائن JSON جديد لتمثيل المخطط الخاص بك باستخدام أمر Bash متعدد الأسطر. ثم استخدم az cosmosdb cassandra table create الأمر لإنشاء جدول جديد باسم products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

سجّل الدخول إلى مدخل Azure (https://portal.azure.com).
أدخل Azure Cosmos DB في شريط البحث العمومي.
ضمن الخدمات، حدد Azure Cosmos DB.
في جزء Azure Cosmos DB ، حدد Create، ثم Azure Cosmos DB ل Apache Cassandra ضمن علامة التبويب Others .
حدد Request unit (RU) database account لنوع الحساب.

ضمن جزء Basics ، قم بتكوين الخيارات التالية، ثم حدد Review + create:

	Value
نوع حمل العمل	Learning
Subscription	حدد اشتراكك في Azure.
مجموعة الموارد	إنشاء مجموعة موارد جديدة أو تحديد مجموعة موارد موجودة
اسم الحساب	توفير اسم فريد عالميا
مناطق التوفر	Disable
Location	تحديد منطقة Azure مدعومة لاشتراكك

Tip

يمكنك ترك أي خيارات غير محددة لقيمها الافتراضية. يمكنك أيضا تكوين الحساب للحد من إجمالي معدل نقل الحساب إلى 1000 وحدة طلب في الثانية (RU/s) أو تمكين المستوى المجاني لتقليل التكاليف.

في جزء Review + create ، انتظر حتى ينتهي التحقق من صحة حسابك بنجاح، ثم حدد Create.
ينتقل المدخل تلقائيا إلى جزء النشر . انتظر حتى يكتمل التوزيع.
بمجرد اكتمال النشر، حدد Go to resource للانتقال إلى واجهة برمجة التطبيقات الجديدة لحساب Apache Cassandra.
في قائمة الموارد، حدد خيار مستكشف البيانات .
في Data Explorer، حدد + New Table.

في مربع الحوار إضافة جدول، قم بتكوين الخيارات التالية، ثم حدد موافق:

	Value
مساحة المفاتيح	إنشاء جديد
اسم مساحة المفاتيح	`cosmicworks`
اسم الجدول	`product`
مخطط الجدول	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Tip

يمكنك ترك أي خيارات غير محددة لقيمها الافتراضية.

الحصول على بيانات الاعتماد

الآن، احصل على كلمة المرور لمكتبة العميل لاستخدامها لإنشاء اتصال بالحساب الذي تم إنشاؤه مؤخرا.

Azure CLI
مدخل Microsoft Azure

استخدم az cosmosdb show للحصول على نقطة الاتصال واسم المستخدم للحساب.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

سجل قيمة خصائص contactPoint و username من إخراج الأوامر السابقة. قيم هذه الخصائص هي نقطة الاتصالواسم المستخدم الذي تستخدمه لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

استخدمه az cosmosdb keys list للحصول على مفاتيح الحساب.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

سجل قيمة الخاصية primaryMasterKey من إخراج الأوامر السابقة. قيمة هذه الخاصية هي كلمة المرور التي تستخدمها لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

إعداد بيئة التطوير

ثم قم بتكوين بيئة التطوير الخاصة بك مع مشروع جديد ومكتبة العميل. هذه الخطوة هي آخر شرط أساسي مطلوب قبل الانتقال إلى بقية هذا الدليل.

ابدأ في دليل فارغ.

إنشاء مشروع وحدة تحكم Java جديد باستخدام Maven.

mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

استيراد الحزمة java-driver-core من Maven. أضف هذا القسم إلى ملف pom.xml الخاص بك.

<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>[4.,)</version>
</dependency>

افتح الملف /console/src/main/java/quickstart/App.java .

لاحظ لغة تطبيق Java الحالية.

package quickstart;

/**
 * Hello world!
 *
 */
public class App 
{
    public static void main( String[] args )
    {
        System.out.println( "Hello World!" );
    }
}

إزالة التعليقات وإخراج وحدة التحكم من المتداول. كتلة التعليمات البرمجية هذه هي نقطة البداية لبقية هذا الدليل.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
java.security.NoSuchAlgorithmException استيراد مساحة الاسم.
```
import java.security.NoSuchAlgorithmException;
```
قم بتحديث main توقيع الأسلوب للإشارة إلى أنه قد يطرح الاستثناء NoSuchAlgorithmException .
```
public static void main(String[] args) throws NoSuchAlgorithmException
{    
}
```
Important

تفترض الخطوات المتبقية في هذا الدليل أنك تضيف التعليمات البرمجية main الخاصة بك داخل الأسلوب .
أنشئ المشروع.
```
mvn compile
```

نموذج الكائن

	Description
`CqlSession`	يمثل اتصالا محددا بمجموعة
`PreparedStatement`	يمثل عبارة CQL المحوسبة مسبقا التي يمكن تنفيذها عدة مرات بكفاءة
`BoundStatement`	يمثل عبارة معدة مع معلمات مرتبطة
`Row`	يمثل صفا واحدا من نتيجة استعلام

مصادقة العميل

ابدأ بمصادقة العميل باستخدام بيانات الاعتماد التي تم جمعها مسبقا في هذا الدليل.

افتح الملف /console/src/main/java/quickstart/App.java في بيئة التطوير المتكاملة (IDE).

استيراد الأنواع التالية:

java.net.InetSocketAddress
javax.net.ssl.SSLContext
com.datastax.oss.driver.api.core.CqlIdentifier
com.datastax.oss.driver.api.core.CqlSession
com.datastax.oss.driver.api.core.cql.BoundStatement
com.datastax.oss.driver.api.core.cql.PreparedStatement
com.datastax.oss.driver.api.core.cql.ResultSet
com.datastax.oss.driver.api.core.cql.Row

import java.net.InetSocketAddress;    

import javax.net.ssl.SSLContext;

import com.datastax.oss.driver.api.core.CqlIdentifier;
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.BoundStatement;
import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;

إنشاء متغيرات سلسلة لبيانات الاعتماد التي تم جمعها مسبقا في هذا الدليل. قم بتسمية المتغيرات usernameو passwordو.contactPoint قم أيضا بإنشاء متغير سلسلة باسم region لمركز البيانات المحلي.
```
String username = "<username>";
String password = "<password>";
String contactPoint = "<contact-point>";
```
إنشاء متغير سلسلة آخر للمنطقة التي قمت فيها بإنشاء Azure Cosmos DB لحساب Apache Cassandra. قم بتسمية هذا المتغير region.
```
String region = "<region>";
```
إنشاء كائن SSLContext للتأكد من أنك تستخدم بروتوكول أمان طبقة النقل (TLS).
```
SSLContext sslContext = SSLContext.getDefault();
```
إنشاء كائن جديد CqlSession باستخدام بيانات الاعتماد ومتغيرات التكوين التي تم إنشاؤها في الخطوات السابقة. تعيين نقطة الاتصال ومركز البيانات المحلي وبيانات اعتماد المصادقة ومساحة المفاتيح وسياق أمان طبقة النقل (TLS).
```
CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress(contactPoint, 10350))
    .withLocalDatacenter(region)
    .withAuthCredentials(username, password)
    .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
    .withSslContext(sslContext)
    .build();
```

Warning

تم تعطيل التحقق الكامل من أمان طبقة النقل (TLS) في هذا الدليل لتبسيط المصادقة. بالنسبة إلى عمليات نشر الإنتاج، قم بتمكين التحقق من الصحة بالكامل.

بيانات Upsert

بعد ذلك، قم بزيادة البيانات الجديدة في جدول. يضمن Upserting إنشاء البيانات أو استبدالها بشكل مناسب اعتمادا على ما إذا كانت نفس البيانات موجودة بالفعل في الجدول.

تعريف فئة جديدة باسم Product مع حقول مطابقة للجدول الذي تم إنشاؤه مسبقا في هذا الدليل.

class Product {
    public String id;
    public String name;
    public String category;
    public int quantity;
    public boolean clearance;

    public Product(String id, String name, String category, int quantity, boolean clearance) {
        this.id = id;
        this.name = name;
        this.category = category;
        this.quantity = quantity;
        this.clearance = clearance;
    }

    @Override
    public String toString() {
        return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                id, name, category, quantity, clearance);
    }
}

Tip

في Java، يمكنك إنشاء هذا النوع في ملف آخر أو إنشائه في نهاية الملف الموجود.

إنشاء كائن جديد من النوع Product. تخزين الكائن في متغير يسمى product.

Product product = new Product(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "Yamba Surfboard",
    "gear-surf-surfboards",
    12,
    false
);

إنشاء متغير سلسلة جديد باسم insertQuery باستخدام استعلام لغة استعلام Cassandra (CQL) لإدراج صف جديد.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

قم بإعداد عبارة الإدراج وربط خصائص المنتج كمعلمات.

PreparedStatement insertStmt = session.prepare(insertQuery);
BoundStatement boundInsert = insertStmt.bind(
    product.id,
    product.name,
    product.category,
    product.quantity,
    product.clearance
);

رفع المنتج عن طريق تنفيذ العبارة المنضمة.
```
session.execute(boundInsert);
```

قراءة البيانات

بعد ذلك، اقرأ البيانات التي تم إدراجها مسبقا في الجدول.

إنشاء متغير سلسلة جديد باسم readQuery مع استعلام CQL يطابق العناصر مع نفس id الحقل.
```
String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
إنشاء متغير سلسلة باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

قم بإعداد العبارة وربط حقل المنتج id كمعلمة.

PreparedStatement readStmt = session.prepare(readQuery);
BoundStatement boundRead = readStmt.bind(id);

قم بتنفيذ العبارة المنضمة وتخزين النتيجة في متغير يسمى readResult.
```
ResultSet readResult = session.execute(boundRead);
```

استرداد الصف الأول من مجموعة النتائج وتعيينه إلى كائن Product إذا تم العثور عليه.

Row row = readResult.one();
Product matchedProduct = new Product(
    row.getString("id"),
    row.getString("name"),
    row.getString("category"),
    row.getInt("quantity"),
    row.getBoolean("clearance")
);

بيانات الاستعلام

الآن، استخدم استعلاما للعثور على كافة البيانات التي تطابق عامل تصفية معين في الجدول.

إنشاء متغير سلسلة جديد باسم findQuery مع استعلام CQL يطابق العناصر مع نفس category الحقل.
```
String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
```
إنشاء متغير سلسلة باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.
```
String category = "gear-surf-surfboards";
```

قم بإعداد العبارة وربط فئة المنتج كمعلمة.

PreparedStatement findStmt = session.prepare(findQuery);
BoundStatement boundFind = findStmt.bind(category);

قم بتنفيذ العبارة المنضمة وتخزين النتيجة في متغير يسمى findResults.
```
ResultSet results = session.execute(boundFind);
```

تكرار نتائج الاستعلام وتعيين كل صف إلى كائن Product .

for (Row result : results) {
    Product queriedProduct = new Product(
        result.getString("id"),
        result.getString("name"),
        result.getString("category"),
        result.getInt("quantity"),
        result.getBoolean("clearance")
    );
    // Do something here with each result
}

إغلاق جلسة العمل

في Java، يطلب منك إغلاق الجلسة بعد الانتهاء من أي استعلامات وعمليات.

session.close();

تشغيل التعليمات البرمجية

قم بتشغيل التطبيق الذي تم إنشاؤه حديثا باستخدام محطة طرفية في دليل التطبيق الخاص بك.

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

Tip

تأكد من تشغيل هذا الأمر داخل المسار /console الذي تم إنشاؤه ضمن هذا الدليل.

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