مشاركة عبر

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

  • مقالة

ينطبق على: العفريت

Azure Cosmos DB ل Apache Gremlin هي خدمة قاعدة بيانات رسم بياني مدارة بالكامل تنفذ إطار عمل حوسبة الرسم البياني الشائع Apache Tinkerpopباستخدام لغة استعلام Gremlin. تمنحك واجهة برمجة التطبيقات ل Gremlin طريقة منخفضة الاحتكاك للبدء في استخدام Gremlin مع خدمة يمكن أن تنمو وتتوسع بقدر ما تحتاج مع الحد الأدنى من الإدارة.

في هذا التشغيل السريع، يمكنك استخدام المكتبة gremlin للاتصال بحساب Azure Cosmos DB الذي تم إنشاؤه حديثا لحساب Gremlin.

حزمة التعليمات البرمجية | المصدر للمكتبة (npm)

المتطلبات الأساسية

Azure Cloud Shell

Azure يستضيف Azure Cloud Shell، بيئة تفاعلية يمكن استخدامها من خلال المستعرض. يمكنك استخدام Bash أو PowerShell مع Cloud Shell للعمل مع خدمات Azure. يمكنك استخدام أوامر Cloud Shell المثبتة مسبقًا لتشغيل التعليمات البرمجية في هذه المقالة دون الحاجة إلى تثبيت أي شيء على البيئة المحلية.

لبدء Azure Cloud Shell:

خيار مثال/ رابط
انقر فوق ⁧⁩جربه⁧⁩ في الزاوية العلوية اليسرى من التعليمة البرمجية أو كتلة الأمر. تحديد ⁧⁩جربه⁧⁩ لا يقوم بنسخ التعليمة البرمجية أو الأمر تلقائيًا إلى Cloud Shell. لقطة شاشة تعرض مثالاً على Try It for Azure Cloud Shell.
انتقل إلى ⁧⁩⁧ https://shell.azure.com⁩⁧⁩، أو حدد زر ⁩تشغيل Cloud Shell لفتح Cloud Shell في المتصفح لديك. زر لتشغيل Azure Cloud Shell.
حدد زر Cloud Shell على شريط القوائم في أعلى اليمين في مدخل Microsoft Azure. لقطة شاشة تعرض زر Cloud Shell في مدخل Microsoft Azure

لاستخدام Azure Cloud Shell:

  1. ابدأ تشغيل Cloud Shell.

  2. حدد الزر نسخ على كتلة التعليمات البرمجية (أو كتلة الأوامر) لنسخ التعليمات البرمجية أو الأمر.

  3. ألصق التعليمة البرمجية أو الأمر في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.

  4. حدد Enter لتشغيل التعليمات البرمجية أو الأمر.

الإعداد

يرشدك هذا القسم خلال إنشاء واجهة برمجة تطبيقات لحساب Gremlin وإعداد مشروع Node.js لاستخدام المكتبة للاتصال بالحساب.

إنشاء واجهة برمجة تطبيقات لحساب Gremlin

يجب إنشاء واجهة برمجة التطبيقات لحساب Gremlin قبل استخدام مكتبة Node.js. بالإضافة إلى ذلك، فإنه يساعد أيضا على وجود قاعدة البيانات والرسم البياني في مكانها.

  1. قم بإنشاء متغيرات shell لـ accountName وresourceGroupNameوالموقع.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

  2. إذا لم تكن قد قمت بالفعل، فسجل الدخول إلى Azure CLI باستخدام az login.

  3. استخدم az group create لإنشاء مجموعة موارد جديدة في اشتراكك.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. استخدم az cosmosdb create لإنشاء واجهة برمجة تطبيقات جديدة لحساب Gremlin مع الإعدادات الافتراضية.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true

    إشعار

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

  5. احصل على واجهة برمجة التطبيقات ل Gremlin endpoint NAME للحساب باستخدام az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

  6. ابحث عن المفتاح من قائمة مفاتيح الحساب باستخدام az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  7. سجل قيم NAME وKEY. يمكنك استخدام بيانات الاعتماد هذه لاحقا.

  8. إنشاء قاعدة بيانات باسم cosmicworks باستخدام az cosmosdb gremlin database create.

    az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

  9. إنشاء رسم بياني باستخدام az cosmosdb gremlin graph create. قم بتسمية الرسم البياني products، ثم قم بتعيين معدل النقل إلى 400، وأخيرا قم بتعيين مسار مفتاح القسم إلى /category.

    az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

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

إنشاء تطبيق وحدة تحكم Node.js في مجلد فارغ باستخدام المحطة الطرفية المفضلة لديك.

  1. افتح المحطة الطرفية في مجلد فارغ.

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

    npm init es6 --yes

  3. إنشاء ملف app.js

    touch app.js

تثبيت الحزمة NPM:

أضف حزمة gremlin npm إلى مشروع Node.js.

  1. افتح ملف package.json واستبدل المحتويات بتكوين JSON هذا.

    {
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

  2. npm install استخدم الأمر لتثبيت كافة الحزم المحددة في ملف package.json.

    npm install

تكوين متغيرات البيئة

لاستخدام قيم NAME وURI التي تم الحصول عليها سابقا في هذا التشغيل السريع، استمر في استخدام متغيرات البيئة الجديدة على الجهاز المحلي الذي يقوم بتشغيل التطبيق.

  1. لتعيين متغير البيئة، استخدم المحطة الطرفية لاستمرار القيم ك COSMOS_ENDPOINT و COSMOS_KEY على التوالي.

    export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"

  2. تحقق من تعيين متغيرات البيئة بشكل صحيح.

    printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

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

تتصل التعليمات البرمجية في هذه المقالة بقاعدة بيانات باسم cosmicworks ورسم بياني باسم products. ثم تضيف التعليمات البرمجية الذروات والحواف إلى الرسم البياني قبل اجتياز العناصر المضافة.

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

يجب التصريح بطلبات التطبيق إلى معظم خدمات Azure. بالنسبة لواجهة برمجة التطبيقات ل Gremlin، استخدم قيم NAME وURI التي تم الحصول عليها سابقا في هذا التشغيل السريع.

  1. افتح ملف app.js.

  2. استيراد الوحدة النمطية gremlin .

    import gremlin from 'gremlin'

  3. إنشاء accountName ومتغيرات accountKey . COSMOS_GREMLIN_ENDPOINT قم بتخزين متغيري البيئة و COSMOS_GREMLIN_KEY كقيم لكل متغير خاص.

    const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY

  4. استخدم PlainTextSaslAuthenticator لإنشاء كائن جديد لبيانات اعتماد الحساب.

    const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

  5. استخدم Client للاتصال باستخدام بيانات اعتماد الخادم البعيد ومسلسل GraphSON 2.0 . ثم استخدم Open لإنشاء اتصال جديد بالخادم.

    const client = new gremlin.driver.Client(
  `wss://${accountName}.gremlin.cosmos.azure.com:443/`,
  {
    credentials,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json'
  }
)

client.open()

إنشاء رؤوس

الآن بعد أن تم توصيل التطبيق بالحساب، استخدم بناء جملة Gremlin القياسي لإنشاء رؤوس.

  1. استخدم submit لتشغيل أمر من جانب الخادم على واجهة برمجة التطبيقات لحساب Gremlin. إنشاء ذروة منتج بالخصائص التالية:

    القيمة‬
    تسميه product
    معرف 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518371',
    prop_name: 'Kiama classic surfboard',
    prop_price: 285.55,
    prop_partition_key: 'surfboards'
  }
)

  2. إنشاء ذروة منتج ثان باستخدام هذه الخصائص:

    القيمة‬
    تسميه product
    معرف 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518403',
    prop_name: 'Montau Turtle Surfboard',
    prop_price: 600.00,
    prop_partition_key: 'surfboards'
  }
)

  3. إنشاء ذروة منتج ثالث باستخدام هذه الخصائص:

    القيمة‬
    تسميه product
    معرف 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518409',
    prop_name: 'Bondi Twin Surfboard',
    prop_price: 585.50,
    prop_partition_key: 'surfboards'
  }
)

إنشاء حواف

إنشاء حواف باستخدام بناء جملة Gremlin لتعريف العلاقات بين الذروات.

  1. إنشاء حافة من المنتج المسمى Montau Turtle Surfboard يستبدل بالمنتج Kiama classic surfboard .

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518371'
  }
)

    تلميح

    يستخدم تعريف الحافة هذا بناء الجملة g.V(['<partition-key>', '<id>']) . بدلا من ذلك، يمكنك استخدام g.V('<id>').has('category', '<partition-key>').

  2. إنشاء آخر يحل محل الحافة من نفس المنتج إلى Bondi Twin Surfboard.

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518409'
  }
)

رؤوس الاستعلام والحواف

استخدم بناء جملة Gremlin لاجتياز الرسم البياني واكتشاف العلاقات بين القمم.

  1. اجتياز الرسم البياني والعثور على جميع الذروات التي Montau Turtle Surfboard تحل محلها.

    const result = await client.submit(
  'g.V().hasLabel(\'product\').has(\'category\', prop_partition_key).has(\'name\', prop_name).outE(\'replaces\').inV()', {
    prop_partition_key: 'surfboards',
    prop_name: 'Montau Turtle Surfboard'
  }
)

  2. اكتب إلى وحدة التحكم نتيجة هذا الاجتياز.

    console.dir(result)

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

تحقق من أن التطبيق الخاص بك يعمل كما هو متوقع عن طريق تشغيل التطبيق. يجب تنفيذ التطبيق بدون أخطاء أو تحذيرات. يتضمن إخراج التطبيق بيانات حول العناصر التي تم إنشاؤها والاستفسار عنها.

  1. افتح المحطة الطرفية في مجلد مشروع Node.js.

  2. استخدم npm <script> لتشغيل التطبيق. لاحظ الإخراج من التطبيق.

    npm start

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

عندما لم تعد بحاجة إلى واجهة برمجة التطبيقات لحساب Gremlin، احذف مجموعة الموارد المقابلة.

  1. إنشاء متغير shell ل resourceGroupName إذا لم يكن موجودا بالفعل.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

  2. استخدم az group delete لحذف مجموعة الموارد.

    az group delete \
    --name $resourceGroupName

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

إنشاء البيانات والاستعلام بها باستخدام Azure Cosmos DB ل Apache Gremlin