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

• Python
• Node.js
• C#‎
• Java
• Go

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

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

Prerequisites

• اشتراك Azure

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

• أحدث إصدار من Azure CLI في Azure Cloud Shell.

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

• .NET SDK 9.0 أو أحدث

الإعداد

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

إنشاء حساب

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

1. إذا لم يكن لديك بالفعل مجموعة موارد مستهدفة az group create ، فاستخدم الأمر لإنشاء مجموعة موارد جديدة في اشتراكك.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

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

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

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

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

4. إنشاء كائن 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"
   

مدخل Microsoft Azure

1. سجّل الدخول إلى مدخل Azure (https://portal.azure.com).

2. أدخل Azure Cosmos DB في شريط البحث العمومي.

3. ضمن الخدمات، حدد Azure Cosmos DB.

4. في جزء Azure Cosmos DB ، حدد Create، ثم Azure Cosmos DB ل Apache Cassandra ضمن علامة التبويب Others .

5. حدد Request unit (RU) database account لنوع الحساب.

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

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

   Tip

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

7. في جزء Review + create ، انتظر حتى ينتهي التحقق من صحة حسابك بنجاح، ثم حدد Create.

8. ينتقل المدخل تلقائيا إلى جزء النشر . انتظر حتى يكتمل التوزيع.

9. بمجرد اكتمال النشر، حدد Go to resource للانتقال إلى واجهة برمجة التطبيقات الجديدة لحساب Apache Cassandra.

10. في قائمة الموارد، حدد خيار مستكشف البيانات .

11. في Data Explorer، حدد + New Table.

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

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

    Tip

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

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

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

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

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

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

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

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

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

مدخل Microsoft Azure

1. في قائمة الموارد للحساب، حدد خيار سلاسل الاتصال ضمن قسم الإعدادات .

2. سجل قيمة حقل نقطة الاتصال في هذه الصفحة. قيمة هذه الخاصية هي نقطة الاتصال التي تستخدمها لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

3. سجل قيمة حقل USERNAME في هذه الصفحة. قيمة هذه الخاصية هي اسم المستخدم الذي تستخدمه لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

4. عرض وتسجيل قيمة حقل كلمة المرور الأساسية في هذه الصفحة. قيمة هذه الخاصية هي كلمة المرور التي تستخدمها لاحقا في هذا الدليل للاتصال بالحساب باستخدام المكتبة.

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

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

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

2. إنشاء تطبيق وحدة تحكم .NET جديد

   dotnet new console
   

3. أضف الحزمة CassandraCSharpDriver من NuGet.

   dotnet add package CassandraCSharpDriver
   

4. أنشئ المشروع.

   dotnet build
   

نموذج الكائن

	Description
Cluster	يمثل حالة الاتصال بمجموعة
ISession	الكيانات الآمنة لسلسلة الرسائل التي تحتفظ باتصال معين بمجموعة
Mapper	عميل Cassandra Query Language (CQL) المستخدم لتشغيل الاستعلامات

أمثلة على التعليمات البرمجية

• مصادقة العميل
• بيانات Upsert
• قراءة البيانات
• بيانات الاستعلام

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

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

1. افتح ملف Program.cs في بيئة التطوير المتكاملة (IDE).

2. احذف أي محتوى موجود داخل الملف.

3. أضف استخدام التوجيهات لمساحات الأسماء التالية:

   • System.Security.Authentication
   • Cassandra
   • Cassandra.Mapping

   using System.Security.Authentication;
   using Cassandra;
   using Cassandra.Mapping;
   

4. إنشاء متغيرات ثابتة للسلسلة لبيانات الاعتماد التي تم جمعها مسبقا في هذا الدليل. قم بتسمية المتغيرات usernameو passwordو.contactPoint

   const string username = "<username>";
   const string password = "<password>";
   const string contactPoint = "<contact-point>";
   

5. أنشئ كائنا جديدا SSLoptions للتأكد من أنك تستخدم بروتوكول أمان طبقة النقل (TLS) 1.2، والتحقق من إبطال الشهادة، وعدم إجراء أي تحقق إضافي من صحة الشهادة من جانب العميل.

   SSLOptions sslOptions = new(
       sslProtocol: SslProtocols.Tls12,
       checkCertificateRevocation: true,
       remoteCertValidationCallback: (_, _, _, _) => true);
   

6. إنشاء كائن جديد Cluster باستخدام بناء الجملة بطلاقة Cluster.Builder() . استخدم بيانات الاعتماد ومتغيرات التكوين التي تم إنشاؤها في الخطوات السابقة.

   Cluster cluster = Cluster.Builder()
       .WithCredentials(username, password)
       .WithPort(10350)
       .AddContactPoint(contactPoint)
       .WithSSL(sslOptions)
       .Build();
   

7. إنشاء متغير جديد session باستخدام ConnectAsync الأسلوب تمرير في اسم مساحة المفتاح الهدف (cosmicworks).

   using ISession session = await cluster.ConnectAsync("cosmicworks");
   

8. إنشاء متغير جديد mapper باستخدام الدالة Mapper الإنشائية للفئة التي تمر في المتغير الذي تم إنشاؤه session مؤخرا.

   Mapper mapper = new(session);
   

Warning

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

بيانات Upsert

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

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

   	Type
   Id	string
   Name	string
   Category	string
   Quantity	int
   Price	decimal
   Clearance	bool

   record Product
   {
       public required string Id { get; init; }
   
       public required string Name { get; init; }
   
       public required string Category { get; init; }
   
       public required int Quantity { get; init; }
   
       public required decimal Price { get; init; }
   
       public required bool Clearance { get; init; }
   }
   

   Tip

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

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

   Product product = new()
   {
       Id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       Name = "Yamba Surfboard",
       Category = "gear-surf-surfboards",
       Quantity = 12,
       Price = 850.00m,
       Clearance = false
   };
   

3. استدعاء InsertAsync الأسلوب الذي يمر في المتغير الذي product تم إنشاؤه في الخطوة السابقة بشكل غير متزامن.

   await mapper.InsertAsync(product);
   

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

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

1. إنشاء متغير سلسلة جديد باسم readQuery مع استعلام CQL يطابق العناصر مع نفس id الحقل.

   string readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. إنشاء متغير سلسلة باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.

   string id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. SingleAsync<> استخدم الأسلوب العام لتشغيل الاستعلام المخزن في readQuery، ومرر id المتغير كوسيطة، وقم بتعيين الإخراج إلى Product النوع. قم بتخزين نتيجة هذه العملية في متغير من النوع Product.

   Product matchedProduct = await mapper.SingleAsync<Product>(readQuery, [id]);
   

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

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

1. إنشاء متغيرات السلسلة المسماة findQuery و category مع استعلام CQL والمعلمة المطلوبة.

   string findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   string category = "gear-surf-surfboards";
   

2. استخدم متغيري السلسلة والأسلوب FetchAsync<> العام للاستعلام عن نتائج متعددة بشكل غير متزامن. قم بتخزين نتيجة هذا الاستعلام في متغير من النوع IEnumerable<Product> المسمى queriedProducts.

   IEnumerable<Product> queriedProducts = await mapper.FetchAsync<Product>(findQuery, [category]);
   

3. استخدم تكرار حلقي foreach للتكرار عبر نتائج الاستعلام.

   foreach (Product queriedProduct in queriedProducts)
   {
       // Do something here with each result
   }
   

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

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

dotnet run

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

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

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

مدخل Microsoft Azure

1. انتقل إلى Azure Cosmos DB الحالي لمورد Apache Cassandra الذي أنشأته سابقا في هذا الدليل.

2. في صفحة المورد، حدد حذف من شريط القائمة.

3. اتبع الإرشادات الموجودة في مربع حوار التأكيد.

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

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