مشاركة عبر

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

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

مهم

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

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

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

Prerequisites

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

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

الإعداد

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

إنشاء حساب

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

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

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

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

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

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

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

  2. تهيئة وحدة نمطية جديدة.

    npm init es6 --yes

  3. تثبيت الحزمة cassandra-driver من Node Package Manager (npm).

    npm install --save cassandra-driver

  4. قم بإنشاء ملفindex.js .

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

  2. تهيئة وحدة نمطية جديدة.

    npm init es6 --yes

  3. تثبيت الحزمة typescript من Node Package Manager (npm).

    npm install --save-dev typescript

  4. تثبيت الحزمة tsx من npm.

    npm install --save-dev tsx

  5. تثبيت الحزمة cassandra-driver من npm.

    npm install --save cassandra-driver

  6. تهيئة مشروع TypeScript باستخدام المحول البرمجي (tsc).

    npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

  7. قم بإنشاء ملف index.ts .

نموذج الكائن

Description
Client يمثل اتصالا محددا بمجموعة
Mapper عميل Cassandra Query Language (CQL) المستخدم لتشغيل الاستعلامات

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

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

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

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

  2. استيراد الأنواع التالية من الوحدة النمطية cassandra-driver :

    • cassandra
    • cassandra.Client
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

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

    const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';

  4. إنشاء متغير سلسلة آخر للمنطقة التي قمت فيها بإنشاء Azure Cosmos DB لحساب Apache Cassandra. قم بتسمية هذا المتغير region.

    const region = '<azure-region>';

  5. إنشاء كائن جديد PlainTextAuthProvider باستخدام بيانات الاعتماد المحددة في الخطوات السابقة.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

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

    let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

  7. الاتصال بشكل غير متزامن إلى نظام المجموعة.

    await client.connect();

  8. إنشاء معين جديد يستهدف cosmicworks مساحة المفتاح والجدول product . قم بتسمية المعين Product.

    const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  9. إنشاء مثيل معين باستخدام الدالة forModelProduct واسم معين.

    const productMapper = mapper.forModel('Product');

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

  2. استيراد الأنواع التالية من الوحدة النمطية cassandra-driver :

    • cassandra.auth
    • cassandra.mapping
    • cassandra.types
    • cassandra.Client
    • cassandra.ClientOptions
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;

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

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

  4. إنشاء متغير سلسلة آخر للمنطقة التي قمت فيها بإنشاء Azure Cosmos DB لحساب Apache Cassandra. قم بتسمية هذا المتغير region.

    const region: string = '<azure-region>';

  5. إنشاء كائن جديد PlainTextAuthProvider باستخدام بيانات الاعتماد المحددة في الخطوات السابقة.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. إنشاء كائن مجهول بخيارات تضمن استخدام بروتوكول أمان طبقة النقل (TLS) 1.2.

    let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};

  7. إنشاء كائن ClientOptions باستخدام بيانات الاعتماد ومتغيرات التكوين التي تم إنشاؤها في الخطوات السابقة.

    let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

  8. إنشاء كائن Client باستخدام clientOptions المتغير في الدالة الإنشائية.

    let client = new Client(clientOptions);

  9. الاتصال بشكل غير متزامن إلى نظام المجموعة.

    await client.connect();

  10. إنشاء معين جديد يستهدف cosmicworks مساحة المفتاح والجدول product . قم بتسمية المعين Product.

    const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  11. إنشاء مثيل معين باستخدام الدالة forModelProduct واسم معين.

    const productMapper = mapper.forModel('Product');

Warning

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

بيانات Upsert

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

  1. إنشاء كائن جديد في متغير يسمى product.

    const product = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    name: 'Yamba Surfboard',
    category: 'gear-surf-surfboards',
    quantity: 12,
    price: 850.00,
    clearance: false
};

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

    await productMapper.insert(product);

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

    Type
    Id string
    Name string
    Category string
    Quantity int
    Price decimal
    Clearance bool 
    interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}

    Tip

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

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

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

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

    await productMapper.insert(product);

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

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

  1. إنشاء كائن مجهول باسم filter. في هذا الكائن، قم بتضمين خاصية باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. استدعاء دالة get المعين الذي يمر في filter المتغير. قم بتخزين النتيجة في متغير يسمى matchedProduct.

    let matchedProduct = await productMapper.get(filter);

  1. إنشاء كائن مجهول باسم filter. في هذا الكائن، قم بتضمين خاصية باسم id بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. استدعاء دالة get المعين الذي يمر في filter المتغير. تخزين النتيجة في متغير يسمى matchedProduct من النوع Product.

    let matchedProduct: Product = await productMapper.get(filter);

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

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

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

    const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. إنشاء كائن مجهول باسم params. في هذا الكائن، قم بتضمين خاصية باسم category بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. استدعاء الدالة execute التي تمر في كل من query المتغيرين و params كوسيطات بشكل غير متزامن. قم بتخزين خاصية النتيجة rows كمتغير يسمى matchedProducts.

    let { rows: matchedProducts } = await client.execute(query, params);

  4. تكرار نتائج الاستعلام عن طريق استدعاء foreach الأسلوب على صفيف المنتجات.

    matchedProducts.forEach(product => {
    // Do something here with each result
});

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

    const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. إنشاء كائن مجهول باسم params. في هذا الكائن، قم بتضمين خاصية باسم category بنفس قيمة المنتج الذي تم إنشاؤه مسبقا في هذا الدليل.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. استدعاء الدالة execute التي تمر في كل من query المتغيرين و params كوسيطات بشكل غير متزامن. تخزين النتيجة في متغير يسمى result من النوع types.ResultSet.

    let result: types.ResultSet = await client.execute(query, params);

  4. قم بتخزين خاصية النتيجة rows كمتغير يسمى matchedProducts من النوع Product[].

    let matchedProducts: Product[] = result.rows;

  5. تكرار نتائج الاستعلام عن طريق استدعاء foreach الأسلوب على صفيف المنتجات.

    matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});

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

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

node index.js

npx tsx index.ts

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

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

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

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

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

  • Last updated on