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

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

مهم

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

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

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

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

Prerequisites

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

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

Python 3.12 أو أحدث

الإعداد

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

إنشاء حساب

ابدأ بإنشاء واجهة برمجة تطبيقات لحساب 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 من إخراج الأوامر السابقة. قيمة هذه الخاصية هي كلمة المرور التي تستخدمها لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

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

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

ابدأ في دليل فارغ.
استيراد الحزمة cassandra-driver من فهرس حزمة Python (PyPI).
```
pip install cassandra-driver
```
قم بإنشاء ملف app.py .

نموذج الكائن

	Description
`Cluster`	يمثل اتصالا محددا بمجموعة

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

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

افتح ملف app.py في بيئة التطوير المتكاملة (IDE).
استيراد الأنواع التالية من الوحدة النمطية cassandra-driver :
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
استيراد الأنواع التالية من الوحدة النمطية ssl :
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
إنشاء متغيرات سلسلة لبيانات الاعتماد التي تم جمعها مسبقا في هذا الدليل. قم بتسمية المتغيرات usernameو passwordو.contactPoint
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
قم بتكوين SSLContext عن طريق إنشاء متغير جديد باسم ssl_context، وتعيين البروتوكول إلى PROTOCOL_TLS_CLIENT، وتعطيل التحقق من اسم المضيف، وتعيين وضع التحقق إلى CERT_NONE.
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
إنشاء كائن جديد PlainTextAuthProvider باستخدام بيانات الاعتماد المحددة في الخطوات السابقة. قم بتخزين النتيجة في متغير يسمى auth_provider.
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
إنشاء كائن Cluster باستخدام بيانات الاعتماد ومتغيرات التكوين التي تم إنشاؤها في الخطوات السابقة. قم بتخزين النتيجة في متغير يسمى cluster.
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```

الاتصال بالمجموعة.

session = cluster.connect("cosmicworks")

Warning

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

بيانات Upsert

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

إنشاء متغير سلسلة جديد باسم insertQuery باستخدام استعلام لغة استعلام Cassandra (CQL) لإدراج صف جديد.

insertQuery = """
INSERT INTO
    product (id, name, category, quantity, price, clearance)
VALUES
    (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
"""

إنشاء كائن جديد بخصائص مختلفة لمنتج جديد وتخزينه في متغير يسمى params.

params = {
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "name": "Yamba Surfboard",
    "category": "gear-surf-surfboards",
    "quantity": 12,
    "price": 850.00,
    "clearance": False
}

استخدم الدالة execute لتشغيل الاستعلام مع المعلمات المحددة.
```
session.execute(insertQuery, params)
```

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

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

إنشاء متغير سلسلة جديد باسم readQuery مع استعلام CQL يطابق العناصر مع نفس id الحقل.
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
إنشاء متغير سلسلة باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
استخدم الدالة execute لتشغيل الاستعلام المخزن في readQuery تمرير المتغير id كوسيطة. قم بتخزين النتيجة في متغير يسمى readResults.
```
readResults = session.execute(readQuery, (id,))
```
استخدم الدالة one للحصول على النتيجة الفردية المتوقعة. قم بتخزين هذه النتيجة الفردية في متغير يسمى matchedProduct.
```
matchedProduct = readResults.one()
```

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

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

إنشاء متغيرات السلسلة المسماة findQuery و category مع استعلام CQL والمعلمة المطلوبة.
```
findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
category = "gear-surf-surfboards"
```
استخدم متغيري السلسلة والدالة execute للاستعلام عن نتائج متعددة. تخزين نتيجة هذا الاستعلام في متغير يسمى findResults.
```
findResults = session.execute(findQuery, (category,))
```
استخدم تكرار حلقي for للتكرار عبر نتائج الاستعلام.
```
for row in findResults:
    # Do something here with each result
```

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

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

python app.py

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

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

Azure CLI
مدخل Microsoft Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

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

نظرة عامة على Azure Cosmos DB ل Apache Cassandra

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-10-13