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

مقالة
08/15/2024

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

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

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

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

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

حساب Azure مع اشتراك نشط.
- لا يوجد اشتراك في Azure؟ التسجيل للحصول على حساب Azure مجاني.
- ألا تريد اشتراك Azure؟ يمكنك تجربة Azure Cosmos DB مجانا دون الحاجة إلى اشتراك.
.NET (LTS)
- أليس لديك .NET مثبت؟ جرب هذا التشغيل السريع في GitHub Codespaces.
واجهة سطر أوامر Azure (CLI)

Azure Cloud Shell

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

لبدء Azure Cloud Shell:

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

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

ابدأ تشغيل Cloud Shell.
حدد الزر نسخ على كتلة التعليمات البرمجية (أو كتلة الأوامر) لنسخ التعليمات البرمجية أو الأمر.
ألصق التعليمة البرمجية أو الأمر في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.
حدد Enter لتشغيل التعليمات البرمجية أو الأمر.

الإعداد

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

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

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

قم بإنشاء متغيرات 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"

إذا لم تكن قد قمت بالفعل، فسجل الدخول إلى Azure CLI باستخدام az login.
استخدم az group create لإنشاء مجموعة موارد جديدة في اشتراكك.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
استخدم 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 ويجب عليك الاشتراك عند إنشاء الحساب. إذا فشل هذا الأمر في تطبيق خصم المستوى المجاني، فهذا يعني أنه تم تمكين حساب آخر في الاشتراك بالفعل مع المستوى المجاني.
احصل على واجهة برمجة التطبيقات ل Gremlin endpoint NAME للحساب باستخدام az cosmosdb show.
```
az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"
```

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

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

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

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

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

إنشاء رسم بياني باستخدام 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
```

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

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

افتح المحطة الطرفية في مجلد فارغ.
استخدم الأمر dotnet new الذي يحدد قالب وحدة التحكم.
```
dotnet new console
```

تثبيت حزمة NuGet

أضف حزمة Gremlin.NET NuGet إلى مشروع .NET.

استخدم الأمر الذي dotnet add package يحدد حزمة Gremlin.Net NuGet.
```
dotnet add package Gremlin.Net
```

إنشاء مشروع .NET باستخدام dotnet build.

dotnet build

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

Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

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

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

لتعيين متغير البيئة، استخدم المحطة الطرفية لاستمرار القيم ك COSMOS_ENDPOINT و COSMOS_KEY على التوالي.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
تحقق من تعيين متغيرات البيئة بشكل صحيح.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

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

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

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

افتح ملف Program.cs.
احذف أي محتوى موجود داخل الملف.
إضافة كتلة استخدام لمساحة Gremlin.Net.Driver الاسم.
```
using Gremlin.Net.Driver;
```
إنشاء accountName متغيرات وسلسلة accountKey . COSMOS_GREMLIN_ENDPOINT قم بتخزين متغيري البيئة و COSMOS_GREMLIN_KEY كقيم لكل متغير خاص.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

إنشاء مثيل GremlinServer جديد لاستخدام بيانات اعتماد الحساب.

var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

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

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

إنشاء رؤوس

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

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

القيمة‬

تسميه product

معرف 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
);
```

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

	القيمة‬
تسميه	`product`
معرف	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
);

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

	القيمة‬
تسميه	`product`
معرف	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
);

إنشاء حواف

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

إنشاء حافة من المنتج المسمى Montau Turtle Surfboard يستبدل بالمنتج Kiama classic surfboard .
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
تلميح

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

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

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

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

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

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

var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

اكتب إلى وحدة التحكم السلسلة [CREATED PRODUCT]\t68719518403الثابتة . بعد ذلك، قم بالتكرار فوق كل ذروة مطابقة باستخدام foreach حلقة واكتب إلى وحدة التحكم رسالة تبدأ ب [REPLACES PRODUCT] وتتضمن حقل المنتج id المطابق كلاحقة.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

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

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

افتح المحطة الطرفية في مجلد مشروع .NET.
استخدم dotnet run لتشغيل التطبيق.
```
dotnet run
```

لاحظ الإخراج من التطبيق.

[CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

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

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

إنشاء متغير shell ل resourceGroupName إذا لم يكن موجودا بالفعل.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
استخدم az group delete لحذف مجموعة الموارد.
```
az group delete \
    --name $resourceGroupName
```

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

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

مشاركة عبر