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

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

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

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

Prerequisites

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

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

Go 1.24 أو أحدث

الإعداد

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

إنشاء حساب

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

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

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

ابدأ في دليل فارغ.
إنشاء وحدة نمطية Go جديدة.
```
go mod init quickstart
```
استيراد الحزمة github.com/apache/cassandra-gocql-driver/v2 من Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
قم بإنشاء ملف main.go .
أضف Go application boilerplate.
```
package main

func main() {    
}
```
Important

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

نموذج الكائن

	Description
`Cluster`	يمثل اتصالا محددا بمجموعة
`Session`	الكيانات التي تحتفظ باتصال معين بمجموعة

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

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

افتح ملف main.go في بيئة التطوير المتكاملة (IDE).
ضمن الدالة main ، قم باستيراد الحزم التالية مع الحزمة github.com/apache/cassandra-gocql-driver/v2 :
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
إنشاء متغيرات سلسلة لبيانات الاعتماد التي تم جمعها مسبقا في هذا الدليل. قم بتسمية المتغيرات usernameو passwordو.contactPoint
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
تكوين مثيل من PasswordAuthenticator النوع مع بيانات الاعتماد المحددة في الخطوات السابقة. قم بتخزين النتيجة في متغير يسمى authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
تكوين مثيل SslOptions مع الحد الأدنى من إصدار أمان طبقة النقل (TLS) 1.2 والمتغير contactPoint كاسم الخادم الهدف. قم بتخزين النتيجة في متغير يسمى sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
إنشاء مواصفات نظام مجموعة جديدة باستخدام NewCluster والمتغير contactPoint .
```
cluster := gocql.NewCluster(contactPoint)
```
تكوين كائن مواصفات نظام المجموعة باستخدام بيانات الاعتماد ومتغيرات التكوين التي تم إنشاؤها في الخطوات السابقة.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
قم بتكوين باقي كائن مواصفات نظام المجموعة بهذه القيم الثابتة.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
إنشاء جلسة عمل جديدة تتصل بالمجموعة باستخدام CreateSession.
```
session, _ := cluster.CreateSession()
```
تكوين جلسة العمل لاستدعاء الدالة Close بعد إرجاع الدالة main .
```
defer session.Close()
```
إنشاء كائن سياق جديد Background وتخزينه في ctx المتغير.
```
ctx := context.Background()
```

Warning

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

بيانات Upsert

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

تعريف نوع جديد باسم Product مع حقول مطابقة للجدول الذي تم إنشاؤه مسبقا في هذا الدليل.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Tip

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

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

product := Product {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

إنشاء متغير سلسلة جديد باسم insertQuery باستخدام استعلام لغة استعلام Cassandra (CQL) لإدراج صف جديد.
```
insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`
```
Query استخدم الدالتين و ExecContext لتشغيل الاستعلام. تمرير خصائص مختلفة للمتغير product كمعلمات استعلام.
```
_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)
```

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

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

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

readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`

إنشاء متغير سلسلة باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
أنشئ متغيرا آخر باسم matchedProduct لتخزين نتيجة هذه العملية فيه.
```
var matchedProduct Product
```

Query Consistency IterContextاستخدم الدالات و و Scan معا للعثور على العنصر الفردي الذي يطابق الاستعلام وتعيين خصائصه إلى matchedProduct المتغير.

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

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

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

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

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Query Consistencyاستخدم الدالات و IterContextو Scanner معا لإنشاء ماسح ضوئي يمكنه التكرار عبر عناصر متعددة تطابق الاستعلام.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Next استخدم الدالتين و Scan للتكرار عبر نتائج الاستعلام وتعيين خصائص كل نتيجة إلى المتغير الداخليqueriedProduct.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

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

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

go run .

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