ميزات Apache Cassandra بدعم من واجهة برمجة تطبيقات Azure Cosmos DB Cassandra

  • مقالة
  • قراءة خلال 8 دقائق

ينطبق على: واجهة برمجة تطبيقات Cassandra

Azure Cosmos DB هي خدمة قاعدة بيانات متعددة النماذج موزعة عالميًّا من Microsoft. يمكنك الاتصال بواجهة برمجة تطبيقات Azure Cosmos DB Cassandra من خلال الإصدار الرابع من البروتوكول الثنائي للغة الاستعلام لـ Cassandra ‏ (CQL) البروتوكول السلكي المتوافق مع برامج تشغيلعملاء Cassandra مفتوحة المصدر.

باستخدام واجهة برمجة تطبيقات Azure Cosmos DB Cassandra، يمكنك الاستمتاع بميزات واجهات برمجة التطبيقات Apache Cassandra وكذلك إمكانيات المؤسسة التي توفرها Azure Cosmos DB. وتشمل قدرات المؤسسة ⁧⁩التوزيع العالمي⁧⁩، والنطاق ⁧⁩التلقائي للتقسيم⁧⁩، وتوافر ضمانات وزمن الانتقال، والتشفير في البقية، والنسخ الاحتياطي، وغيرها الكثير.

بروتوكول Cassandra

تتوافق واجهة برمجة تطبيقات Azure Cosmos DB Cassandra مع واجهة برمجة تطبيقات لغة استعلام Cassandra (CQL) v3.11 (التي تتوافق مع الإصدار 2.x). يتم سرد أوامر CQL المعتمدة والأدوات والتقييدات والاستثناءات أدناه. إن أي برنامج تشغيل خاص بالعميل يستوعب هذه البروتوكولات ينبغي أن يكون قادرًا على الاتصال بواجهة برمجة تطبيقات Azure Cosmos DB Cassandra.

برنامج تشغيل Cassandra

يتم اعتماد الإصدارات التالية من برامج تشغيل Cassandra بواسطة واجهة برمجة تطبيقات Azure Cosmos DB Cassandra:

أنواع بيانات CQL

تدعم واجهة برمجة تطبيقات Azure Cosmos DB Cassandra أنواع بيانات CQL التالية:

النوع مدعوم
ascii نعم
bigint نعم
blob نعم
boolean نعم
counter نعم
date نعم
decimal نعم
double نعم
float نعم
frozen نعم
inet نعم
int نعم
list نعم
set نعم
smallint نعم
text نعم
time نعم
timestamp نعم
timeuuid نعم
tinyint نعم
tuple نعم
uuid نعم
varchar نعم
varint نعم
tuples نعم
udts نعم
map نعم

ثابتة مدعومة لإعلان نوع البيانات.

دوال CQL

تدعم واجهة برمجة تطبيقات Azure Cosmos DB Cassandra أنواع دوال CQL التالية:

الأمر مدعوم
Token * نعم
ttl *** نعم
writetime *** نعم
cast ** نعم

ملاحظة

* تدعم واجهة برمجة تطبيقات Cassandra الرمز المميز كإسقاط/محدد، وتتيح الرمز المميز (pk) على الجانب الأيسر من عبارة where فقط. على سبيل المثال، ⁧WHERE token(pk) > 1024⁩ مدعوم، ولكن ⁧WHERE token(pk) > token(100)⁩⁧⁩غير⁧⁩ مدعوم.
**الدالة cast() ليست قابلة للتداخل في واجهة برمجة تطبيقات Cassandra. على سبيل المثال، ⁧SELECT cast(count as double) FROM myTable⁩ مدعوم، ولكن ⁧SELECT avg(cast(count as double)) FROM myTable⁩⁧⁩غير⁧⁩ مدعوم.
*** تُستخدَم الطوابع الزمنية المخصصة وTTL المحددة مع الخيار USING على مستوى صف (وليس لكل خلية).

دوال مجمعة:

الأمر مدعوم
avg نعم
count نعم
min نعم
max نعم
sum نعم

ملاحظة

تعمل الدوال المجمعة على أعمدة عادية، ولكن ⁧⁩التجميعات⁧⁩ على أعمدة التجميع غير مدعومة.

دوال تحويل كائن ثنائي كبير الحجم:

الأمر مدعوم
typeAsBlob(value) نعم
blobAsType(value) نعم

UUID ودوال timeuuid:

الأمر مدعوم
dateOf() نعم
now() نعم
minTimeuuid() نعم
unixTimestampOf() نعم
toDate(timeuuid) نعم
toTimestamp(timeuuid) نعم
toUnixTimestamp(timeuuid) نعم
toDate(timestamp) نعم
toUnixTimestamp(timestamp) نعم
toTimestamp(date) نعم
toUnixTimestamp(date) نعم

أوامر CQL

يدعم Azure Cosmos DB أوامر قاعدة البيانات التالية على حسابات واجهة برمجة تطبيقات Cassandra.

الأمر مدعوم
ALLOW FILTERING نعم
ALTER KEYSPACE لا يوجد (خدمة PaaS، النسخ المتماثل المدار داخليًا)
ALTER MATERIALIZED VIEW لا
ALTER ROLE لا
ALTER TABLE نعم
ALTER TYPE لا
ALTER USER لا
BATCH نعم (الدفعة غير المسجلة فقط)
COMPACT STORAGE لا يوجد (خدمة PaaS)
CREATE AGGREGATE لا
CREATE CUSTOM INDEX (SASI) لا
CREATE INDEX نعم (بدون ⁧⁩تحديد اسم الفهرس⁧⁩، والفهارس على مفاتيح التجميع أو مجموعة FROZEN الكاملة غير معتمدة)
CREATE FUNCTION لا
CREATE KEYSPACE (تم تجاهل إعدادات النسخ المماثلة) نعم
CREATE MATERIALIZED VIEW لا
CREATE TABLE نعم
CREATE TRIGGER لا
CREATE TYPE نعم
CREATE ROLE لا
CREATE USER (مهمل في Apache Cassandra الأصلي) لا
DELETE نعم
DISTINCT لا
DROP AGGREGATE لا
DROP FUNCTION لا
DROP INDEX نعم
DROP KEYSPACE نعم
DROP MATERIALIZED VIEW لا
DROP ROLE لا
DROP TABLE نعم
DROP TRIGGER لا
DROP TYPE نعم
DROP USER (مهمل في Apache Cassandra الأصلي) لا
GRANT لا
INSERT نعم
LIST PERMISSIONS لا
LIST ROLES لا
LIST USERS (مهمل في Apache Cassandra الأصلي) لا
REVOKE لا
SELECT نعم
UPDATE نعم
TRUNCATE لا
USE نعم

معاملات خفيفة الوزن (LWT)

المكون مدعوم
DELETE IF EXISTS نعم
DELETE conditions نعم
INSERT IF NOT EXISTS نعم
UPDATE IF EXISTS نعم
UPDATE IF NOT EXISTS نعم
UPDATE conditions نعم

ملاحظة

المعاملات خفيفة الوزن حاليًا لا تدعم الحسابات التي تم تمكين عمليات الكتابة متعددة المناطق بها.

أوامر CQL Shell

يدعم Azure Cosmos DB أوامر قاعدة البيانات التالية على حسابات واجهة برمجة تطبيقات Cassandra.

الأمر مدعوم
CAPTURE نعم
CLEAR نعم
CONSISTENCY * غير متوفر
COPY لا
DESCRIBE نعم
cqlshExpand لا
EXIT نعم
LOGIN لا يوجد (دالة CQL ⁧USER⁩ غير مدعومة، ومن ثمَّ ⁧LOGIN⁩ فهي مكررة)
PAGING نعم
SERIAL CONSISTENCY * غير متوفر
SHOW نعم
SOURCE نعم
TRACING لا يوجد (تدعم واجهة برمجة التطبيقات Cassandra Azure Cosmos DB - استخدم ⁧⁩التسجيل التشخيصي⁧⁩ لاستكشاف الأخطاء وإصلاحها)

ملاحظة

يعمل الاتساق بشكل مختلف في Azure Cosmos DB، راجع ⁧⁩هنا⁧⁩ لمزيد من المعلومات.

دعم JSON

الأمر مدعوم
SELECT JSON نعم
INSERT JSON نعم
fromJson() لا
toJson() لا

حدود واجهة برمجة التطبيقات Cassandra

لا تتمتع واجهة برمجة تطبيقات Azure Cosmos DB Cassandra بأية حدود لحجم البيانات المخزنة في جدول. يمكن تخزين مئات التيرابايت أو البيتابايت من البيانات مع ضمان احترام حدود مفتاح القسم. وبالمثل، ليس لدى كل كيان أو صف مكافئ أي حدود لعدد الأعمدة. غير أنه، يجب ألا يتجاوز الحجم الإجمالي للكيان 2 ميجابت. لا يمكن أن تتجاوز البيانات لكل مفتاح قسم 20 جيجابت كما هو الحال في كافة واجهات برمجة التطبيقات الأخرى.

الأدوات

واجهة برمجة تطبيقات Azure Cosmos DB Cassandra عبارة عن منصة خدمة مدارة. لا يتطلب النظام الأساسي أي حمل أو أدوات مساعدة للإدارة مثل جامع المهملات وجهاز Java الظاهري (JVM) وnodetool لإدارة نظام المجموعة. أدوات مثل cqlsh التي تستخدم توافق CQLv4 الثنائي معتمدة.

  • مستكشف البيانات في مدخل Azure، والمقاييس، وتشخيص السجلات، وPowerShell، وCLI عبارة عن آليات أخرى مدعومة لإدارة الحساب.

CQL shell

يمكنك الاتصال بواجهة برمجة تطبيقات Cassandra في Azure Cosmos DB باستخدام CQLSH المُثبَت على جهاز محلي. يأتي مع Apache Cassandra 3.11 ويعمل بالخارج عن طريق تعيين متغيرات البيئة. تتضمن المقاطع التالية إرشادات لتثبيت واجهة برمجة تطبيقات Cassandra وتكوينها والاتصال بها في Azure Cosmos DB، على Windows أو Linux باستخدام CQLSH.

تحذير

لن تعمل الاتصالات بواجهة برمجة تطبيقات Azure Cosmos DB Cassandra مع إصدارات DataStax Enterprise (DSE) أو إصدارات Cassandra 4.0 لـ CQLSH. يُرجى التأكد من استخدام إصدار 3.11 مفتوح المصدر من Apache Cassandra لـ CQLSH فقط عند الاتصال بواجهة برمجة تطبيقات Cassandra.

⁧⁩Windows:⁧⁩

إذا كنت تستخدم windows، نوصي بتمكين ⁧⁩نظام الملفات Windows من أجل Linux⁧⁩. يمكنك بعد ذلك اتباع أوامر Linux أدناه.

تثبيت على Unix/Linux/Mac:

# Install default-jre and default-jdk
sudo apt install default-jre
sudo apt-get update
sudo apt install default-jdk

# Import the Baltimore CyberTrust root certificate:
curl https://cacert.omniroot.com/bc2025.crt > bc2025.crt
keytool -importcert -alias bc2025ca -file bc2025.crt

# Install the Cassandra libraries in order to get CQLSH:
echo "deb https://downloads.apache.org/cassandra/debian 311x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
sudo apt-get update
sudo apt-get install cassandra

الاتصال بـ Unix/Linux/Mac:

# Export the SSL variables:
export SSL_VERSION=TLSv1_2
export SSL_VALIDATE=false

# Connect to Azure Cosmos DB API for Cassandra:
cqlsh <YOUR_ACCOUNT_NAME>.cassandra.cosmosdb.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl

الاتصال بـ Docker:

docker run -it --rm -e SSL_VALIDATE=false -e SSL_VERSION=TLSv1_2 cassandra:3.11 cqlsh <account_name>.cassandra.cosmos.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl

ستؤدي كافة عمليات CRUD التي يتم تنفيذها من خلال SDK متوافق مع CQL v4 إلى الحصول على معلومات إضافية حول الخطأ وطلب وحدات مستهلكة. يجب معالجة أوامر الحذف والتحديث مع مراعاة إدارة الموارد لضمان الاستخدام الفعال فيما يتعلق بمعدل النقل المقدم.

  • ملاحظة: يجب أن تكون قيمة gc_grace_seconds صفراً في حالة تحديدها.
var tableInsertStatement = table.Insert(sampleEntity); 
var insertResult = await tableInsertStatement.ExecuteAsync(); 
 
foreach (string key in insertResult.Info.IncomingPayload) 
        { 
            byte[] valueInBytes = customPayload[key]; 
            double value = Encoding.UTF8.GetString(valueInBytes); 
            Console.WriteLine($"CustomPayload:  {key}: {value}"); 
        }

تعيين التناسق

توفر واجهة برمجة تطبيقات Azure Cosmos DB Cassandra خيار التناسق لعمليات القراءة. يتم تفصيل تعيين التناسق ⁧⁩هنا⁧⁩.

الإذن وإدارة الدور

يدعم Azure Cosmos DB التحكم في الوصول المستند إلى دورAzure (Azure RBAC) لتوفير المفاتيح وتناوبها وعرض المقاييس وكلمات المرور/المفاتيح المخصصة للقراءة والكتابة وللقراءة فقط التي يمكن الحصول عليها من خلال ⁧⁩مدخل Microsoft Azure⁧⁩. لا يدعم Azure Cosmos DB الأدوار لأنشطة CRUD.

خيارات مساحة المفاتيح والجدول

يتم تجاهل الخيارات الخاصة باسم المنطقة والفئة وreplication_factor ومركز البيانات في الأمر "إنشاء مساحة مفاتيح" حاليًا. يستخدم النظام أسلوب النسخ المتماثل ⁧⁩التوزيع العمومي⁧⁩ Azure Cosmos DB الأساسي لإضافة المناطق. إذا كنت بحاجة إلى وجود البيانات عبر المناطق، يمكنك تمكينها على مستوى الحساب باستخدام PowerShell أو CLI أو المدخل، لمعرفة المزيد، راجع ⁧⁩كيفية إضافة مقالة المناطق⁧.⁩ لا يمكن تعطيل Durable_writes لأن Azure Cosmos DB يضمن أن تكون كل كتابة دائمة. في كل منطقة، يقوم Azure Cosmos DB بنسخ البيانات عبر مجموعة النسخ المتماثلة التي تتكون من أربع نسخ متماثلة ولا يمكن تعديل ⁧⁩تكوين⁧⁩ مجموعة النسخ المتماثلة هذه.

يتم تجاهل كافة الخيارات عند إنشاء الجدول، باستثناء gc_grace_seconds، والتي يجب تعيينها إلى الصفر. تحمل مساحة المفاتيح وجدول خيار إضافي يُسمى "cosmosdb_provisioned_throughput" مع قيمة الحد الأدنى من 400 RU/s. يسمح معدل نقل مساحة المفاتيح مشاركة الإنتاجية عبر جداول متعددة وهو مفيد للسيناريوهات عندما لا تستخدم كافة الجداول الإنتاجية المقدمة. يتيح الأمر «تعديل الجدول» تغيير معدل النقل المقدم عبر المناطق.

CREATE  KEYSPACE  sampleks WITH REPLICATION = {  'class' : 'SimpleStrategy'}   AND cosmosdb_provisioned_throughput=2000;  

CREATE TABLE sampleks.t1(user_id int PRIMARY KEY, lastname text) WITH cosmosdb_provisioned_throughput=2000; 

ALTER TABLE gks1.t1 WITH cosmosdb_provisioned_throughput=10000 ;

فهرس ثانوي

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

استخدام نهج اتصال إعادة محاولة Cassandra

Azure Cosmos DB هو نظام الموارد التي تحكمها. يمكنك إجراء عدد معين من العمليات في ثانية معينة استناداً إلى وحدات الطلب التي تستهلكها العمليات. في حالة تجاوز أحد التطبيقات هذا الحد في ثانية معينة، تُفرَض حدود على معدل الطلبات ويمكن تقديم استثناءات. تترجم واجهة برمجة تطبيقات Cassandra في Azure Cosmos DB هذه الاستثناءات إلى أخطاء في التحميل الزائد على بروتوكول Cassandra الأصلي. للتأكد من أن التطبيق الخاص بك يمكن اعتراض الطلبات ومحاولة إعادتها في حالة تقييد معدل، يتم توفير ⁧⁩spark⁧⁩ وملحقات ⁧⁩Java⁧.⁩ انظر أيضًا نماذج التعليمات البرمجية لـ Java ⁧⁩للإصدار 3⁧⁩ و ⁧⁩الإصدار 4⁧⁩ برامج تشغيل Datastax، عند الاتصال بواجهة برمجة تطبيقات Cassandra في Azure Cosmos DB. إذا كنت تستخدم وحدات SDK أخرى للوصول إلى واجهة برمجة تطبيقات Cassandra في Azure Cosmos DB، فأنشئ نهج إعادة المحاولة لإعادة المحاولة في هذه الاستثناءات. بدلاً من ذلك، مكِّن عمليات إعادة المحاولة من جانب الخادم لواجهة برمجة تطبيقات Cassandra.

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