البدء السريع: إنشاء إطار .NET أو تطبيق أساسي باستخدام حساب Azure Cosmos DB لواجهة برمجة التطبيقات Gremlin

مقالة
05/10/2022
قراءة خلال 10 دقائق

ينطبق على: واجهة برمجة تطبيقات Gremlin

Azure Cosmos DB هي خدمة قاعدة بيانات متعددة النماذج موزعة عالميًّا من Microsoft. يمكنك إنشاء مستند ومفتاح/قيمة وقواعد بيانات الرسم البياني والاستعلام عنها بسرعة، وكلها تستفيد من التوزيع العالمي وقدرات المقياس الأفقي في صميم Azure Cosmos DB.

يوضح هذا البدء السريع كيفية إنشاء حساب Azure Cosmos DBلواجهة برمجة تطبيقات Gremlin قاعدة بيانات ورسم بياني (حاوية) باستخدام مدخل Azure. ثم تقوم بإنشاء وتشغيل تطبيق وحدة تحكم تم إنشاؤه باستخدام برنامج التشغيل مفتوح المصدر Gremlin.Net.

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

أحدث إصدار Visual Studio مع أحمال عمل تطوير Azure. يمكنك البدء باستخدام بيئة التطوير المتكامل IDE المجانيةلمجتمع Visual Studio. بادر بتمكين حمل عمل تطوير Azure أثناء إعداد Visual Studio.

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

أنشئ «حساب قاعدة البيانات».

في نافذة مستعرض جديدة، سجل الدخول إلى مدخل Azure.
في القائمة اليمنى، حدد "إنشاء مورد" .
في صفحة جديدة، حدد "قواعد البيانات">Azure Cosmos DB.

في الصفحة إنشاء حساب Azure Cosmos DB، أدخل إعدادات حساب جديد Azure Cosmos DB.

إعداد	القيمة	الوصف
الاشتراك	اسم الاشتراك	حدد اشتراك Azure الذي تريد استخدامه لحساب Azure Cosmos DB هذا.
مجموعة الموارد	اسم مجموعة الموارد	حدد مجموعة موارد، أو حدد إنشاء جديد، ثم أدخل اسمًا فريدًا لمجموعة الموارد الجديدة.
اسم الحساب	إدخال اسم فريد	أدخل اسماً فريداً لتعريف حساب Azure Cosmos DB الخاص بك. سيتم إلحاق URI بحسابك gremlin.azure.com باسم حسابك الفريد. لا يمكن أن يستخدم اسم الحساب سوى الأحرف الصغيرة والأرقام والواصلات (-)، ويجب أن يتراوح طولها بين 3 و44 حرفاً.
واجهة برمجة التطبيقات (API)	Gremlin (رسم بياني)	تحدد واجهة API نوع الحساب المراد إنشائه. يوفر Azure Cosmos DB خمس واجهات برمجة التطبيقات: الأساسية (SQL) لقواعد بيانات المستند، وGremlin لقواعد بيانات الرسم البياني، وMongoDB لقواعد بيانات المستندات، وجدول Azure، وكاساندرا. يجب إنشاء حساب منفصل لكل API. حدد Gremlin (الرسم البياني) ، لأنه في هذه البداية السريعة تقوم بإنشاء جدول يعمل مع واجهة برمجة تطبيقات Gremlin. تعرف على المزيد عن واجهة برمجة تطبيقات Gremlin.
‏‏الموقع	المنطقة الأقرب إلى مستخدميك	حدد موقعًا جغرافيًا لاستضافة حساب Azure Cosmos DB. استخدم الموقع الأقرب إلى المستخدمين لمنحهم أسرع وصول إلى البيانات.
وضع السعة	معدل النقل أو من دون خادم	حدد Provisioned throughput لإنشاء حساب في وضع معدل النقل المتوفر. حدد Serverless لإنشاء حساب في وضع دون خادم.
تطبيق Azure Cosmos DB خصم الطبقة الحرة	تطبيق أو عدم تطبيق	مع Azure Cosmos DB الطبقة الحرة، سوف تحصل على أول 1000 RU / ثانية و25 غيغابايت من التخزين مجانًا في حساب. تعرف على المزيد حول الطبقة المجانية.

ملاحظة

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

The new account page for Azure Cosmos DB

في علامة تبويب Global Distributionكوّن التفاصيل التالية. يمكنك ترك القيم الافتراضية لغرض هذه البداية السريعة:

إعداد	القيمة	الوصف
التكرار الجغرافي	تعطيل	تمكين التوزيع العمومي على حسابك أو تعطيله عن طريق إقران منطقتك بمنطقة زوج. يمكنك إضافة المزيد من المناطق إلى حسابك لاحقًا.
كتابات متعددة المناطق	تعطيل	تتيح لك إمكانية الكتابة متعددة المناطق الاستفادة من الإنتاجية المقدمة لقواعد البيانات والحاويات الخاصة بك في جميع أنحاء العالم.

ملاحظة

الخيارات التالية غير متوفرة إذا قمت بتحديد دون خادمباعتبارهاوضع السعة:

Apply Free Tier Discount
التكرار الجغرافي
كتابات متعددة المناطق

اختياريًا يمكنك تكوين تفاصيل إضافية في علامات التبويب التالية:
- شبكة الاتصال - تكوين الوصول من شبكة اتصال ظاهرية.
- نهج النسخ الاحتياطي - تكوين نهج النسخ الاحتياطي الدوري أو المستمر.
- التشفير - استخدم إما مفتاحًا مُدارًا بواسطة الخدمة أو مفتاحًا مُدارًا من قِبل العميل.
- العلامات - العلامات هي أزواج الاسم/القيم التي تمكنك من تصنيف الموارد وعرض الفوترة الموحدة من خلال تطبيق نفس العلامة على موارد متعددة ومجموعات موارد متعددة.
حدد Review + create.
يستغرق إنشاء الحساب بضع دقائق. انتظر البوابة لعرض التهاني! تم إنشاء صفحة حساب Azure Cosmos DB الخاصة بك.

إضافة رسم بياني

يمكنك الآن استخدام أداة Data Explorer في بوابة Azure لإنشاء قاعدة بيانات الرسم البياني.

حدد Data Explorer>New Graph.

يتم عرض منطقة "Add Graph" في أقصى اليمين، قد تحتاج إلى التمرير إلى اليمين لرؤيتها.

في الصفحة "Add graph" ، أدخل إعدادات الرسم البياني الجديد.

الإعداد	القيمة المقترحة	الوصف
معرف قاعدة البيانات	نموذج قاعدة البيانات	أدخل "sample-database" كاسم لقاعدة البيانات الجديدة. يجب أن تحتوي أسماء قواعد البيانات من 1 إلى 255 حرفاً، ولا يمكن أن تحتوي على `/ \ # ?` أو مسافة زائدة.
معدل النقل	400 RUs	غيّر الإنتاجية إلى 400 وحدة طلب في الثانية (RU/s). إذا كنت تريد تقليل زمن الانتقال، يمكنك زيادة الانتاجية لاحقاً.
Graph ID	نموذج الرسم البياني	أدخل "sample-graph" كاسم لمجموعتك الجديدة. تتضمن أسماء الرسم البياني متطلبات أحرف مُعرَّفات قاعدة البيانات نفسها.
مفتاح القسم	/pk	تحتاج جميع حسابات Cosmos DB إلى مفتاح قسم لتوسيع النطاق أفقياً. تعرف على كيفية تحديد مفتاح قسم مناسب في مقالة تقسيم بيانات الرسم البياني.

بمجرد تعبئة النموذج، حدد "OK" .

استنساخ نموذج التطبيق

الآن دعونا نستنسخ تطبيق واجهة برمجة تطبيقات Gremlin من GitHub، عيِّن سلسلة الاتصال، وشغلها. سترى مدى سهولة العمل مع البيانات برمجيًّا.

افتح موجه الأوامر، وأنشئ مجلدًا جديدًا باسم git-sample، ثم أغلق موجه الأوامر.
```
md "C:\git-samples"
```
افتح نافذة المحطة الطرفية لـ git، مثل git bash، واستخدم الأمر cd للتغيير إلى المجلد الجديد لتثبيت نموذج التطبيق.
```
cd "C:\git-samples"
```
شغّل الأمر الآتي لاستنساخ نموذج المستودع. يقوم هذا الأمر بإنشاء نسخة من نموذج التطبيق على جهاز الكمبيوتر لديك.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
```
ثم افتح أستوديو مرئيًّا وافتح ملف الحل.
استعادة حزم NuGet في المشروع. ينبغي أن يشمل ذلك برنامج التشغيل Gremlin.Net، وأيضاً الحزمة Newtonsoft.Json.
يمكنك أيضًا تثبيت مشغّل النسخة 3.4.6 من Gremlin.Net يدوياً باستخدام مدير حزمة Nuget، أو أداة Nuget المساعدة لسطر الأوامر:
```
nuget install Gremlin.NET -Version 3.4.6
```

ملاحظة

تدعم واجهة برمجة تطبيقات Gremlin حاليًّا فقط Gremlin.Net حتى v3.4.6. إذا قمت بتثبيت أحدث إصدار، فستتلقى أخطاء عند استخدام الخدمة.

استعراض الكود

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

يتم أخذ كافة المقتطفات التالية من الملف برنامج.cs.

تعيين معلمات الاتصال استنادًا إلى الحساب الذي تم إنشاؤه أعلاه:

private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");

private static bool EnableSSL
{
    get
    {
        if (Environment.GetEnvironmentVariable("EnableSSL") == null)
        {
            return true;
        }

        if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
        {
            throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
        }

        return value;
    }
}

private static int Port
{
    get
    {
        if (Environment.GetEnvironmentVariable("Port") == null)
        {
            return 443;
        }

        if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
        {
            throw new ArgumentException("Invalid env var: Port is not an integer");
        }

        return port;
    } 
}

يتم عمل قائمة بأوامر Gremlin ليتم تنفيذها في قاموس:

private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
{
    { "Cleanup",        "g.V().drop()" },
    { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
    { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
    { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
    { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
    { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
    { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
    { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
    { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
    { "CountVertices",  "g.V().count()" },
    { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
    { "Project",        "g.V().hasLabel('person').values('firstName')" },
    { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
    { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
    { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
    { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
    { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
    { "CountEdges",     "g.E().count()" },
    { "DropVertex",     "g.V('thomas').drop()" },
};

إنشاء كائنات اتصال GremlinServer جديدة GremlinClient باستخدام المعلمات المتوفرة أعلاه:

string containerLink = "/dbs/" + Database + "/colls/" + Container;
Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                        username: containerLink, 
                                        password: PrimaryKey);

ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
{
    MaxInProcessPerConnection = 10,
    PoolSize = 30, 
    ReconnectionAttempts= 3,
    ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
};

var webSocketConfiguration =
    new Action<ClientWebSocketOptions>(options =>
    {
        options.KeepAliveInterval = TimeSpan.FromSeconds(10);
    });


using (var gremlinClient = new GremlinClient(
    gremlinServer, 
    new GraphSON2Reader(), 
    new GraphSON2Writer(), 
    GremlinClient.GraphSON2MimeType, 
    connectionPoolSettings, 
    webSocketConfiguration))
{

تنفيذ كل استعلام Gremlin باستخدام GremlinClient الكائن مع مهمة متزامنة. يمكنك قراءة استعلامات Gremlin من القاموس المُعرف في الخطوة السابقة وتنفيذها. في وقت لاحق احصل على النتيجة واقرأ القيم التي يتم تنسيقها كقاموس، وذلك باستخدام JsonSerializer الفئة من حزمة Newtonsoft.Js:

foreach (var query in gremlinQueries)
{
    Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));

    // Create async task to execute the Gremlin query.
    var resultSet = SubmitRequest(gremlinClient, query).Result;
    if (resultSet.Count > 0)
    {
        Console.WriteLine("\tResult:");
        foreach (var result in resultSet)
        {
            // The vertex results are formed as Dictionaries with a nested dictionary for their properties
            string output = JsonConvert.SerializeObject(result);
            Console.WriteLine($"\t{output}");
        }
        Console.WriteLine();
    }

    // Print the status attributes for the result set.
    // This includes the following:
    //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
    //  x-ms-total-request-charge   : The total request units charged for processing a request.
    //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
    PrintStatusAttributes(resultSet.StatusAttributes);
    Console.WriteLine();
}

تحديث سلسلة الاتصال

الآن العودة إلى مدخل Azure للحصول على معلومات سلسلة الاتصال ونسخها إلى التطبيق.

من مدخل Azure، انتقل إلى حساب قاعدة بيانات الرسم البياني. في علامة التبويب نظرة عامة، يمكنك مشاهدة نقطتي نهاية-

.NET SDK URI - يتم استخدام هذه القيمة عند الاتصال بحساب الرسم البياني باستخدام مكتبة Microsoft.Azure.Graphs.

نقطة النهاية Gremlin - يتم استخدام هذه القيمة عند الاتصال بحساب الرسم البياني باستخدام مكتبة Gremlin.Net.

لتشغيل هذا النموذج، انسخ قيمةنقطة النهاية Gremlin، احذف رقم المنفذ في النهاية، وهذا سيصبح هو الـ URIhttps://<your cosmos db account name>.gremlin.cosmosdb.azure.com . يجب أن تبدو قيمة نقطة النهاية وكأنها testgraphacct.gremlin.cosmosdb.azure.com
بعد ذلك، انتقل إلى علامة التبويب مفاتيح وانسخ قيمة المفتاح الأساسي من مدخل Azure.
بعد نسخ URI وPRIMARY KEY لحسابك، احفظهما في متغير بيئة جديد على الجهاز المحلي الذي يشغل التطبيق. لتعيين متغير البيئة، افتح نافذة موجه الأوامر، ثم قم بتشغيل الأمر التالي. تأكد من استبدال قيم <Your_Azure_Cosmos_account_URI> و<Your_Azure_Cosmos_account_PRIMARY_KEY>.
```
setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
```
افتح ملف البرنامج.cs وحدِّث "قاعدة البيانات" و"حاوية" المتغيرات مع أسماء قاعدة البيانات والحاوية (وهي أيضًا اسم الرسم البياني) التي تم إنشاؤها أعلاه.

private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";
حفظ ملف ⁧⁩«Program.cs»⁧⁩

لقد قمت بتحديث تطبيقك الآن بجميع المعلومات التي يحتاجها للتواصل مع Azure Cosmos DB.

قم بتشغيل تطبيق وحدة التحكم

اضغط CTRL + F5 لتشغيل التطبيق. سيقوم التطبيق بطباعة كل من أوامر الاستعلام Gremlin والنتائج في وحدة التحكم.

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

تصفح باستخدام مستكشف البيانات

يمكنك الآن العودة إلى مستكشف البيانات في مدخل Azure لعرض بيانات رسمك البياني الجديد والاستعلام عنه.

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

يمكنك تكبير الرسم البياني وتصغيره، كما يمكنك توسيع مساحة عرض الرسم البياني وإضافة قمم إضافية وتحريك القمم على سطح العرض.

مراجعة اتفاقيات على مستوى الخدمة في مدخل Microsoft Azure

مدخل Azure يراقب معدل نقل حساب Cosmos DB والتخزين والتوفر وزمن الانتقال والتناسق. المخططات الخاصة بالمقاييس المقترنة بـ اتفاقية مستوى خدمة Azure Cosmos DB (SLA) تعرض قيمة اتفاقية مستوى الخدمة مقارنة بالأداء الفعلي. هذه المجموعة من المقاييس تجعل مراقبة اتفاقيات مستوى الخدمة الخاصة بك شفافة.

لمراجعة المقاييس واتفاقيات مستوى الخدمة:

حدد المقاييس في قائمة التنقل في حساب Cosmos DB.
حدد علامة تبويب مثل زمن الانتقال، وحدد إطارًا زمنيًا على اليسار. قارن الأسطر الفعلية واتفاقية مستوى الخدمة على المخططات.
راجع المقاييس في علامات التبويب الأخرى.

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

عند الانتهاء من تطبيقك وحساب Azure Cosmos DB، يمكنك حذف موارد Azure التي أنشأتها حتى لا تتحمل المزيد من الرسوم. لحذف الموارد:

في شريط البحث في مدخل Azure، ابحث عن مجموعات المواردوحددها.
من القائمة، حدد مجموعة الموارد التي أنشأتها لهذه البداية السريعة.
في صفحة نظرة عامة على مجموعة الموارد، حدد حذف مجموعة الموارد.
في النافذة التالية، أدخل اسم مجموعة الموارد لحذفها، ثم حدد Delete.

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

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

الاستعلام باستخدام Gremlin

البدء السريع: إنشاء إطار .NET أو تطبيق أساسي باستخدام حساب Azure Cosmos DB لواجهة برمجة التطبيقات Gremlin

هل هذه الصفحة مفيدة؟

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

أنشئ «حساب قاعدة البيانات».

إضافة رسم بياني

استنساخ نموذج التطبيق

استعراض الكود

تحديث سلسلة الاتصال

قم بتشغيل تطبيق وحدة التحكم

تصفح باستخدام مستكشف البيانات

مراجعة اتفاقيات على مستوى الخدمة في مدخل Microsoft Azure

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

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