تمرين - كتابة البيانات باستخدام روابط الإخراج

مكتمل

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

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

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

هل لاحظت خطوة أخرى في المخطط الانسيابي؟ حتى الآن، لم نفعل الكثير مع البيانات التي تلقيناها من حيث المعالجة. نحن ننقل ما نتلقاه في قاعدة بيانات. ولكن في حالة استخدام حل حقيقي، ربما نعالج البيانات بطريقة ما. يمكننا القيام بجميع المعالجة في نفس الوظيفة، ولكن في هذا التمرين، نعرض نمطا يلغي تحميل المزيد من المعالجة إلى مكون آخر أو جزء من منطق العمل.

ما الذي قد يكون مثالاً جيداً لتفريغ العمل في سيناريو الإشارات المرجعية لدينا؟ حسنا، ماذا لو أرسلنا الإشارة المرجعية الجديدة إلى خدمة توليد رمز الاستجابة السريعة؟ وبدورها تنشئ هذه الخدمة شفرة الاستجابة السريعة لعنوان URL، وتخزن الصورة في Blob Storage، وتضيف عنوان صورة شفرة الاستجابة السريعة إلى الإدخال في مجموعة الإشارات المرجعية خاصتنا. يستغرق استدعاء خدمة لإنشاء صورة الاستجابة السريعة وقتا طويلا. لذلك بدلا من انتظار النتيجة، نقوم بتسليم المهمة إلى دالة والسماح لها بإكمال هذه المهمة بشكل غير متزامن.

تماماً كما يدعم Azure Functions روابط الإدخال لمصادر تكامل مختلفة، فإنها تحتوي أيضاً على مجموعة من القوالب لربط المخرجات لتسهيل كتابة البيانات إلى مصادر البيانات. يتم تكوين روابط الإخراج أيضا في ملف function.json . كما ترى في هذا التمرين، يمكننا تكوين وظيفتنا للعمل مع مصادر وخدمات بيانات متعددة.

هام

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

إنشاء وظيفة تم تشغيلها في بروتوكول نقل نص تشعبي

1. في مدخل Microsoft Azure، انتقل إلى تطبيق الدالة الذي قمت بإنشائه عن طريق تحديد اسم تطبيق الدالة في مسار التنقل أعلى صفحة دالة HttpTrigger2.

2. في علامة التبويب Functions في صفحة Overview ، يجب أن يكون لديك وظائف مشغل HTTP التي قمت بإنشائها.

3. حدد Create في علامة التبويب Functions . يظهر جزء Create function .

4. ضمن قسم Select a template ، حدد HTTP trigger، ثم حدد Next. اقبل الإعدادات الافتراضية في علامة التبويب تفاصيل القالب وحدد إنشاء. سيظهر جزء نظرة عامة لوظيفة HttpTrigger3.

إضافة رابط إدخال قاعدة بيانات Azure Cosmos

دعنا نضِف ربط إدخال Azure Cosmos DB آخر.

1. في قائمة الوظائف HttpTrigger3، حدد Integration. يظهر جزء Integration.

2. في مربع Trigger and inputs ، حدد Add input. يظهر جزء Create Input.

3. في القائمة المنسدلة Binding Type، حدد Azure Cosmos DB.

4. يجب ملء إعداد اتصال حساب Cosmos DB مسبقا بالاتصال الذي أنشأته في التمرين السابق.

   إذا كنت لا ترى اتصالك مدرجاً، فاتبع هذه الخطوات لإنشاء اتصال جديد.

   1. في قسم Azure Cosmos DB details، ضمن إعدادات Cosmos DB account connection، حدد ارتباط New.

   2. عند ظهور مربع الحوار New Cosmos DB connection حدد OK لإنشاء الاتصال. تم إنشاء اتصال حساب Cosmos DB جديد.

5. أدخل القيم التالية للإعدادات الأخرى في هذا الجزء. في أي وقت، لمعرفة المزيد حول الغرض من أحد الإعدادات، يمكنك تحديد أيقونة المعلومات على يمينه.

   الإعداد	قيمة	‏‏الوصف
   اسم معلمة المستند	bookmark	الاسم المستخدم لتعريف هذا الرابط في رمزك.
   اسم قاعدة البيانات	func-io-learn-db	قاعدة البيانات للعمل معها. هذه القيمة هي اسم قاعدة البيانات التي قمنا بتعيينها مسبقًا في هذا الدرس.
   اسم المجموعة	Bookmarks	اسم المجموعة التي تتم قراءة البيانات منها. لقد حددنا هذا الإعداد مسبقاً في الدرس.
   معرف المستند	{id}	أضف {id} لاستخدام تعبير الربط الصحيح وقبول المعلمة التي تم تمريرها في سلسلة الاستعلام.
   ⁧ مفتاح التقسيم⁧	{id}	مرة أخرى، أضف {id} لاستخدام تعبير الربط الصحيح وقبول المعلمة التي تم تمريرها في سلسلة الاستعلام.
   استعلام SQL (اختياري)	اتركه فارغا	نقوم باسترداد عنصر واحد فقط في كل مرة استنادا إلى المعرف. لذلك، تعتبر تصفية إعدادات المستند أفضل من استخدام استعلام SQL في هذا المثيل. يمكننا صياغة استعلام SQL لإرجاع إدخال واحد (SELECT * from b where b.ID = /id). سيُعيد الاستعلام بالفعل عنصراً ولكنه سيعود في مجموعة مستندات. يجب أن يتلاعب رمزنا بمجموعة بشكل غير ضروري استخدم نهج استعلام SQL عندما تريد الحصول على مستندات متعددة.

   مثل ربط الإدخال الذي أنشأناه في التمرين السابق، نريد البحث عن إشارة مرجعية بمعرف محدد، لذلك ربطنا Document ID الذي تتلقاه دالتنا في سلسلة الاستعلام بالربط، والذي يُعرف باسم binding expression. مشغل الدالة هو طلب HTTP يستخدم سلسلة استعلام لتحديد المعرف للبحث عنه. يرجع الربط إما 0 (غير موجود) أو 1 (تم العثور عليه).

6. حدد Add لحفظ تكوين ربط الإدخال.

لدينا الآن رابط إدخال قاعدة بيانات Azure Cosmos. دعنا نضِف رابط الإخراج حتى نتمكن من كتابة إدخالات جديدة إلى مجموعتنا.

إضافة رابط إخراج قاعدة بيانات Azure Cosmos

1. في جزء Integration لـ HttpTrigger3، في مربع Outputs، حدد Add output. يظهر جزء Create Output.

2. ضمن نوع الربط، من القائمة المنسدلة، حدد Azure Cosmos DB.

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

4. أدخل القيم التالية للإعدادات المتبقية لربط الإخراج.

   الإعداد	قيمة	‏‏الوصف
   اسم معلمة المستند	newbookmark	الاسم المستخدم لتعريف هذا الرابط في رمزك. يتم استخدام هذه المعلمة لكتابة إدخال إشارة مرجعية جديدة.
   اسم قاعدة البيانات	func-io-learn-db	قاعدة البيانات للعمل معها. هذه القيمة هي اسم قاعدة البيانات التي قمنا بتعيينها مسبقًا في هذا الدرس.
   اسم المجموعة	Bookmarks	اسم المجموعة التي تتم قراءة البيانات منها. هذه القيمة هي اسم الحاوية الذي حددناه سابقا في الدرس.
   ⁧ مفتاح التقسيم⁧	/id	أضف مفتاح القسم الذي حددناه عندما أنشأنا حاوية الإشارات المرجعية Azure Cosmos DB في وقت سابق. يجب أن يتطابق المفتاح الذي تم إدخاله هنا (المحدد في تكوين ربط الإدخال <key>) مع المفتاح الموجود في الحاوية.

5. حدد Add لحفظ تكوين ربط الإخراج هذا.

الآن لدينا رابط نقرأه من مجموعتنا، وملزم للكتابة عليه.

إضافة رابط إخراج "تخزين قائمة انتظار Azure "

تخزين قائمة انتظار Azure هو خدمة لتخزين الرسائل التي يمكن الوصول إليها من أي مكان في العالم. يمكن أن يصل حجم رسالة واحدة إلى 64 كيلوبايت، ويمكن أن تحتوي قائمة الانتظار على ملايين الرسائل - حتى السعة الإجمالية لحساب التخزين الذي تم تعريف قائمة الانتظار فيه. يوضح الرسم البياني التالي، على مستوى عالٍ، كيفية استخدام قائمة الانتظار في السيناريو الخاص بنا.

في هذا المثال، ترى أن دالة تسمى add-bookmark تضيف رسائل إلى قائمة انتظار، وأن دالة أخرى تسمى gen-qr-code تنبثق الرسائل من نفس قائمة الانتظار، وتعالج الطلب. نظرا لأننا نكتب أو ندفع الرسائل إلى قائمة الانتظار من إشارة مرجعية إضافية، نضيف ربط إخراج جديدا إلى الحل الخاص بك.

لنقم بإنشاء الارتباط من خلال المدخل.

1. في جزء Integration الخاص بوظيفتك، في المربع Outputs، حدد Add Output. يظهر جزء Create Output.

2. في القائمة المنسدلة Binding Type، حدد تخزينAzure Queue Storage.

   إذا ظهرت رسالة تطالبك بتثبيت الامتداد Microsoft.Azure.WebJobs.Extensions.Storage، فحدد install وانتظر حتى ينتهي.

بعد ذلك، قمنا بإعداد اتصال حساب تخزين، حيث تتم استضافة قائمة الانتظار الخاصة بنا.

1. ضمن Storage account connection، حددNew. يظهر مربع الحوار New Storage Account connection.

2. في بداية هذه الوحدة، عندما أنشأت تطبيق وظيفتك، تم أيضاً إنشاء حساب تخزين لك. حدده من القائمة المنسدلة، ثم حدد OK.

   يتم تعبئة الإعداد Storage account connection باسم الاتصال.

على الرغم من أنه يمكننا الاحتفاظ بالقيم الافتراضية، فلنقم بتغيير بعض الإعدادات لإضفاء المزيد من المعنى على الخصائص المتبقية.

1. أكمل الإعدادات في جزء Create Output، عن طريق استبدال القيم القديمة التالية بالقيم الجديدة:

   الإعدادات	قيمة قديمة	قيمة جديدة	‏‏الوصف
   اسم معلمة الرسالة	outputQueueItem	newmessage	خاصية الربط التي نستخدمها في التعليمات البرمجية.
   اسم قائمة الانتظار	outqueue	الإشارات المرجعية - بعد المعالجة	اسم قائمة الانتظار حيث نضع الإشارات المرجعية بحيث يمكن لوظيفة أخرى معالجتها بشكل أكبر.

2. حدد Add لحفظ تكوين الإخراج الخاص بك ل Azure Queue Storage.

تحديث تنفيذ الوظيفة

جميع عمليات الربط الخاصة بنا جاهزة للإعداد الآن. حان الوقت لاستخدامهم في وظيفتنا.

1. لفتح الملف index.js في محرر التعليمات البرمجية، حدد وظيفتك HttpTrigger3.

2. في القائمة، حدد Code + Test. يظهر جزء Code + Test الخاص بالوظيفة.

3. استبدل جميع الشفرات الموجودة في ملف index.js بالتعليمة البرمجية من القصاصة البرمجية التالية، وفي شريط الأوامر بعد ذلك، حدد Save.

   module.exports = function (context, req) {
   
       var bookmark = context.bindings.bookmark;
       if(bookmark){
               context.res = {
               status: 422,
               body : "Bookmark already exists.",
               headers: {
               'Content-Type': 'application/json'
               }
           };
       }
       else {
           
           // Create a JSON string of our bookmark.
           var bookmarkString = JSON.stringify({ 
               id: req.body.id,
               url: req.body.url
           });
   
           // Write this bookmark to our database.
           context.bindings.newbookmark = bookmarkString;
   
           // Push this bookmark onto our queue for further processing.
           context.bindings.newmessage = bookmarkString;
   
           // Tell the user all is well.
           context.res = {
               status: 200,
               body : "bookmark added!",
               headers: {
               'Content-Type': 'application/json'
               }
           };
       }
       context.done();
   };
   

دعونا نغير ما تفعله هذه الأكواد:

• حيث تغير هذه الوظيفة البيانات الخاصة بنا، نتوقع أن يكون طلب نشر بروتوكول نقل نص تشعبي، وبيانات الإشارة المرجعية جزءًا من نص الطلب.
• يحاول ربط إدخال Azure Cosmos DB استرداد مستند أو إشارة مرجعية id باستخدام ما نتلقاه. إذا عثر على إدخال، يتم تعيين العنصر bookmark. if(bookmark) يتحقق الشرط لمعرفة ما إذا كان قد تم العثور على إدخال.
• تعد الإضافة إلى قاعدة البيانات بسيطة مثل تعيين معلمة context.bindings.newbookmark الربط إلى إدخال الإشارة المرجعية الجديدة، والتي أنشأناها كسلسلة JSON.
• يعد نشر رسالة إلى قائمة الانتظار الخاصة بنا أمرا بسيطا مثل تعيين المعلمة context.bindings.newmessage .

إشعار

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

.

1. حدد function.json من القائمة المنسدلة في المسار وقم <functionapp> \ HttpTrigger3 \ بإجراء التغييرات التالية:

   1. تغيير كافة مثيلات "collectionName" إلى "containerName".
   2. تغيير كافة مثيلات "connectionStringSetting" إلى "connection".
   3. احذف المراجع إلى "methods": [].

2. يجب أن يشبه ملف function.json النهائي هذه التعليمة البرمجية.

   {
     "bindings": [
       {
         "authLevel": "function",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "methods": [
           "get",
           "post"
         ]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "name": "bookmark",
         "direction": "in",
         "type": "cosmosDB",
         "partitionKey": "{id}",
         "databaseName": "func-io-learn-db",
         "containerName": "Bookmarks",
         "connection": "your-database_DOCUMENTDB",
         "id": "{id}"
       },
       {
         "name": "newbookmark",
         "direction": "out",
         "type": "cosmosDB",
         "partitionKey": "/id",
         "databaseName": "func-io-learn-db",
         "containerName": "Bookmarks",
         "connection": "your-database_DOCUMENTDB"
       },
       {
         "name": "newmessage",
         "direction": "out",
         "type": "queue",
         "queueName": "bookmarks-post-process",
         "connection": "your-storage-account_STORAGE"
       }
     ]
   }
   

3. في شريط الأوامر، حدد Save.

إذًا، هذا كل شيء. دعونا نرَ عملنا في القسم التالي.

1. لفتح ملف run.ps1 في محرر التعليمة البرمجية، حدد الدالة HttpTrigger3 من مسار التنقل أعلى الجزء.

2. في قائمة الدالة، ضمن Developer، حدد Code + Test. يظهر جزء Code + Test لدالة HttpTrigger3، ويعرض المحتوى الافتراضي لـ run.ps1.

3. استبدل المحتوى الموجود في الملف بالتعليمة البرمجية التالية.

   using namespace System.Net
   
   param($Request, $bookmark, $TriggerMetadata)
   
   if ($bookmark) {
       $status = 422
       $body = "Bookmark already exists."
   }
   else {
       $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }
   
       Push-OutputBinding -Name newbookmark -Value $newBookmark
   
       Push-OutputBinding -Name newmessage -Value $newBookmark
   
       $status = [HttpStatusCode]::OK
       $body = "bookmark added!"
   }
   
   Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
       StatusCode = $status
       Body = $body
       ContentType = "application/json"
   })
   

4. حدد حفظ في شريط الأدوات. يتم إجراء اتصال وفتح جلسة ملف السجل.

دعونا نغير ما تفعله هذه الأكواد:

• حيث تغير هذه الوظيفة البيانات الخاصة بنا، نتوقع أن يكون طلب نشر بروتوكول نقل نص تشعبي، وبيانات الإشارة المرجعية جزءًا من نص الطلب.
• يحاول ربط إدخال Azure Cosmos DB الخاص بنا استرداد مستند أو إشارة مرجعية باستخدام id في الطلب. إذا عثر على إدخال، يتم تعيين العنصر bookmark. if ($bookmark) يتحقق الشرط لمعرفة ما إذا كان قد تم العثور على إدخال.
• تعد الإضافة إلى قاعدة البيانات بسيطة مثل استدعاء Push-OutputBinding باسم ربط إخراج Cosmos DB (newbookmark) وقيمة $newBookmark الكائن.
• يعد نشر رسالة إلى قائمة الانتظار الخاصة بنا أمرا بسيطا مثل الاتصال Push-OutputBinding باسم ربط إخراج قائمة الانتظار (newmessage) وقيمة $newBookmark الكائن.

إشعار

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

إذًا، هذا كل شيء. دعونا نرَ عملنا في القسم التالي.

عليك تجربة ذلك

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

1. في شريط الأوامر بجزء Code + Test لوظيفة HttpTrigger3، حدد Test/Run. يظهر جزء جديد، مع فتح علامة تبويب Input، كما هو موضح في هذه الصورة:

   

2. في القائمة المنسدلة HTTP method تحقق من تحديد POST.

3. استبدل محتويات الطلب Body بعنصر JSON التالي:

   {
       "id": "docs",
       "url": "https://learn.microsoft.com/azure"
   }
   

4. حدد تشغيل.

5. يظهر التقدم الآلي في جزء Logs. عند الانتهاء، تحقق من أن علامة التبويب Output تعرض "إشارة مرجعية موجودة بالفعل". في إعداد HTTP response content.

   

   قمت بإضافة عنصر الإشارة المرجعية في تمرين - قراءة البيانات باستخدام روابط الإدخال. تؤكد الاستجابة أن JavaScript var bookmark = context.bindings.bookmark يعمل بشكل صحيح، وأن التعليمات البرمجية لـ PowerShell تُجري نفس الاتصال.

6. دعنا ننشر إشارة مرجعية ثانية إلى قاعدة البيانات. حدد علامة التبويب Input.

7. استبدل محتويات الطلب Body بعنصر JSON التالي:

   {
       "id": "github",
       "url": "https://www.github.com"
   }
   

8. حدد تشغيل.

9. تحقق من أن علامة التبويب Output تعرض رسالة "تمت إضافة الإشارة المرجعية!" في HTTP response content، كما هو موضح في لقطة الشاشة التالية.

   

تهانينا! وظيفتك تعمل على النحو المصمم! ولكن، ماذا عن عملية الطابور التي أضفناها إلى التعليمة البرمجية؟ حسنًا، دعنا نذهب لنرى ما إذا كان هناك شيء مدون في قائمة الانتظار.

تحقق من كتابة رسالة إلى قائمة الانتظار

تتم استضافة قوائم انتظار تخزين Azure في حساب تخزين. قمت بتكوين حساب التخزين عندما أنشأت ربط الإخراج.

1. في شريط البحث العالمي في مدخل Microsoft Azure، أدخل storage accounts، ثم في قائمة النتائج، حدد Storage accounts. يظهر جزء Storage accounts.

   

2. حدد حساب التخزين الذي استخدمته لتكوين ربط إخراج newmessage.

3. في قائمة Storage account، ضمن Data storage، حدد قوائم الانتظار لإدراج قوائم الانتظار التي يستضيفها حساب التخزين هذا. تحقق من إدراج قائمة انتظار bookmarks-post-process، كما هو موضح في لقطة الشاشة التالية.

   

4. حدد bookmarks-post-process لسرد الرسائل الموجودة في قائمة الانتظار. إذا تم عرضها وفقًا للخطة، تتضمن قائمة الانتظار الرسالة التي قمت بنشرها عند إضافة إشارة مرجعية إلى قاعدة البيانات. يجب أن تبدو كما يلي.

   

   في هذا المثال، تم منح الرسالة معرفاً فريداً، ويعرض العمود نص الرسالة إشارتك المرجعية بتنسيق JSON. لا توجد رسالة للإشارة المرجعية Azure docs التي حاولت إضافتها لأنها موجودة بالفعل في قاعدة البيانات.

5. يمكنك اختبار الدالة بشكل أكبر عن طريق تغيير نص الطلب في جزء الاختبار مع مجموعات المعرّف/رابط موقع جديد وتشغيل الوظيفة. شاهد قائمة الانتظار هذه لمشاهدة وصول المزيد من الرسائل. يمكنك أيضا إلقاء نظرة على قاعدة البيانات للتحقق من إضافة إدخالات جديدة.

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