البحث في الموقع

سنتعرف في هذا المقال على مفهوم واجهة برمجية التطبيقات Application Programming Interface، هذا المصطلح السهل المعقد حيث سنحاول فهمه وكيفية بناء مواقع الويب والتطبيقات الحديثة في يومنا هذا بالاعتماد على الواجهات البرمجية ونجيب على سؤال مهم وهو كيف ترتبط الواجهة الأمامية مع الواجهة الخلفية لتطبيق الويب أو الموقع الإلكتروني. هذا المقال هو جزء من سلسلة مقالات حول الواجهة البرمجية API وكيفية الاستفادة منها في بناء تطبيق ويب: مدخل إلى الواجهات البرمجية API الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية مفهوم الواجهة البرمجية للتطبيقات API قبل أن ندخل في أية تفاصيل تقنية عن موضوعنا اليوم، سأحكي لك يومًا في حياة علي. علي هو مبرمج تطبيقات ويب يعمل في إحدى الشركات التقنية العربية، علي يحب تجربة المأكوﻻت المختلفة، بحيث يجرب في كل يوم أكلة جديدة في المطاعم المحيطة وإن سمع بافتتاح مطعم جديد بالقرب من مكان عمله، فإنه ﻻ يتوانى في زيارته وتذوق مختلف اﻷطباق التي يقدمها. ذهب علي ﻷحد المطاعم التي فتحت أبوابها مؤخرا، واختار مكانا هادئًا ونادى النادل يسأله عن اﻷطباق التي يقدمونها من أجل أن يأخذ طلبيته إلى الطباخ لتحضير ما طلبه علي. دوَّن النادل ما يريد علي تناوله من مأكوﻻت وذهب بها إلى الطباخ من أجل تحضيرها، بعد مدة وجيزة، عاد النادل إلى علي وهو يحمل كل ما طلبه وقدمها متمنيا أنه يعجبه اﻷكل، تذوق علي المأكوﻻت وأبدى إعجابه اﻷولي بها، وبدأ في اﻷكل إلى أن أنهى كل ما في الصحون، دفع الحساب، وخرج من المطعم شاكرا النادل على حسن اﻷستقبال. هل تتساءل اﻵن، ما علاقة هذه القصة بالواجهات البرمجية؟ وهل تساءلت يومًا عن طريقة عمل تطبيقات الهواتف الذكية، وكيف تتصل بخوادم الشركات المطورة لها، هل استطعت الوصول إلى إجابات كافية عن ذلك؟ سأبين لك ما العلاقة بين المثال السابق والواجهات البرمجية وكيف أن الواجهات البرمجية ماهي إﻻ تطبيق لمثالنا باختلاف بسيط وهو مكان التطبيق فقط، فمثالنا هو من الواقع الذي نعيشه يوميًا ونراه دائمًا حتى تعودنا عليه حتى أصبحنا ﻻ ندركه، أما الواجهات البرمجية، فقد أصبحت جزءًا ﻻ يتجزأ من حياة مبرمج المواقع وتطبيقات الويب المهنية. كنت قد نوهتك ﻷن تسأل نفسك عن طريقة ربط تطبيقات الهواتف الذكية مع خوادم الشركات. هنالك طريقتين لربط تطبيقات الهواتف الذكية مع خوادم الشركات المطورة، الطريقة اﻷقدم تسمى SOAP وهي اختصار لجملة Simple Object Access Protocol، أما الطريقة اﻷحدث فهي الواجهة البرمجيةللتطبيقات API وهي اختصار لجملة Application Programming Interface، وهي التي سأركز عليها، ولكن باختصار، API هي طريقة لتواصل البرمجيات في ما بينها باستخدام صيغة JavaScript Object Notation والتي تعرف اختصارا بـ JSON. لن أدخل في التفاصيل التاريخية وسأبقى مركزا على الجانب التقني فقط، لهذا أتوقع منك أن تحاول البحث عن تاريخ ابتكار وتطوير تقنية API والتقنية المكملة لها REST والتي هي اختصار لجملة REpresentational State Transfer. مصطلحات وجب معرفتها سنسرد بعض المصطلحات باللغة الإنجليزية والعربية الضروري على كل مطور ويب أن يعرفها: Backend: الواجهة الخلفية، هي المسؤولة عن العمليات المنطقية للنظام، تتعامل مع الملفات أيضا ومع قواعد البيانات. Frontend: الواجهات الأمامية، كل ما يراه المستخدم ويتعامل معه بشكل مباشر، ويتم ربطها مع النظم الخلفية بما يعرف بالواجهة البرمجية للتطبيقات API. API: الواجهة البرمجية للتطبيقات، هي حلقة الوصل ما بين النظم أو الواجهة الخلفية والواجهات الأمامية. Request: الطلب الذي يرسله العميل (قد تكون الواجهة الأمامية) إلى الخادم Server الموجود في الواجهة الخلفية. Header: ترويسة الطلب Request المرسل والذي يحوي بعض البيانات الوصفية التي تصف الطلبية وحالها وأية معلومات إضافية مطلوبة. Body: جسم أو متن الطلب المرسل والذي يحوي غالبًا على البيانات المتبادلة في الطلبية. Response: استجابة أو رد الخادم وهي المعلومات الراجعة من الخادم إلى العميل مقدم الطلب ردًا على طلبه. تحوي المعلومات الراجعة من الخادم إلى العميل على ترويسة Header وأيضا على متن Body. Endpoint: نقطة الوصول، وهي نقطة اتصال الواجهات الأمامية مع موقع محدد في الواجهة الخلفية أي نقطة محددة تتصل عبرها الواجهة الأمامية مع الواجهة الخلفية لغرض محدَّد. HTTP Client Software: عميل خادم HTTP وهو برنامج يساعد على تسريع التعامل مع الواجهات البرمجية بتوفير آلية واضحة في عملية إرسال واستقبال الطلبيات والردود. هل تعرفت على أي من المصطلحات التي ذكرناها قبل قليل؟ لا بأس إن لم تفعل، فسنشرحها لك حتى تكون لديك معرفة مبدئية بموضوع الواجهات البرمجية. لماذا نستخدم الواجهات البرمجية للتطبيقات APIs وما هي فائدتها؟ تُعَد الواجهات البرمجية للتطبيقات طبقة الحماية الأولى First Security Layer للبرمجية الموجودة على خادم الويب، بسبب أنها تفصل ما بين النظم الخلفية والعمليات الجارية على قواعد البيانات عن الواجهات الأمامية سواءً كانت صفحات ويب عادية أو تطبيقات هواتف ذكية. أي أن أي تطبيق ويب أو موقع اليوم يتألف من واجهة خلفية وواجهة أمامية وواجهة برمجية تعد وصلة وصل بينهما. أما الواجهة الخلفية، فتحوي على كامل العمليات والإجراءات والخدمات التي يوفرها التطبيق أو الموقع مثل معالجة صورة أو بيانات أو حتى تقديم خدمة الطقس. أما الواجهة الأمامية فهي الواجهة التي يراها المستخدم والمسؤولة عن عرض البيانات القادمة من الواجهة الخلفية للمستخدم بصورة مناسبة ومتناسقة مع إرسال البيانات من المستخدم إلى الخادم بالشكل الذي يطلبها، فالبيانات المتبادلة تلك تكون بشكلها الخام (تستعمل غالبًا صيغة JSON أو حتى صيغة XML)، أما الواجهة البرمجية للتطبيقات API فهي صلة الوصل كما ذكرنا ووظيفتها استلام البيانات من الواجهة الأمامية وتسلميها للواجهة الخلفية وإرسال البيانات من الواجهة الخلفية إلى الأمامية بطريقة وأسلوب موحد أي هي التي تؤمن عملية التفاهم بين الواجهة الأمامية والخلفية لتأمين التخاطب فيما بينهما. كيف تعمل الواجهات البرمجية للتطبيقات API سأحاول قدر اﻹمكان تبسيط آلية عمل الواجهات البرمجية بمثال عملي من حياتنا اليومية، وليكن مثلا منصة فيسبوك. كما تعلم أنه بإمكانك الدخول إلى حسابك في فيسبوك من أي جهاز تريد، سواءً من هاتفك الذكي أو من جهازك اللوحي أو من جهاز الحاسوب بل بإمكانك الدخول منها مجتمعة وفي نفس الوقت، وهنا يجب أن تطرح سؤاﻻ مهمًا، كيف تتم مزامنة حسابك في كل تلك اﻷجهزة؟ هنا تأتي أهمية الواجهة البرمجية، بحيث أن كل تلك اﻷجهزة متصلة بنظام خلفي واحد وكلها تتصل بالواجهة البرمجية التي تكون حلقة الوصل ما بين كل اﻷجهزة المتصلة و النظام الخلفي. سنأخذ مثاﻻ من حياتنا اليومية وهو موقع فيسبوك، سنقوم بالدخول إلى حسابنا باستخدام الأجهزة التي بحوزتنا، إن لم تكن لديك أجهزة غير جهاز الحاسوب، افتح أكثر من متصفح، ليس نفس المتصفح، مثلا متصفح كروم Google Chrome ومتصفح فايرفوكس Mozilla Firefox، في هذه الحالة يمكنك فتح حسابك 4 مرات باستخدام التصفح الخفي، في متصفح كروم يسمى Incognito Mode أما في متصفح فايرفوكس فيسمى Private Mode. هل قمت بذلك؟ كيف تستطيع إرسال رسائل إلى أصدقائك من أي متصفح وتشاهدها في نفس الوقت من بقية المتصفحات؟ قم بالدخول إلى حسابك على فيسبوك من هاتفك الذكي، من التطبيق الرسمي أو من المتصفح، هل تستطيع أن ترى الرسائل التي قمت بإرسالها على هاتفك أيضا، كيف يحدث ذلك؟ كيف تستطيع الدخول إلى حسابك من أماكن مختلفة في نفس الوقت؟ سأشرح العملية بأكملها بشكل بسيط وبالمقارنة مع مثالنا في بداية المقال وبدون الدخول في التفاصيل الدقيقة في الوقت الحالي. عند دخول علي مطور الويب إلى المطعم، كان عليه أن يختار طاولة محددة برقم حتى يعلم النادل موقعه وأنه يريد تناول الطعام وبالتالي يستطيع تقديم مختلف الخدمات التي يعرضها المطعم. هنا الطاولة وتفاصيلها (من رقم وحجم وغيرهما) تعتبر المكان المتفق عليه من أجل اﻹستفادة من خدمات المطعم، ويمكن القول أنها نقطة الوصول إلى خدمات المطعم Endpoint. في حالة موقع فيسبوك، وعند قيامك فتح التطبيق مثلا، سيتصل تطبيقك بخادم الشركة، في نقطة متفق عليها ومحددة مسبقًا في التطبيق وفيها فقط يستطيع الخادم أن يقدم خدماته للتطبيق. جاء النادل إلى عليٍ والذي يسمى العميل client ليأخذ الطلبات منه، ودون أية ملاحظات أو أي خدمات أخرى، وبعدها ذهب إلى المطبخ ليخبر الطباخ بالطلبات من أجل تحضيرها. هنا نسمي العملية: إرسال طلب Send Request من العميل علي إلى الطباخ في المطعم مقدمة الخدمة. في حالة موقع فيسبوك، أقرب عملية لذلك المثال عملية تسجيل الدخول حيث تُدخل اسم المستخدم الخاص بك مع كلمة المرور، تأخذ الواجهة الأمامية منك هذه المعلومات وترسلها للواجهة الخلفية لموقع فيسبوك لتتحقق منها ومن الطلب الخاص بك، طلب تسجيل الدخول. يستلم الطباخ الطلبية ويتأكد من أنها طلبية صالحة ويمكنك تحضيرها (أي ليست طلبية شراء ملابس مثلًا) ثم يبدأ بتحضيرها وعندما ينتهي منها، يعطيها للنادل الذي يرتبها بدوره في صينية ويأخذها إلى علي ليضعها على طاولته حتى يتسنى له البدء في تذوقها. هذه العملية تسمى: اﻹستجابة Send Response أي استجاب الطباخ لطلبية علي وقدم له ما يريد. وفي حالة موقع فيسبوك، إن كانت المعلومات المقدمة صالحة، سيقوم خادم فيسبوك بالسماح لك بالدخول واستعراض مختلف الصفحات واﻷجزاء الخاصة به والاستفادة من خدمته التي يقدمها. هل اتضحت الصورة العامة اﻵن؟ ببساطة، الواجهة البرمجية تنفذ عمل النادل في المطعم، حيث أن النادل يقوم بأخذ طلبات الزبائن إلى الطباخ وفريقه لتحضيرها وبعد ذلك، يقوم بأخذ تلك استجابة الطباخ لتلك الطلبات إلى أصحابها، أي أن الواجهة البرمجية تأخذ الطلبات من المستخدمين (الواجهة الأمامية) إلى النظام الخلفي لتقوم بعمل محدد ومن ثم تعيد النتائج المتحصل عليها إلى طالبيها أي تعيدها للواجهة الأمامية مرةً أخرى. خاتمة تعرفنا على ماهية الواجهة البرمجية للتطبيقات وأهم المصطلحات فيها وكيف يستفيد منها المطورون في بناء تطبيقات الويب الحديثة واستثمارها في التواصل ما بين الواجهة الأمامية والخلفية لتطبيقات الويب والمواقع الحالية، فالتعامل مع الواجهة البرمجية للتطبيقات ضروري لأي مبرمج متخصص في تطوير الويب، وعليه أن يعي مفهوم الواجهة البرمجة تمامًا إذ أصبح هذا المفهوم هو المفهوم الحديث في التواصل ما بين الواجهة البرمجية الخلفية والأمامية للمواقع وتطبيقات الويب، أضف إلى ذلك أن الكثير من الخدمات والمواقع أصبحت تتيح واجهتها البرمجية (مثل الواجهة البرمجية للمطورين من فيسبوك وتويتر وغيرهما) للاستفادة منها أو حتى هنالك واجهة برمجية مخصصة فقط لتقديم خدمات محددة (مثل واجهة برمجية للحصول على معلومات الطقس) وتقدمها للمطورين للاستفادة من تلك الخدمات في مختلف المشاريع. اقرأ أيضًا المقال التالي: الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد الواجهة البرمجية Fetch API في جافاسكريبت

OAuth 2 هو آليّة للتّرخيص تسمح للتطبيقات بطلب وصول محدود إلى حسابات المستخدمين في خدمات HTTP، مثل Facebook وGitHub وDigitalOcean. يعمل OAuth 2 بتوكيل الخدمة المستضيفة لحساب المستخدم باستيثاق هذا الحساب، ثمّ السّماح للتطبيقات الخارجيّة بالوصول إلى حساب المستخدم هذا. يوفّر OAuth 2 مسارًا لترخيص تطبيقات الويب وتطبيقات سطح المكتب والأجهزة المحمولة. هذا الدّرس موجّه لمطوّري التّطبيقات، وهو يُلقي الضّوء على أدوار OAuth 2 وأنواع الرُّخَص المتاحة، وكذلك يستعرض مجالات استخدامه وسير عمليّة التّرخيص. لنبدأ بالتّعرّف على أدوار OAuth. أدوار OAuth يُحدِّد OAuth أربعة أدوار: مالك المحتوى العميل خادوم المحتوى خادوم التّرخيص سنُفصّل كلًّا من هذه الأدوار في الفقرات التّالية. مالك المحتوى: المستخدم مالك المحتوى هو المستخدم الذي يُرخِّص لتطبيقٍ الوصول إلى حسابه. وصول التّطبيق إلى حساب المستخدم محدودٌ "بنطاق" (scope) الترخيص الممنوح (مثلاً: صلاحيّة القراءة والكتابة). خادوم المحتوى/التّرخيص: الواجهة البرمجيّة (API) يستضيف خادوم المحتوى حسابات المستخدمين المحميّة، ويتحرّى خادوم التّرخيص هويّة المستخدم ثمّ يمنح التّطبيق رمز وصول (access token). من وجهة نظر مطوّر التّطبيقات، فإنّ الواجهة البرمجيّة للخدمة تؤدّي كلا الدّورين، دور خادوم المحتوى ودور خادوم التّرخيص. سنُشير إلى هذين الدّورين مجتمعين على أنّهما دور الخدمة أو الواجهة البرمجيّة. العميل: التّطبيق العميل هو التّطبيق الّذي يريد الوصول إلى حساب المستخدم، وقبل أن يستطيع ذلك، يجب أن يحصل على "ترخيص" المستخدم، وعلى هذا التّرخيص أن يُصادَق من الواجهة البرمجيّة. سير البروتوكول نظريًّا بعد أن تعرّفنا على أدوار OAuth، دعونا نلقِ نظرةً على المخطّط التالي، والذي يبيّن كيف تتفاعل هذه الأدوار فيما بينها: وفيما يلي شرح أكثرُ تفصيلًا للخطوات المُبيّنة في المُخطّط: يطلب التطبيق رخصةً للوصول إلى الخدمة من المستخدم إن رخّص المستخدم الطّلب، فإنّ التطبيق يحصل على إذن بالتّرخيص يطلب بعدها التطبيق رمز وصول (access token) من خادوم التّرخيص (الواجهة البرمجيّة) مُقدّمًا ما يُثبت هوّيته مع إذن التّرخيص الّذي حصل عليه. إن كانت هويّة التّطبيق موثّقة وإذن التّرخيص سليمًا، أصدر خادوم التّرخيص (الواجهة البرمجيّة) رمز وصول (access token) يمنحه للتّطبيق، لتكتمل حينئذٍ عمليّة الترخيص. يطلب التّطبيق من خادوم المحتوى (الواجهة البرمجيّة) المحتوى المطلوب، مُقدّمًا رمز الوصول الّذي حصل عليه. إن كان رمز الوصول سليمًا، قدّم خادوم المحتوى (الواجهة البرمجيّة) المحتوى المقصود للتطبيق قد يختلف مسار العمليّة الفعليّ بحسب نوع الرّخصة المُستخدمة، ولكن هذه هي الفكرة العامّة. سنستعرض أنواع الرُّخَص المُختلفة في فقرة لاحقة. تسجيل التّطبيق قبل استخدام OAuth في تطبيقاتك، عليك تسجيل التّطبيق في الخدمة المعنيّة. يجري التسجيل عادةً من خلال نموذج في قسم المُطوّرين أو الواجهة البرمجيّة في موقع الخدمة على الويب، حيث ينبغي عليك تقديم البيانات التالية (وربّما معلومات أخرى عن تطبيقك): اسم التّطبيق موقع التّطبيق رابط إعادة الّتوجيه (Redirect URL) أو الاستدعاء الرّاجع (Callback URL) تُعيد الخدمة توجيه المستخدم إلى رابط إعادة التّوجيه الّذي توفّره بعد ترخيصه لتطبيق (أو رفضه)، وعليه فإنّ هذا الرابط هو المسؤول عن التّعامل مع رموز الترخيص أو رموز الوصول (access tokens). مُعرّف العميل وكلمة سرّ العميل ستمنحك الخدمة بعد تسجيل تطبيقك "وثائق اعتماد العميل" المؤلّفة من معرّف العميل وكلمة سرّ العميل. معرّف العميل هو سلسلة من الحروف مكشوفة للعموم تستخدمها الواجهة البرمجيّة للخدمة لتحديد هويّة التّطبيق، ولبناء روابط التّرخيص المُقدّمة للمستخدمين. أمّا كلمة سر العميل فتُستخدم للاستيثاق من هويّة التّطبيق بالنّسبة للواجهة البرمجيّة للخدمة عندما يطلب التّطبيق الوصول إلى حساب المُستخدم، ويجب أن تبقى سرّيّة بين التّطبيق والواجهة البرمجيّة. إذن التّرخيص في فقرة "سير البروتوكول نظريًّا"، تبيّن الخطوات الأربع الأولى كيفيّة الحصول على إذن بالتّرخيص ورمز للوصول. يعتمد نوع الإذن على طريقة طلب التّطبيق للتّرخيص، وأنواع الأذون الّتي تدعمها الواجهة البرمجيّة. يعرّف OAuth 2 أربعة أنواع من أذون التّرخيص، يمكن الاستفادة من كلّ منها في حالات مُختلفة: رمز التّرخيص (Authorization Code): تستخدمه التّطبيقات الّتي تعمل على الخواديم ضمنيّ (Implicit): تستخدمه تطبيقات الويب وتطبيقات الأجهزة المحمولة (أي التّطبيقات الّتي تعمل على جهاز المُستخدم) كلمة مرور مالك المحتوى: تستخدمها التّطبيقات الموثوقة، كتلك الّتي تتبع للخدمة ذاتها كلمة مرور العميل: تستخدم في حالة الوصول للواجهة البرمجيّة للتّطبيقات سنشرح أنواع الأذون وحالات استخدامها بالتّفصيل في الفقرات التّالية. الإذن من نوع "رمز الترخيص": هذا النّوع من الأذون هو الأكثر استخدامًا لأنّه مُصمّم للتطبيقات الّتي تعمل على الخواديم، حيث لا يُكشف النّص المصدريّ للتّطبيق للعموم، وحيث يمكن الاحتفاظ بسرّيّة كلمة سرّ العميل بصورة تامّة. ويعتمد سير التّرخيص هنا على إعادة التّوجيه، ممّا يعني أنّه على التّطبيق أن يكون قادرًا على التّفاعل مع وكيل المستخدم (كمتصفّح الويب الّذي يستخدمه) وعلى استقبال رموز التّرخيص الّتي توفّرها الواجهة البرمجيّة والّتي تمرّ من خلال وكيل المستخدم. سنشرح الآن سير عمليّة التّرخيص في هذا النّوع من الأذون: سير التّرخيص بالرّمز الخطوة 1: رابط رمز الترخيص يُعطى المُستخدم في البداية رابطًا لرمز التّرخيص يُشبه هذا: https://cloud.digitalocean.com/v1/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read فيما يلي شرحٌ لمكوّنات الرابط: https://cloud.digitalocean.com/v1/oauth/authorize: نقطة الوصول إلى قسم التّرخيص في الواجهة البرمجيّة client_id=client_id: مُعرّف العميل للّتطبيق (كيفيّة تحديد الواجهة البرمجيّة لهويّة التّطبيق) redirect_uri=CALLBACK_URL: المكان الّذي تعيد الخدمة توجيه وكيل المستخدم إليه بعد منح رمز الترخيص response_type=code: يُبيّن أنّ تطبيقك يطلب إذنًا بالحصول على رمز ترخيص scope=read: يُعيّن مستوى الوصول الّذي يطلبه المُستخدم الخطوة 2: يُرخّص المستخدم التّطبيق عندما ينقر المُستخدم الرّابط، يجب عليه أوّلًا تسجيل الدّخول إلى الخدمة، وذلك للتّحقق من هويّة المُستخدم (ما لم يكن قد سجّل دخوله من قبل). ثم تعرض عليه الخدمة ترخيص أو رفض وصول التّطبيق إلى حسابه. فيما يلي مثال عن صفحة ترخيص التّطبيق: هذه الصّورة مُلتقطة من صفحة ترخيص DigitalOcean، ونرى فيها التّطبيق "Thedropletbook App" يطلب إذنًا بقراءة حساب المُستخدم "manicas@digitalocean.com". الخطوة 3: يتلقّى التطبيق رمز التّرخيص إذا نقر المُستخدم "Authorize Application"، فإنّ الخدمة تُعيد تحويل وكيل المستخدم إلى رابط إعادة التّوجيه الّذي حدّده التّطبيق أثناء تسجيل المُطوِّر له، وتُرفق الخدمة مع الرّابط رمز التّرخيص. مثال على الرّابط (مُفترضين أنّ التّطبيق هو "dropletbook.com"): https://dropletbook.com/callback?code=AUTHORIZATION_CODE الخطوة 4: يطلب التّطبيق رمز الوصول (Access Token) يطلب التّطبيق من الخدمة رمز وصول، مُمرّرًا لها رمز التّرخيص مع تفاصيله، بما في ذلك كلمة سرّ العميل، والّتي تُرسل جميعها إلى رابط الحصول على رمز الوصول الخاصّ بالخدمة. فيما بلي مثال على طلب POST يُرسل إلى رابط رمز الوصول في DigitalOcean: https://cloud.digitalocean.com/v1/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL الخطوة 5: يتلقّى التّطبيق رمز الوصول إن كان التّرخيص سليمًا، فإنّ الواجهة البرمجيّة تردّ على الطّلب بجواب يحوي رمز الوصول (مع رمز إعادة تجديد الرّخصة، غير إلزاميّ) إلى التّطبيق. يبدو الجواب مثل هذا: {"access_token":"ACCESS_TOKEN","token_type":"bearer","expires_in":2592000,"refresh_token":"REFRESH_TOKEN","scope":"read","uid":100101,"info":{"name":"Mark E. Mark","email":"mark@thefunkybunch.com"}} أصبح التّطبيق الآن مُرخّصًا! وبإمكانه استخدام الّرمز للوصول إلى حساب المُستخدم عن طريق الواجهة البرمجيّة للخدمة، محدودًا بنطاق الوصول، إلى أن تنتهي مدّة الرّمز أو يُسحب التّرخيص. في حال أُصدر رمز إعادة تجديد الرّخصة (refresh token)، فبإمكان التّطبيق استخدامه للحصول على رمز وصول جديد في حال انتهى مدّة السّابق. الإذن الضّمنيّ يُستخدم نوع الأذون الضّمنيّ في تطبيقات الويب (التي تعمل في المتصفح) وتطبيقات الأجهزة المحمولة، حيث يصعب ضمان سرّية كلمة سرّ العميل. يقوم هذا النّوع من الأذون على مبدأ إعادة التّوجيه أيضًا، إلّا أنّ رمز الوصول يُعطى لوكيل المُستخدم ليقوم بدفعه إلى التّطبيق، وبهذا قد يُكشف للمُستخدم وللتّطبيقات على جهازه. لا يتضمّن سير التّرخيص في هذا النّوع هوّيّة التّطبيق، بل يعتمد على رابط إعادة التّوجيه (الّذي سُجّل في الخدمة) للوصول إلى هذا الهدف. لا يدعم هذا النّوع من الأذون رموز إعادة تجديد التّرخيص. يسير التّرخيص في هذا النّوع كما يلي: يُطلب من المُستخدم ترخيص التّطبيق، ثمّ يُمرّر خادوم التّرخيص رمز الوصول إلى وكيل المُستخدم، الّذي ينقله بدوره إلى التّطبيق. إن كُنت مُهتمًّا بالتّفاصيل، فتابع القراءة. سير التّرخيص الضّمنيّ الخطوة 1: رابط التّرخيص الضّمني يُعرض على المُستخدم رابط التّرخيص، الّذي يطلب رمزًا من الواجهة البرمجيّة، يبدو هذا الرّابط مُشابهًا لرابط رمز التّرخيص، باستثناء أنّه يطلب رمز token بدلًا من code (لاحظ نوع الجواب المطلوب "token"): https://oauth.example.com/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read ملاحظة: لا تدعم DigitalOcean حاليًا التّرخيص الضّمني، لذا ذكرنا رابطًا وهميًّا "oauth.example.com". الخطوة 2: يرخّص المُستخدم التّطبيق عندما ينقر المُستخدم الرّابط، يجب عليه أوّلًا تسجيل الدّخول إلى الخدمة، وذلك للتّحقق من هويّة المُستخدم (ما لم يكن قد سجّل دخوله من قبل). ثم تعرض عليه الخدمة ترخيص أو رفض وصول التّطبيق إلى حسابه. فيما يلي مثال عن صفحة ترخيص التّطبيق: نرى في الصّورة التّطبيق "Thedropletbook App" يطلب إذنًا بقراءة حساب المُستخدم "manicas@digitalocean.com". الخطوة 3: يتلقّى وكيل المُستخدم رمز الوصول مع رابط إعادة التّوجيه إذا نقر المُستخدم "Authorize Application"، فإنّ الخدمة تُعيد تحويل وكيل المستخدم إلى رابط إعادة التّوجيه الّذي حدّده التّطبيق أثناء تسجيل المُطوِّر له، وتُرفق الخدمة مع الرّابط رمز الوصول. مثال على الرّابط: https://dropletbook.com/callback#token=ACCESS_TOKEN الخطوة 4: يتبع وكيل المُستخدم مسار إعادة التّوجيه يتبع وكيل المُستخدم رابط إعادة التّوجيه مع احتفاظه برمز الوصول. الخطوة 5: يُرسل التّطبيق نصًّا برمجيًّا لاستخراج رمز الوصول يُعيد التّطبيق صفحة ويب تحوي نصًّا برمجيًّا بإمكانه استخراج رمز الوصول من رابط إعادة التّوجيه الكامل الّذي احتفظ به وكيل المُستخدم. الخطوة 6: يُمرّر رمز الوصول إلى التّطبيق يُنفّذ وكيل المستخدم النّصّ البرمجيّ ويُمرّر رمز الوصول المُستخرَج إلى التّطبيق. أصبح التّطبيق الآن مُرخّصًا! وبإمكانه استخدام الّرمز للوصول إلى حساب المُستخدم عن طريق الواجهة البرمجيّة للخدمة، محدودًا بنطاق الوصول، إلى أن تنتهي مدّة الرّمز أو يُسحب التّرخيص. ملاحظة: لا تدعم DigitalOcean حاليًا التّرخيص الضّمني، لذا ذكرنا رابطًا وهميًّا "oauth.example.com". الإذن بالوصول إلى كلمة مرور مالك المُحتوى في هذا النّوع من التّرخيص، يزوّد المستخدم التّطبيق مباشرةً باسم حسابه وكلمة مروره، ليستخدمها للحصول على رمز الوصول من الخدمة. يجب استخدام هذا النّوع من الأذون في الخوادم عندما لا تكون الأنواع الأخرى مُناسبة فقط. ويجب استخدامه فقط في حال كان التّطبيق موضع ثقة المُستخدم، كأن يكون تابعًا للخدمة ذاتها، أو أن يكون نظام التّشغيل على حاسوب المُستخدم هو ما يطلب الوصول. سير التّرخيص بالحصول على كلمة مرور المُستخدم بعد أن يُعطي المستخدم كلمة مروره للتّطبيق، يطلب التّطبيق رمز الوصول من خادوم التّرخيص. يُشبه طلب POST ما يلي: https://oauth.example.com/token?grant_type=password&username=USERNAME&password=PASSWORD&client_id=CLIENT_ID إن كان اسم المُستخدم وكلمة المرور صحيحين، يُعيد خادوم التّرخيص رمز وصول للتّطبيق ويُصبح التّطبيق مُرخّصًا! ملاحظة: لا تدعم DigitalOcean حاليًا التّرخيص بالحصول على كلمة المرور، لذا ذكرنا رابطًا وهميًّا "oauth.example.com". الإذن بالوصول إلى كلمة مرور العميل في هذا النّوع من التّرخيص، يوفّر التّطبيق طريقة للوصول إلى حسابه الخاصّ على الخدمة. من الأمثلة الّتي يكون فيها استخدام هذا النّوع مُفيدًا أن يرغب التّطبيق بتحديث وصفه أو رابط إعادة التّوجيه المُسجّلين في الخدمة، أو أن يصل إلى بيانات أخرى حول حسابه على الخدمة عن طريق الواجهة البرمجيّة. سير التّرخيص بالحصول على كلمة مرور العميل يطلب التّطبيق رمز الوصول مُرسلًا مُعرَّفه وكلمة مروره إلى خادوم التّرخيص، فيما يلي مثال عن طلب POST: https://oauth.example.com/token?grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET إن كان مُعرّف التّطبيق وكلمة مروره صحيحين، يُعيد خادوم التّرخيص رمز وصول للتّطبيق ويُصبح التّطبيق مُرخّصًا باستخدام حسابه الخاصّ! ملاحظة: لا تدعم DigitalOcean حاليًا التّرخيص بالحصول على كلمة مرور العميل، لذا ذكرنا رابطًا وهميًّا "oauth.example.com". مثال على استخدام رمز الوصول بعد أن يحصل التّطبيق على رمز الوصول، إمكانه استخدام هذا الّرمز للوصول إلى حساب المُستخدم عن طريق الواجهة البرمجيّة للخدمة، محدودًا بنطاق الوصول، إلى أن تنتهي مدّة الرّمز أو يُسحب التّرخيص. فيما يلي مثال عن طلب يُرسل للواجهة البرمجيّة للخدمة باستخدام curl، لاحظ أنّه يتضمّن رمز الوصول: curl -X POST -H "Authorization: Bearer ACCESS_TOKEN""https://api.digitalocean.com/v2/$OBJECT" على فرض أنّ رمز الوصول سليم، فإنّ الواجهة البرمجيّة تُعالج الطّلب حسب ما صُمِّمت؛ وإلّا أعادت الواجهة خطأ "invalid_request"، كما يحدث عند انتهاء مدّة التّرخيص أو استخدام رمز خاطئ. سير الحصول على رمز إعادة تجديد الرُخصة يؤدّي استخدام رمز وصول بعد انتهاء مدّة صلاحيّته إلى "خطأ رمز غير سليم (Invalid Token Error)". في هذه النّقطة، يمكن استخدام رمز إعادة تجديد الرّخصة في حال أُصدَر مع رمز الوصول للحصول على رمز وصول جديد من خادوم التّرخيص. فيما يلي مثال على طلب POST للحصول على رمز وصول جديد مُستخدمين رمز إعادة تجديد: https://cloud.digitalocean.com/v1/oauth/token?grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN الخاتمة إلى هناك نكون قد وصلنا إلى ختام دليل OAuth. من المُفترض أن لديك الآن فكرة جيّدة عن البروتوكول وكيف يعمل، ومتى يمكن استخدام كلّ نوع من الأذون. إذا أردت تعلّم المزيد عن OAuth 2، اطّلع على هذه المصادر القيّمة (بالإنكليزيّة): How To Use OAuth Authentication with DigitalOcean as a User or Developer How To Use the DigitalOcean API v2 The OAuth 2.0 Authorization Framwork ترجمة (بشيء من التّصرّف) لمقال Introduction to OAuth 2 لصاحبه Mitchell Anicas.

إن كنت مطور ويب أو أحد المهتمين بتطوير الأنظمة المعلوماتية المختلفة في بيئة الويب، فإنك تعلم حجم التنوع الكبير للغات البرمجة المستخدمة في تطوير مواقع الويب وخدماته، ولربما كنت أحد مطوري هذه الخدمات وترغب بأن تكون خدماتك سريعة الانتشار وسهلة الاستخدام من قبل التطبيقات المختلفة ، وكما تعلم فإن كثرة لغات البرمجة المستخدمة في تطوير خدمات الويب تجعل من الصعب التواصل والتكامل بين هذه التطبيقات. إن المصطلح REST وهو اختصار لـ Representational state transfer يعبر عن المعمارية المستخدمة في تطوير خدمات الويب، التي تهدف إلى وضع معايير تضبط إدارة موارد الأنظمة resources وتحدد كيفية عنونتها ونقلها عبر بروتوكل HTTP إلى طيف واسع من التطبيقات المختلفة بغض النظر عن لغات البرمجة التي طورت بها تلك التطبيقات، وتعد معمارية REST أكثر معماريات تصميم الويب هيمنة خلال السنوات الماضية وذلك لسهولة استخدامها والتعامل معها. بعد التعرف على RESTful ستكون قادر على الانطلاق لتصميم الخدمة الخاصة بك دون القلق بشأن من سيستخدم الخدمة الخاصة بك.

تعرفنا في المقال اﻷول على الواجهة البرمجية للتطبيقات API وكيفية استعمالها في تطوير المواقع وتطبيقات الويب على ماهية الواجهات البرمجية وأسس عملها ولماذا نحتاج إليها، وتعلمنا في المقال الثاني، المعنون بـ الاتصال بواجهة برمجة التطبيقات API وفهم عملية الاستيثاق والتصريح كيفية الاتصال بالواجهة البرمجية بصورة صحيحة، وأخذنا مثاﻻ عن ذلك باستخدام الواجهة البرمجية لمنصة زد، وإن كنت تتبعت جميع الخطوات التي ذُكرت في المقالين السابقين، فسنفترض اﻵن أن لديك حساب مطور على منصة زد وأيضا متجر للتجربة عليه أو عد إليهما ثم أكمل بعدهما قراءة هذا المقال. هذا المقال هو جزء من سلسلة مقالات حول الواجهة البرمجية API وكيفية الاستفادة منها في بناء تطبيق ويب: مدخل إلى الواجهات البرمجية API الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية متطلبات مسبقة حتى تستطيع العمل بجميع التجارب، يجب عليك الحصول على كل من مفتاح الوصول Access Token وهو المفتاح المساعد الخاص بحسابك كمطور، وأيضا مفتاح المتجر X-Manager-Token وهو المفتاح المساعد الخاص بالمتجر المنشود الذي ستطبق عليه العملية. يمكنك جلب مفتاح الوصول بعد تفعيل تطبيقك في منصة تطور زد للمطورين أما بخصوص مفتاح المتجر المساعد، فيمكنك جلب واحد من متجر حقيقي منشور أو تجريبي تنشئه بغرض التجربة ولكن يفضل استخدام متجر تجريبي حتى ﻻ يتأثر متجرك الفعلي بأية عمليات تجريبية سنطبقها في هذا المقال (انظر مقال كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد). لن أذكر أنك تحتاج لكل من مفتاح الوصول Access Token ومفتاح المتجر X-Manager-Token واللغة في جميع التجارب التي سنجريها على نقاط وصول الواجهة البرمجية ﻷنها مطلوبة في ترويسات الطلبيات كلها دون استثناء. استعراض العملاء توفر واجهة زد البرمجية إمكانية استعراض العملاء عبر إرسال طلب HTTP من النوع GET إلى نقطة الوصول التالية: /managers/store/customers تستعمل نقطة الوصول هذه لاستعراض بيانات عملاء المتجر الذي حددناه بالمفتاح X-Manager-Token المرسل مع الطلبية وتذكر دومًا أننا سنرسل مع الطلبية متفاح المتجر ومفتاح الوصول مع الطلبية حتى لو لم نذكر ذلك صراحةً. المعلومات المطلوبة: page: ويعني كم من صفحة تريد استعراضها per_page: عدد العملاء المراد استعراضهم في الصفحة الواحدة هذه المعلومات نحتاجها في جميع طلباتنا القادمة، وهي تخص ترقيم الصفحات Pagination لترتيب البيانات في واجهة المستخدم بتنسيق مقبول التي نحصل عليها والتي قد تكون بيانات آلاف العملاء. حسب التوثيق، فإنها ترسل مثل استعلام Query، وبالتالي الطلب سيكون كالتالي: سنرسل الطلب بهذا الشكل للواجهة البرمجية لمنصة زد، وننتظر إجابة الخادم Response والتي ستكون كالتالي: نلاحظ أن الرد يحوي على مفتاح Key تحت اسم customers ونوعه مصفوفة، وفي حالتنا هذه، مصفوفة فارغة ﻷن متجرنا التجريبي ﻻ يحوي عملاء مسجلين فيه. إضافة منتج جديد توفر واجهة زد البرمجة إمكانية إضافة منتج جديد إلى المتجر المحدد بالمفتاح المرسل عبر إرسال طلبية إلى نقطة الوصول التالية: /products المعلومات المطلوبة في الترويسة: STORE_ID: وهو الرقم التعريفي الخاص بالمتجر خاصتك، ستحصل على الرقم التعريفي الخاص بالمتجر من نفس الصفحة التي حصلت منها على مفتاح المتجر X-MANGER-TOKEN ROLE: وهو السماحية الخاصة بك، ويمكن أن تأخذ القيمة Manager أي المدير، أو Customer أي عميل، في حالتنا سنحتاج إلى استخدام السماحية Manager. أما جسم الطلب Request Body فيجب أن يحوي المعلومات التالية: cost: وتعني التكلفة ويجب أن تكون سلسلة نصية string quantity: الكمية ويجب أن تكون سلسلة نصية string keywords: الكلمات المفتاحية ويجب أن تكون مصفوفة من السلاسل النصية name: الاسم، ويكون كائن Object يحوي مفتاحين ar و en description: التوصيف ويجب أن يكون كائنًا يحوي مفتاحين ar و en price: السعر ويكون سلسلة نصية sale_price: سعر البيع ويكون سلسلة نصية weight: الوزن، ويكون كائنا يحوي على مفتاحين unit ويعني وحدة القياس، و value وهي القيمة Is_published: و يجب أن يكون بولياني Boolean، وبالتالي إما True أو False، وتعني هل المنتج معروض للشراء أم ﻻ. سنضيف منتجًا جديدًا عن طريق إرسال طلب باستخدام برنامج Insomnia، وسيكون من نوع Post كالتالي: توضح الصورة التالية نموذج عن جسم الطلبية المرسل بصيغة json: إن كانت كل المعلومات المطلوبة صحيحة، فسيُنشأ المنتج الجديد وإرسال معلومات المنتج على النحو التالي: { "id": "37c99a36-4a43-4c96-8566-6158b0263c74", "sku": "Z.111684.16216931837021275", "parent_id": null, "name": { "ar": "منتج تجريبي", "en": "Testing Product" }, "slug": "منتج-تجريبي", "price": 150.0, "sale_price": 130.0, "formatted_price": "150.00 ر.س ", "formatted_sale_price": "130.00 ر.س ", "currency": "SAR", "currency_symbol": "ر.س ", "attributes": [], "categories": [], "display_order": null, "has_options": false, "has_fields": false, "images": [], "is_draft": false, "quantity": 1000, "is_infinite": false, "html_url": "https://zid.store/madjid/products/منتج-تجريبي", "weight": { "value": 0.5, "unit": "kg" }, "keywords": [ "أكاديمية حسوب", "حسوب", "منتج تجريبي" ], "requires_shipping": true, "is_taxable": true, "structure": "standalone", "seo": null, "sold_products_count": null, "cost": 100.0, "is_published": true, "created_at": "2021-05-22T14:19:43.702509Z", "updated_at": "2021-05-22T14:19:43.702542Z", "description": { "ar": "[\"<h1>من الممكن وضع تنسيقات هنا</h1>\"]", "en": "[\"<h1>You can add HMTL here</h1>\"]" }, "variants": [], "custom_user_input_fields": [], "custom_option_fields": [], "options": [], "related_products": [], "next_product": null, "previous_product": null } استعراض المنتجات تتيح الواجهة البرمجية لمنصة زد استعراض جميع المنتجات المعروضة على المتجر، يكفي فقط أن نرسل طلبا من نوع GET إلى نفس نقطة الوصول السابقة: /products وبنفس ترويسة الطلب Headers السابقة، بحيث تُرسل كل من الترويسة STOREID والترويسة ROLE مع إضافة المفتاحين pagesize وpage كالتالي: سترسل الواجهة البرمجية لمنصة زد ردًا Response يحوي جميع المنتجات الموجودة في المتجر في الوقت الحالي سواء كانت معروضة أو مخفية، الرد سيكون مشابهًا للرد التالي: { "count": 1, "next": null, "previous": null, "results": [ { "id": "37c99a36-4a43-4c96-8566-6158b0263c74", "sku": "Z.111684.16216931837021275", "parent_id": null, "name": { "ar": "منتج تجريبي", "en": "Testing Product" }, "slug": "منتج-تجريبي", "price": 150.0, "sale_price": 130.0, "formatted_price": "150.00 ر.س ", "formatted_sale_price": "130.00 ر.س ", "currency": "SAR", "currency_symbol": "ر.س ", "attributes": [], "categories": [], "display_order": null, "has_options": false, "has_fields": false, "images": [], "is_draft": false, "quantity": 1000, "is_infinite": false, "html_url": "https://zid.store/madjid/products/منتج-تجريبي", "weight": { "value": 0.5, "unit": "kg" }, "keywords": [ "أكاديمية حسوب", "حسوب", "منتج تجريبي" ], "requires_shipping": true, "is_taxable": true, "structure": "standalone", "seo": null, "sold_products_count": null, "cost": 100.0, "is_published": true, "created_at": "2021-05-22T14:19:43.702509Z", "updated_at": "2021-05-22T14:19:43.702542Z" } ] } كل المنتجات موجودة داخل المفتاح results وهي مصفوفة كائنات Array Of Objects. استعراض قائمة البلدان المدعومة ﻻستعراض قائمة جميع البلدان التي تدعمها منصة زد، يكفي أن نرسل طلبا من نوع GET إلى نقطة الوصول التالية: /settings/countries كالعادة، يجب أن تحوي ترويسة Header الطلب على المفاتيح المساعدة ولغة الطلب، وستعيد لنا الواجهة البرمجية لمنصة زد، إجابة Response تحوي على مصفوفة كائنات Array Of Objects تحت مفتاح باسم countries بالشكل التالي: استعراض قائمة المدن للحصول على قائمة المدن المدعومة، يجب أن نرسل طلبا من نوع GET إلى نقطة الوصول التالية: /settings/cities/by-country-id/{country_id} بحيث يتم استبدال country_id بالرقم المعرف الخاص بالبلد الذي نريد استعراض المدن الموجودة فيه، فمثلا لو أردنا استعراض المدن الموجودة في المملكة العربية السعودية، سنرسل الطلب كالتالي: /settings/cities/by-country-id/184 لنجرب الآن إرسال الطلبية وسنحصل على نتيجة مشابهة للرد التالي: في حالة كان الرقم التعريفي الخاص بالبلد صحيحًا، سترسل الواجهة البرمجية قائمة المدن على شكل مصفوفة كائنات Array Of Objects تحوي جميع المدن لذلك البلد كما هو واضح في الصورة السابقة. إضافة وسيلة شحن ﻹضافة وسيلة شحن لمتجرك باستخدام الواجهة البرمجية، يكفي أن نرسل طلبًا من النوع POST لنقطة الوصول التالية: /managers/store/delivery-options/add ترويسات الطلب Headers يجب أن تحوي كل من مفتاح الوصول Access Token ومفتاح المتجر X-Manager-Token واللغة Accept-Language مثل العادة. أما بدن الطلب Body فيجب أن يحوي المعلومات التالية: name: اسم وسيلة الشحن المراد إضافتها. cost: تكلفة الشحن وتكون ثابتة. cod_enabled: وتعني الدفع عند اﻹستلام، وتكون إما 0 لتعطيل الخيار أو 1 لتفعيله. cod_fee: تكلفة الدفع عن اﻹستلام إن كانت موجودة. cities: ويجب أن تحتوي على المعرفات الخاصة بالمدن (تُحصّل من خلال الطلب السابق). delivery_estimated_time_ar: وصف للفترة المتوقعة لوصول المشتريات باللغة العربية. delivery_estimated_time_en: وصف للفترة المتوقعة لوصول المشتريات باللغة اﻹنجليزية. سنرسل طلبًا بالشكل التالي: { "name": "Hsoub Delivery", "cost": "50", "cod_enabled": "1", "cod_fee": "20", "cities": [ 1, 71, 76, 38 ], "delivery_estimated_time_ar": "3 أيام", "delivery_estimated_time_en": "3 days" } عند إرسال الطلب، سنتلقى ردًا Response من الواجهة البرمجية يفيد بأن نقطة الوصول هذه قد حصلت على حمايتها، ولم يعد باﻹمكان الوصول إليها من الواجهة البرمجية باستخدام مفتاح الوصول Access Token الخاص بنا وقت كتابة المقال وقد تصبح متاحة لاحقًا أثناء قراءة المقال. هذا مثال جيد عن رسائل الأخطاء المختلفة التي ممكن أن تعيدها الواجهة البرمجية، ويجب أن تحصن تطبيقك جيدًا بمعالجة أي خطأ يحتمل أن تعيده الواجهة البرمجية، إذ يؤخذ بالحسبان عادة رمز الخطأ (في حالتنا هو 403) ويفترض أن تعرف معنى تلك الرموز أثناء الطوير لتعرف كيف تتصرف مع رموز الأخطاء والحالات التي تهمك، وعمومًا هذا الأمر يحتاج إلى مقال منفصل، ننصحك بالاطلاع على مقال مدخل إلى HTTP ومقال رموز الإجابة في HTTP. خاتمة اﻵن، وقد استعرضنا عددًا من نقاط الوصول التي توفرها الواجهة البرمجية لمنصة زد، وتعرفنا على طرق إرسال الطلبات، دعنا نطبق كل ما تعلمنا إلى الآن في تطبيق عملي يستعمل يستفيد من واجهة زد البرمجية وهو بناء تطبيق بسيط لزيادة وﻻء العملاء مع شرح كيفية تحويل هذا التطبيق إلى مشروع تجاري. اقرأ أيضًا المقال التالي: تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد الواجهة البرمجية Fetch API في جافاسكريبت HTTP - لننطلق: شرح التخاطب بين العميل والخادوم

شرحنا في المقال السابق مدخل إلى الواجهات البرمجية API الفكرة العامة حول الواجهات البرمجية، وكنا قد شبهناها بالنادل في المطعم الذي يأخذ طلبات الزبائن إلى الطباخ والفريق العامل معه من أجل تحضيرها، ومن ثم استلام استجابة الطباخ للطلبية وتوصيلها إلى أصحابها، وهو ما تفعله الواجهات البرمجية بالضبط مع بعض الإختلاف بالنظر إلى طبيعة العمل في مجال التقنية. سنتعرف في هذا المقال أكثر على عملية التواصل التي تنظمها الواجهة البرمجية، ثم سنطبق ذلك عمليًا على واجهة برمجة واخترنا واجهة زد البرمجية للغرض الذي شرحنا في السابق. هذا المقال هو جزء من سلسلة مقالات حول الواجهة البرمجية API وكيفية الاستفادة منها في بناء تطبيق ويب: مدخل إلى الواجهات البرمجية API الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية آلية التواصل وتنظيم عملية الاتصال قبل أن أكمل الحديث عن الواجهة البرمجية، هل سألت نفسك، لماذا ﻻ يذهب الزبائن مباشرةً إلى الطباخ في مقال المطعم السابق ويخبروه بما يريدون تناوله من مختلف الأطباق التي تُقدَّم في المطعم؟ الجواب ببساطة هو أن الطلبيات ستصبح عشوائيةً آنذاك ولن يستطيع الطباخ أن يحضّر أيًا من الطلبات بسبب العشوائية، وقد لا يفهم على الزبون ماذا يريد أي تحصل عشوائية وغموض في الطلب، فكل زبون يطلب طلبيته بصيغة مختلفة عن الآخر قد تكون بلغة أخرى تمامًا. في حالة أخرى، هل يستطيع أي عامل في المطعم أن يكون نادﻻ؟ في هذه الحالة ستكون فوضى أخرى ولكن بدرجة أقل، بحيث هنالك احتمالية كبيرة ﻷن تُحضّر نفس الطلبية أكثر من مرة لنفس الشخص وفي مرات أخرى من الممكن نسيان طلبية زبون آخر، وفي حالة أخرى، لن يكون باﻹمكان معرفة صاحب الطلبية من غيره أو حتى عدم فهم طلبية الزبون. كانت هذه الحالة الخاصة بالمطعم، فلك أن تتخيل كقاميف ستكون في حالة الواجهات البرمجية؟ تقريبا هي نفس الشيء ولكنها بشكل أسوأ بكثير بسبب أن الواجهة البرمجية API تنظِّم الكثير والكثير من الطلبات لعدد كبير جدا من العملاء التي قد تصل إلى أرقام كبيرة وخيالية. حُلت المشكلة في حالة المطعم بتحديد من يستطيع التحدث مع الزبائن وتدريبهم بأخذ الطلبيات إلى الطباخ وفريقه ومن ثم إعادة الاستجابة أو الناتج الذي حُضِّر إلى الزبون نفسه الذي طلبها تحديدًا ولم يسبق أن دخلت مطعمًا ونسي النادل طلبيتي أو جاءني بطلبية أخرى فهل سألت نفسك عن السبب؟ هل رأيته يكتب في ورقة أمامه ويسألك عن اسمك وينظر في الطاولة والموقع برهة ويذهب؟ وهل قلت لنفسك إن تأخر لقد نسيني أو لم يعرفني ثم يعود جالبًا لك طلبيتك التي طلبتها تمامًا دون أي نسيان؟ للنادل آلية يتذكر فيها صاحب كل طلبية وطلبيته بالضبط ولا ينساها مطلقًا والأمر في حالة الواجهة البرمجة مشابه تمامًا. حلت المشكلة السابقة عن طريق ما يسمى المفتاح المساعد Token وهو سلسلة نصية String تخص العميل طالب الخدمة وتميزه تصدرها الواجهة البرمجة غالبًا (سواءً بمقابل مادي أو مجرد التسجيل في منصة مقدم الواجهة البرمجية) بحيث يرسل المفتاح المساعد Token مع كل طلب خدمة إلى الواجهة البرمجية، من ثم تتحقق الواجهة البرمجية من صلاحية المفتاح المساعد، إن كان صالحا، فستُقدَّم الخدمة المطلوبة للعميل، أما إن لم يكن صالحا، فعادةً ما تُرجع رسالة خطأ تفيد بأن المفتاح المساعد غير صالح، أي لا يمكن إلا لأشخاص مخوليين التواصل مع الواجهة البرمجية وإلا لعمت الفوضى وجاء الجميع للاستفادة من الخدمة التي تقدمها الواجهة. التواصل مع واجهة منصة زد البرمجية حتى نفهم أكثر هذه العملية، سنأخذ مثالًا من الحياة العملية، بحيث سنوجه طلبات إلى الواجهة البرمجية لمنصة زد من أجل اﻹستعلام عن بعض الخدمات الخاصة بهم، دعونا نبدأ. قبل أن نبدأ، ستحتاج إلى التالي: حساب مطور على منصة زد برناج إرسال طلبات HTTP مثل Insomnia أو البرنامج الأكثر شهرة Postman (أصبح البرنامج بطيئًا نوعا ما موازنةً ببرنامج Insomnia ولهذا سنستخدم اﻷخير). إنشاء حساب مطور على منصة زد ندخل إلى بوابة المطورين في منصة زد، سنجدها بسيطة وسهلة اﻹستخدام، يكفي فقط أن عنوان بريدك اﻹلكتروني في الخانة المخصصة، كما في الصورة التالية: بعد أن تدخل عنوان بريدك اﻹلكتروني، والضغط على الزر START NOW، سيُعاد توجيهك إلى لوحة تحكم المطورين، أين يمكنك أخذ نظرة عن الواجهة البرمجية لمنصة زد عند الضغط على ZidAPI ﻻكتشاف تفاصيل الواجهة البرمجية لمنصة زد، كما في الصورة الموالية: ستظهر لنا النافذة التالية: وفيها نجد جميع المعلومات اللازمة للاتصال بالواجهة البرمجية لمنصة زد، بحيث ذُكرت جميع نقاط الوصول Endpoints، مع المعلومات التي يجب إرسالها والمعلومات التي ستُحصّل عند كل نقطة وصول. في الجزء Gateway Environments، وعند الضغط على القائمة Production and Sandbox، ستظهر معلومات مهمة، هي نقطة الوصول الرئيسية للواجهة البرمجية، ولكن ما الذي تعنيه Production and Sandbox. ببساطة Production Environment، هي البيئة الإنتاجية للواجهة البرمجية التي عليك استخدامها في مشروعك النهائي المقدم كخدمة للزبائن، بحيث أن كل العمليات التي تحدث فيها، هي عمليات فعلية. أما Sandbox Environment، فهي البيئة التطويرية التجريبية التي تستخدم أثناء عملية التطوير، بحيث أن جميع العمليات التي تتم فيها، هي عمليات تجريبية فقط. في الواجهة البرمجية لمنصة زد، نلاحظ أن اﻹختلاف بين البيئة الإنتاجية والبيئة التطويرية التجريبية طفيف، فهو يمكن فقط في البروتوكول المستخدم HTTP. فهم طلبيات HTTP وأنواعها نريد اﻵن ااتصال بالواجهة البرمجية لمنصة زد، كل المعلومات لدينا ولم يبقى إﻻ عملية اﻹتصال. للقيام بذلك، نحتاج برنامجا ﻹرسال طلبات HTTP، أو ما يسمى باللغة اﻹنجليزية HTTP Client، ولكن ما هو هذا البرنامج، وما هو عمله؟ ببساطة، برنامج HTTP Client، هو وسيط بينك وبين الواجهة البرمجية، بحيث يرسل الطلبات حسب بروتوكول HTTP. هنالك عدة أنواع من الطلبات الخاصة ببروتوكول HTTP، أشهرها GET و POST و PUT و DELETE. كمعلومة جانبية، متصفح اﻹنترنت الذي تعرفه، مثل كروم Google Chrome، وفايرفوكس أو أي متصفح آخر يعتبر HTTP Client، أي لديه القدرة أن يرسل طلبات HTTP للاستزادة في هذه النقطة، سأشرح أنواع طلبيات HTTP وهي: الطلب GET: يستخدم لجلب بيانات من الخادم أو الواجهة البرمجية. الطلب POST: يستخدم ﻹرسال البيانات إلى الخادم أو الواجهة البرمجية. الطلب PUT: يستخدم لتحديث بيانات في الخادم. الطلب DELETE: يستخدم لحذف البيانات على الخادم. استعمال Insomnia لإدارة الطلبيات التجريبية سنستخدم برنامج Insomnia من أجل إرسال الطلبات لواجهة زد البرمجية، يمكنك تنزيل البرنامج من الموقع الرسمي للشركة المطورة. بعد التحميل والتثبيت، ستظهر نافذة البرنامج كما في الصورة: واجهة بسيطة وسهلة اﻹستخدام، أليس كذلك؟ نضغط على الزر New Request ﻹرسال طلب للواجهة البرمجية لمنصة زد: لتسمية الطلب الجديد، يمكنك اختيار أي اسم كان، أو ترك الاسم الافتراضي، ولكن يفضل أن تُسمى الطلبات بأسماء ذات معنى للعمل الذي تنجزه. نوع الطلب، ويمكننا تحديد أي طلب كان حسب حاجتنا وحسب ما تفرضه الواجهة البرمجية. إنشاء وحفظ الطلب الجديد. احفظ الطلب الجديد باسم Get Profiles، لأننا سنتصل بالواجهة البرمجية لمنصة زد من أجل جلب الملفات الشخصية Profiles المتعلقة بحسابنا على منصة زد. التعرف على نقاط الوصول حينما نتصفح صفحة Developer Portal التي وفرتها منصة زد، سنجد توثيقا يخص الواجهة البرمجية لمنصة زد. التوثيق هو شرح لجميع نقاط الوصول Endpoints للواجهة البرمجية، وما هي المعلومات التي عليك إرسالها لكل نقطة وصول والمعلومات التي ستتحصل عليها من نقطة الوصول تلك. تلاحظ أن هناك نقطة وصول تتيح لنا الحصول على الملفات الشخصية Profiles، وهي موجودة على المسار Path: /managers/account/profile تذكر أن علينا إضافة نقطة الوصول الرئيسية للواجهة البرمجية قبل رابط تلك المسارات أو نقاط الوصول الفرعية، وبالتالي يصبح الرابط النهائي الذي علينا توجيه الطلب إليه كالتالي: http://api.zid.dev/app/v1/managers/account/profile ولكن كيف كونا الرابط النهائي لنقطة الوصول هذه؟ اﻷمر بسيط جدا، من التوثيق الخاص بالواجهة البرمجية لمنصة زد، فنجد Servers والتي تحوي الرابط الرئيسي لكل من البيئة الإنتاجية والبيئة التجريبية للواجهة البرمجية. طلب التصريح والاستيثاق من الطلبية بعدها نجد مسار نقطة الوصول Endpoint تمامًا مثل هذا المثال: لكل نقطة وصول معلومات مطلوبة حتى تستطيع الوصول إليها واستخدامها، فمثلا نقطة الوصول الموضح بالصورة تتطلب مُعامِلات Parameters خاصة بها وهي: X-MANAGER-TOKEN: وهو المفتاح المتجر المساعد الذي يخص المتجر اﻹلكتروني المراد تطبيق العملية عليه ولكل متجر في زد مفتاح مساعد خاص به فقط. Accept-Language: وهي اللغة التي تريد أن ترسل لك الواجهة البرمجية الإجابة Response فيها، وتأخذ القيمة ar للغة العربية أو en للغة اﻹنجليزية. الآن، سنرسل الطلب للواجهة البرمجية لمنصة زد، وننتظر الرد: لقد واجهتنا رسالة تفيد بأن علينا إرفاق مفتاح المبرمج المساعد Token مع الطلب حتى يتم التحقق بأننا مخولون للدخول واستعمال نقاط الوصول الخاصة بالواجهة البرمجية، هو نفسه الذي شرحناه آنفًا في بداية المقال فكما ذكرنا أنه يجب أن يكون مصرحًا لك استعمال الواجهة البرمجية وإلا جاء أي أحد واستعملها وستتأكد الواجهة البرمجة من ذلك التصريح وتستوثق منه. تذكر أن العملية مشابهة تمامًا للباب ومفتاحه فلأي مكان باب مثل منزلك عليه باب ولا يخول لأي أحد دخوله إلا من يملك مفتاح الباب، وتخيل أن يكون باب المنزل دون مفتاح أو أن يملك أي أحد مفتاح باب منزلك! العملية هنا نفسها تمامًا. الحصول على مفاتيح التصريح المخولة التوثيق الخاص بالواجهة البرمجية لمنصة زد، يشرح طريقة الحصول على المفتاح المبرمج المساعد أي المفتاح الخاص بك الذي يصرح لك استعمال الواجهة البرمجية، يكفيك أن تتوجه إلى التبويب Subscriptions ومنه أنشئ التطبيق الخاص بك، باستخدام Subscriptions & Key Generation Wizard. سيطلب منك معلومات بسيطة تعريفية بالتطبيق، تابع الصور التالية: عليك الآن أن تنتظر إلى حين الموافقة على التطبيق من طرف فريق منصة زد. بعد أن يوافق فريق منصة زد على تطبيقك، سيصبح لديك حق الاتصال بالواجهة البرمجية لمنصة زد، ولكن بقيت خطوة أخيرة وهي إنشاء مفتاح مساعد Token. هنالك طريقتان: الأولى، عن طريق لوحة التحكم في منصة زد نفسها، بحيث من نفس الصفحة السابقة، نختار التطبيق الذي أنشاناه، ونختار Manage App، وبعدها نختار Sandbox Keys، حتى نستعمل الواجهة البرمجية الخاصة بالتجربة فقط: نضغط على Generate Access Token، لتظهر نافذة منبثقة، تطلب تأكيد توليد المفتاح المساعد Token: بعد الضغط على GENERATE، ستظهر سلسلة نصية متكونة من أحرف وأرقام، علينا نسخها ولصقها في مكان يسهل علينا الرجوع إليه. الطريقة الثانية ﻹنشاء مفتاح مساعد هي أن نتجه إلى التبويب Subscriptions في قسم Zid Developer Portal، ونختار التطبيق الذي أنشأناه سابقًا: نضغط على Sandbox Keys: ثم نضغط بعدها على CURL TO GENERATE ACCESS TOKEN: نختار الرابط الثاني (الطريقة الثانية) ﻹنشاء المفتاح المساعد Access Token ونلضغط على الزر الموجود على الجانب من أجل نسخه، ونفتح برنامج Insomnia: بعدها نختار كما موضح في الصورة: ستظهر نافذة تسألك إن كنت تريد استيراد السطر في نفس النافذة أم نافذة جديدة، اختر ما يناسبك سيُنشَأ طلب جديد من نوع POST مثل الصورة الموالية: اﻵن علينا أن نضيف ترويسة إلى قبل إرسال طلبنا عن طريق الذهاب إلى التبويب Header وإضافته كالتالي: ما الذي يعنيه هذا الجزء من الطلب؟ يعني هذا الجزء ببساطة، إرسال مفتاح فرعي مع الطلب يثبت أن لدينا حسابًا مفعلا في الواجهة البرمجية لمنصة زد حتى يكون بإمكاننا إرسال طلب إنشاء مفتاح مساعد، ولكن من أين أتينا بهته المعلومات؟ هي معلومات موجودة في الرابط الذي نسخناه ولصقناه قبل قليل. إن لم تستوعب الفكرة اﻵن فلا داعي للقلق، سنشرح كل شيء بالتفصيل في المقاﻻت القادمة ويكفي اﻵن أن تضغط على Send، ﻹرسال طلب إنشاء مفتاح مساعد جديد، وسيُرسَل إليك كالتالي: بقيت اﻵن خطوة أخيرة وهي إنشاء متجر تجريبي على منصة زد من أجل التجربة عليه، المنصة تمنحك فترة 14 يوما من أجل اكتشاف خصائص المنصة والتعرف على طريقة التعامل معها (انظر مقال كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد لمزيد من التفاصيل حول كيفية إنشاء متجر). بعد أن تنشئ متجرًا على منصة زد، أدخُل إلى حسابك وتوجه إلى صفحة "اﻹعدادات"، ثم اختر "الربط مع الخدمات"، ثم اضغط على زر "قم بإنشاء رمز المصادقة Manager Token": إنشاء أول اتصال مع الواجهة البرمجية اﻵن وبعد أن توافرت لدينا كل المفاتيح والمعلومات المطلوبة للاتصال بالواجهة البرمجية، يمكننا العودة للطلب الذي أنشأناه سابقا واﻹتصال بالواجهة البرمجية لمنصة زد كالتالي: ﻻحظ أننا ضمنا كلًا من مفتاح المبرمج Access Token ومفتاح المتجر Manager Token في ترويسة Header الطلب تحت تسمية Authorization و X-MANAGER-TOKEN على الترتيب، وهو ما يسمح للواجهة البرمجية لمنصة زد من التحقق من قدرتنا على الوصول إلى نقطة الوصول Endpoint هته وهل نمتلك الصلاحية لذلك وتعرف أيضًا أي متجر بالتحديد نريد تطبيق العمليات عليه. إن كنت قد تساءلت لماذا أضفنا كلمة Bearer قبل السلسلة النصية في Authorization، فببساطة هنالك عدة أنواع من المفاتيح المساعدة ولكن أشهرها هي Basic وBearer، اﻹختلاف بينهما هو في نمط التشفير وفك التشفير فقط. خاتمة تعلمنا في هذا المقال كيفية إنشاء أول اتصال مع واجهة برمجية نموذجية -مثل واجهة منصة زد- بتأمين مفاتيح التصريح المطلوبة وكل المعلومات اللازمة لها وأصبح بإمكانك الآن تطبيق ما تعلمته في المقال على أي واجهة برمجية والاتصال بها والاستفادة من الخدمات التي تقدمها على الوجهة التي تريد. سنتعرف في المقال التالي أكثر على واجهة منصة زد والاتصال بمختلف نقاط وصول الواجهة البرمجية والاطلاع على المعلومات التي يمكن أن تزودنا فيها وكيف يمكن الاستفادة منها. اقرأ أيضًا المقال التالي: أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API التعرف على لوحة تحكم متجر زد الإلكتروني وضبط عمليات المتجر كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد الواجهة البرمجية Fetch API في جافاسكريبت

بعد أن غطينا معظم ما يتعلق بالواجهات البرمجية وكيفية عملها، مرورًا بالتعرف على الواجهة البرمجية لمنصة زد، سنعمل على بناء تطبيق يتصل بالواجهة البرمجية لمنصة زد ويوسع من عمل المتاجر المبنية بتلك المنصة بإضافة ميزة لها وهي زيادة المبيعات بزيادة الاحتفاظ العملاء وكسب ولائهم. هذا المقال هو جزء من سلسلة مقالات حول الواجهة البرمجية API وكيفية الاستفادة منها في بناء تطبيق ويب: مدخل إلى الواجهات البرمجية API الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية فكرة التطبيق فكرة التطبيق سهلة وبسيطة، بحيث سنستخدم نقطة الوصول الخاصة بسلات الشراء المتروكة لاستعراض العملاء الذين تركوا سلة ما دون إتمام عملية الشراء لمتجر ما ومن ثم سنولد عبر نقطة وصول القسائم قسيمة تخفيض Coupons ونرسلها عبر البريد اﻹلكتروني للعملاء لحضهم على استعمال قسيمة التخفيض وإتمام عملية الشراء. يُحدد المتجر بالمفتاح X-Manager-Token الذي سيزودنا به صاحب المتجر الذي يريد الاستفادة من هذا التطبيق وسنستعمل مفتاح متجر تجريبي أثناء عملية التطوير. سيكون بإمكانك استغلال هذا التطبيق وبناء منصة متكاملة لزيادة عملاء متاجر زد الإلكترونية، وبالتالي زيادة المداخيل السلبية Passive Income لأصحاب المتاجر، الأمر الذي يحقق الفائدة والنفع لهم. المتطلبات المسبقة لبناء التطبيق سنبني التطبيق باستخدام تقنية NodeJS كنظام خلفي Backend، مع واجهة مستخدم بسيطة تكفينا فقط ﻻستخدام سهل وسلس للتطبيق، وسنبني التطبيق باستخدام محرك القوالب Template Engine المعروف باسم Pug. يُفترض أن لديك معرفةً مسبقةً ولو قليلةً بالبرمجة باستخدام NodeJS وإطار العمل ExpressJS لهذا لن نتطرق إلى شرحهما. يمكنك استخدام مدير الحزم Package Manager الذي تفضله سواءً NPM أو YARN، سأستخدم YARN في هذا المشروع. تهيئة المشروع لبداية مشروع جديد، يكفي أن تفتح سطر أوامر وتكتب الأمر التالي: yarn init سيسألك مدير الحزم عن معلومات التطبيق الذي تريد إنشاؤه، يكفي أن تجيب بالقبول عن كل الأسئلة دون تعديل. بعدها، سينشئ مدير الحزم ملفًا باسم package.json بهذا المحتوى: { "name": "zid", "version": "1.0.0", "main": "index.js", "license": "MIT" } الآن سنثبت عددًا من الإضافات اللازمة لعمل التطبيق بصورة طبيعية، وسنبدأ بتثبيت إطار العمل ExpressJS عن طريق تنفيذ الأمر التالي في سطر الأوامر: yarn add express بعد انتهاء مدير الحزم من تثبيت ExpressJS، سنثبت مكتبة Nodemon والتي تمكننا من تشغيل خادم دائم للتطبيق بحيث يعيد Nodemon تشغل الخادم آليًا في كل مرة نعدل على شفرة التطبيق. مكتبة Nodemon تستخدم فقط في مرحلة التطوير وليس في البيئة الإنتاجية، لهذا يجب علينا تثبيتها على هذا الأساس، ويكون ذلك باستخدام هذا الأمر: yarn add nodemon --dev الآن، الملف package.json سيظهر كالتالي: { "name": "zid", "version": "1.0.0", "main": "index.js", "license": "MIT", "dependencies": { "express": "^4.17.1" }, "devDependencies": { "nodemon": "^2.0.7" } } الآن أنشئ ملفًا باسم nodemon.json، وهو ملف خاص بإعدادات Nodemon ويجب أن يحتوي على الشفرة التالية: { "ext": "js", "exec": "node index.js" } السطر اﻷول، يعني أن على Nodemon أن يتتبع التغيرات الحاصلة على أي ملف بامتداد js. والسطر الثاني يمثل الأمر المراد تنفيذه عند حصول أي تغيير على أي ملف بالامتداد المحدد. إنشاء أول نقطة وصول من الواجهة الخلفية الآن، دعنا ننشئ أولى نقاط الوصول Endpoint الخاصة بنا. أولًا، نعدّل على ملف package.json ونضيف له سكريبت كالتالي "scripts": { "start": "nodemon" } سيكون الملف النهائي كالتالي: { "name": "zid", "version": "1.0.0", "main": "index.js", "license": "MIT", "dependencies": { "express": "^4.17.1" }, "devDependencies": { "nodemon": "^2.0.7" }, "scripts": { "start": "nodemon" } } الآن كل شيء جاهز. ننشئ ملف جديد باسم index.js يحتوي على الشفرة التالية: import express from "express"; var app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: false })); const port = process.env.PORT || 3000; app.listen(port, () => { console.log(`Server started on ${port}`); }); سنشرح هذه الشفرة المصدرية لأنها أساس كل ما سيأتي لاحقًا. السطرين الأول والثاني: import express from "express"; var app = express(); استدعينا إطار العمل express، بعدها أنشأنا نسخة منه Instance منه باسم app، ومنها سيعمل التطبيق ككل. السطرين الثالث والرابع تخص إطار Express إذ أخبرنا ببساطة Express بأن كل الطلبات Requests ستكون على شكل JSON. السطر الخامس: const port = process.env.PORT || 3000; أنشأنا ثابتًا يحدد رقم المنفذ Port الذي سيعمل عليه الخادم الخاص بنا. بحيث إن كان معرفا كمتغير نظام أو سيؤخذ المنفذ 3000. السطر السادس هو إنشاء الخادم الخاص بالتطبيق والذي سيعمل على المنفذ Port الذي حددناه سابقًا: app.listen(port, () => { console.log(`Server started on ${port}`); }); الآن أضف الشفرة المصدرية التالية مباشرةً بعد السطر الرابع: app.get("/", (req, res) => { res.send(‘Hello Hsoub’); }); سيكون شكل الملف كالتالي: import express from "express"; var app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: false })); app.get("/", (req, res) => { res.send(`Hello Hsoub`); }); const port = process.env.PORT || 3000; app.listen(port, () => { console.log(`Server started on ${port}`); }); سنثبت بعض المكتبات التي سنستخدمها في بناء التطبيق الخاص بنا. نفِّذ الأمر التالي في سطر الأوامر في مجلد المشروع: yarn add axios pug ثبتنا المكتبتين التاليتين: Axios: هو مكتبة مهمتها القيام بإرسال طلبيات HTTP. Pug: مكتبة تخص قوالب لبناء واجهات المستخدم Frontend Templating Engine. هنالك عدة مكتبات تخص بناء واجهات المستخدم، وقع اﻹختيار على مكتبة Pug بسبب أن الشيفرة البرمجية الخاصة بها بسيطة وسهلة القراءة، باﻹضافة إلى أنها متوافقة بامتياز مع إطار العمل ExpressJS. الآن نفّذ الأمر: yarn start ستظهر لك رسالة خطأ تفيد بأنه ﻻ يمكنك استيراد إطار العمل express داخل المشروع عبر import، ويكفي لحل هذه المشكلة فقط أن تضيف السطر التالي إلى الملف package.json: "type": "module", في حالة واجهت رسالة خطأ مثل الرسالة التالية: Error: listen EADDRINUSE: address already in use :::3000 تأكد من إيقاف التطبيقات الأخرى التي تستخدم المنفذ 3000 أو غير المنفذ الخاص بالتطبيق ليكون مثلا 3001: افتح المتصفح، وادخل العنوان التالي: http://localhost:3000 يفترض أن تحصل على الرسالة التالية: تهانينا، أتممت تهئية التطبيق وإنشاء أولى نقاط الوصول Endpoint الخاصة بالواجهة الخلفية فيه باستخدام NodeJS وExpressJS. بناء تطبيق الاحتفاظ بمستخدمي متاجر زد الآن وقد شرحنا باختصار شديد طريقة بناء واجهة خلفية برمجية بسيطة باستخدام تقنية NodeJS وإطار عمل ExpressJS، سننتقل إلى بناء تطبيق بسيط لزيادة ولاء العملاء. قبل أن نبدأ، عليك أن تحاول الاستزادة قدر الإمكان في ما يتعلق بالبرمجة باستخدام NodeJS، وطريقة بناء الواجهات البرمجية، لأن هدفنا هنا هو التطبيق، لهذا لن تجدني أشرح باستفاضة الأمور البسيطة. جلب سلات الشراء المتروكة أنشئ ملفًا جديدًا باسم zid.js يحوي على الشفرة المصدرية التالية: // axios استيراد مكتبة import axios from "axios"; // إنشاء متغير يحمل رابط الواجهة البرمجية const ZidAPI = "https://api.zid.dev/app/v1"; const AbandonedCarts = async () => { const headers = { "X-MANAGER-TOKEN": process.env.MANAGER_TOKEN, Authorization: "Bearer " + process.env.auth, }; try { const getAbandondCarts = await axios.get( `${ZidAPI}/managers/store/abandoned-carts`, { headers: headers, params: { page: 1, page_size: 10, duration: 4 }, } ); if (getAbandondCarts) { return getAbandondCarts.data; } } catch (error) { return error; } }; export default AbandonedCarts; والآن، لنشرح الشيفرة باختصار شديد. بدايةً، استدعينا المكتبة axios من أجل إرسال بطلبات للواجهة البرمجية الخاصة بمنصة زد، ثم أنشأنا ثابتًا باسم ZidAPI ويحوي أساس نقطة الوصول الخاصة بالواجهة البرمجية لمنصة زد. أنشأنا دالة Function غير متزامنة باسم AbandonedCarts ومهمتها هي جلب سلات الشراء المتروكة على متجرنا. أنشأنا داخل تلك الدالة ثابتًا باسم headers، وهو كائن يحتوي على قيمتين مفتاح المتجرX-MANAGER-TOKEN و مفتاح الواجهة البرمجية Authorization. إن لم تعرف من أين حصلنا على هذين المتغيرين فارجع إلى المقالات السابقة. قد أجدك تتساءل ما معنى process.env؟ هي طريقة لحماية مفاتيح الوصول، وذلك عن طريق إضافة المفتاح كمتغير بيئة Environment Variable. فمثلا، في تطبيقنا هذا، حمينا مفتاح الوصول الخاص بالمتجر باسم X-MANAGER-TOKEN. تُنفّذ هذه العملية على نحو فتح سطر الأوامر وإدخال الأمر التالي: export X-MANAGER-TOKEN=value استبدل value بقيمة مفتاح المتجر بدون إضافة مسافة بعد علامة = ونفس الشيء بالنسبة للمتغير Authorization. سنشرح في عجالة طريقة تثبيت WSL2 على نظام التشغيل ويندوز، ومن ثم طريقة إنشاء متغيرات النظام. بداية تأكد من تحديث نظام التشغيل عندك إلى آخر نسخة ممكنة حتى تستطيع الاستفادة من خاصية تثبيت نظام لينكس كنظام ثانوي داخل ويندوز. افتح PowerShell كمستخدم مدير، ونفذ الأمر التالي: dism.exe /online /enable-feature/featurename:Microsoft-Windows-Subsystem-Linux /all /norestart بعد انتهاء تنفيذ الأمر، نحتاج الآن إلى تفعيل خاصية الأنظمة الوهمية Virtual Machine الخاصة بنظام التشغيل ويندوز وذلك عن طريق تنفيذ الأمر التالي في نفس نافذة PowerShell السابقة: dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart بعد انتهاء تنفيذ الأمر، أعد تشغيل جهازك حتى يتسنى للنظام تفعيل جميع الخصائص المطلوبة. علينا الآن تحديث نواة نظام التشغيل لينكس، وذلك بتنزيل آخر تحديث متوفر، بعد انتهاء التنزيل، افتح الملف واتبع الخطوات لتثبيته كأي برنامج آخر. إفتح نافذة PowerShell، ونفذ الأمر التالي: wsl --set-default-version 2 افتح متجر تطبيقات ويندوز وابحث عن Ubuntu وثبِّته مثل أي تطبيق آخر، وبعد الانتهاء أعد تشغيل جهازك. بإمكانك الآن تنفيذ أوامر لينكس داخل نظام ويندوز دون مشاكل. لمزيد من التفاصيل، ارجع إلى مقال تطبيق Hyper-V في ويندوز 10. على أي حال، هنالك طريقة أخرى ﻹضافة متغيرات النظام عن طريق مكتبة dotenv، وتكون كالتالي: في سطر اﻷوامر أدخل الأمر التالي: yarn add dotenv أنشئ ملفًا باسم env. داخل المجلد الرئيسي للتطبيق، وضع بداخله قيمتي مفتاح المتجر ومفتاح الواجهة البرمجية، النتيجة ستكون كالتالي: MANAGER_TOKEN=value auth=value لا تنسى تبديل القيمة value ووضع المفتاح المناسب الخاص بك مكانها. في بداية الملف index.js نضيف الشيفرة البرمجية التالية: import dotenv from "dotenv"; بقي علينا اﻵن أن نضيف شيفرة تخبر إطار Express أننا سنستخدم مكتبة dotenv لجلب متغيرات البيئة من الملف ‎.env عوض استخدام المتغيرات المخزنة فعلا في نظام التشغيل. في ملف index.js وقبل السطر التالي: var app = express(); نضيف ما يلي: dotenv.config(); بإمكانك اﻵن إضافة متغيرات النظام مباشرةً للملف env. دون إضافتها بصورة مباشرة إلى نظام التشغيل. بعد الانتهاء من ضبط متغيرات البيئة، أنشأنا كتلة برمجية باستخدام Try-Catch لتجريب الإتصال بالواجهة البرمجية لمنصة زد. أنشأنا متغيرًا باسم getAbandondCarts وأسندنا إليه القيمة الراجعة من إرسال الطلب إلى الواجهة البرمجية لمنصة زد. بحيث أرسلنا طلب Request من نوع GET، يحمل المعلومات المطلوبة في توثيق الواجهة البرمجية، وهي ترويسة الطلب headers وأيضا استعلامًا Query فيه عدد الصفحات وأيضا عدد العناصر في الصفحة. بعدها تحققنا إن استقبلنا إجابة خادم الواجهة البرمجية لمنصة زد، وفي حالة وجود الإجابة، فإننا نرجع المحتوى خاصتها؛ أما في حالة وجود خطأ، فسننتقل إلى الجزء catch والذي سيرجع قيمة الخطأ مثل رسالة. في آخر الملف، صدرنا الدالة لنستخدمها في مواضع أخرى. الآن ننتقل إلى الملف index.js ونستدعي الملف zid.js بالطريقة التالية: import AbandonedCarts from "./zid.js"; ثم نضيف نقطة وصول جديدة بنفس الطريقة السابقة: app.get("/carts", async (req, res) => { const response = await AbandonedCarts(); const renderedData = response["abandoned-carts"]; res.send(renderedData); }); دعنا نفهم الشيفرة السابقة: أنشأنا نقطة وصول جديدة بحيث تستقبل طلبات من نوع GET أنشأنا ثابتًا جديدًا باسم response بحيث يستقبل إجابة الخادم من الدالة التي أنشأناها سابقًا باسم AbandonedCarts أنشأنا ثابتًا جديدًا باسم renderedData يحمل قيمة فرعية من الثابت response أعدنا محتوى الثابت renderedData لنجرب الآن نقطة الوصول الجديدة، افتح برنامج Insomnia، وأنشئ طلبًا جديدًا من نوع GET لنقطة الوصول التالية: http://localhost:3000/carts وأرسل الطلب، إن لم توجد سلات شراء متروكة، فإن الواجهة البرمجية لمنصة زد، ستعيد لنا مصفوفة فارغة، أما إن وجدت سلات شراء متروكة، ستحصل على مصفوفة مشابهة لهذه: [ { "id": "6718344e-8e2c-4667-b2cd-1178632de6e9", "store_id": "a739c51c-8103-4648-873b-cc3a8ea2dc8a", "session_id": "xQH4imSzunyafhd2QkD2llkjz8qjEKvW", "cart_id": "904142370", "order_id": 7231078, "phase": "completed", "customer_id": 5835, "customer_name": "man", "customer_email": "m.a***at@zid.sa", "customer_mobile": "966550*****", "city_id": 1, "products_count": 1, "reminders_count": 0, "cart_total": 138, "cart_total_string": "138.00 SAR", "created_at": "2021-05-20 08:59:54", "updated_at": "2021-05-20 10:59:35" }, { "id": "33e932a1-0a9f-4468-a8de-c09540f9aa56", "store_id": "a739c51c-8103-4648-873b-cc3a8ea2dc8a", "session_id": "b6fRKKmcwVtLssqQNgvPSEaY2FvzAG7B", "cart_id": "914265844", "order_id": null, "phase": "shipping_address", "customer_id": 3450024, "customer_name": "Mohammad", "customer_email": "asha.k@fast.com", "customer_mobile": "966506766***", "city_id": 1, "products_count": 2, "reminders_count": 0, "cart_total": 504.85, "cart_total_string": "504.85 SAR", "created_at": "2021-05-19 09:09:45", "updated_at": "2021-05-19 12:23:16" } ] أصبحنا الآن قادرين على تتبع كل السلات المتروكة وحالتها والتفاصيل الخاصة بها وفعل أي شيء متاح معها عبر هذه التفاصيل مع كل سلة وهنا مربط الفرس. سننتقل الآن إلى إنشاء واجهة استخدام بسيطة باستخدام محرك القوالب Pug. بناء شريط التنقل وواجهة السلات المتروكة سنبني واجهات التطبيق عبر محركة القوالب Pug وسنبدأ بواجهة السلات المتروكة، ولكن دعنا أول أن نفهم ما هو محرك القوالب. محرك القوالب Template Engine هو نظام قوالب يسمح لنا بإنشاء واجهات الإستخدام على الخادم ومن ثم إخراجها Render للعميل. يمكنك الإطلاع على التوثيق الخاص بمحرك القوالب Pug من الموقع الرسمي الخاص به. أنشئ مجلدًا جديدًا باسم views داخل المجلد الرئيسي للمشروع، وأنشئ ملفًا جديدًا باسم page.pug، ضع بداخله الشيفرة البرمجية التالية: doctype html block head meta(charset='UTF-8') meta(http-equiv='X-UA-Compatible' content='IE=edge') meta(name='viewport' content='width=device-width, initial-scale=1.0') link(href='https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css' rel='stylesheet') body .w-full.max-w-8xl.min-w-0.mx-auto.px-6 .flex.mt-12.bg-white.rounded-md.shadow .w-64.bg-blue-100.rounded-l-md.border-r.border-dashed.border-blue-200 .flex.justify-center.items-center.h-32.text-blue-700.text-center.font-semibold.text-3xl.italic | Loyalty Program .mt-8.border-t.border-blue-200 a.block.py-3.px-6.text-blue-700.font-semibold.border-b.border-blue-200(href='/') | Home a.block.py-3.px-6.text-blue-700.font-semibold.border-b.border-blue-200(href='/carts') | Abandoned Carts a.block.py-3.px-6.text-blue-700.font-semibold.border-b.border-blue-200(href='/coupon') | Coupons a.block.py-3.px-6.text-blue-700.font-semibold.border-b.border-blue-200(href='/loyalty') | Loyalty block content .flex-grow .flex.flex-col.mx-2.mt-1 .px-3.py-4.flex.justify-center لن نشرح صيغة كتابة قوالب pug لأنها بسيطة جدًا، وتحفيزك أيضًا للإطلاع على التوثيق الرسمي الخاص بـ Pug. يتيح محرك القوالب Pug إنشاء كتل برمجية blocks وإعادة استخدامها لاحقا في أي مكان تحتاجه، كمثال على ذلك، هو ما فعلناه في الملف السابق page.pug، بحيث أنشأنا كتلة برمجية سنستخدمها في بقية الصفحات. في الشيفرة البرمجية السابقة التي تخص الملف page.pug، ﻻحظ أننا أنشأنا كتلة block باسم head وأضفنا إليها ما يتعلق بالبيانات الوصفية Metadata، مع إرفاق ملف خاص بإطار TailwindCSS، باستخدام شبكات الوصول CDN. بعدها أضفنا جسم الصفحة تحت ترويسة body، تحتوي على قائمة جانبية. وتحتها أضفنا كتلة جديدة تحت اسم content وهي ما سيحمل مختلف محتوى الصفحات الخاصة بالتطبيق. سنريكم صورةً عن الناتج النهائي المتوقع الحصول عليه: ننتقل اﻵن ﻹنشاء صفحة لعرض قائمة سلات الشراء المتروكة، باستخدام نقطة الوصول التي أنشأناها سابقًا، بحيث سنسترجع مصفوفة الكائنات التي تحصلنا عليها من الواجهة البرمجية والتي تخص متجر العميل، ونستخرج المعلومات التي نحتاجها باستخدام حلقة تكرارية بسيطة. أنشئ ملفًا جديدًا داخل المجلد views باسم abandoned.pug وضع بداخله الشيفرة التالية: extends page.pug block append head title Abandoned Carts block content table.w-full.text-md.bg-white.shadow-md.rounded.mb-6.max-w-6xl.min-w-0.mx-auto.px-6 thead tr.border-b th.text-left.p-1.px-4 Customer Name th.text-left.p-1.px-4 Customer Email th.text-left.p-1.px-4 Customer Mobile th.text-left.p-1.px-4 Products In Cart th.text-left.p-1.px-4 Cart Total(SAR) th.text-left.p-1.px-4 Phase tbody each element in renderedData tr.border-b.bg-gray-100(class='hover:bg-orange-100') td.p-3.px-5=element.customer_name td.p-3.px-5=element.customer_email td.p-3.px-5=element.customer_mobile td.p-3.px-5=element.products_count td.p-3.px-5=element.cart_total td.p-3.px-5=element.phase سأشرح هذا الكود باستفاضة. في السطر اﻷول، عملنًا تمديدًا للقالب اﻷب الذي أنشأناه سابقا، بحيث أن القالب الجديد (القالب ابن) سيأخذ كل محتوى القالب السابق ويضيف عليه ما نريد: extends page.pug أما في السطرين التاليين، طلبنا من محرك القوالب Pug أن يعدل الكتلة block المسمى head في القالب الأب بما تحت هذا السطر، وهنا أعدنا تسمية عنوان الصفحة بـ Abandoned Carts: block append head title Abandoned Carts بعدها أنشأنا جدولًا Table وقسمناه إلى 6 أعمدة تحمل عناوين المعلومات التي نريد عرضها. each element in renderedData في هذا السطر، أنشأنا حلقة تكرارية تستخرج المعلومات المطلوبة من مصفوفة الكائنات Array of Objects التي تحصلنا عليها سابقا، إذ وضعنا المعلومات المطلوبة في سطور حسب نوعيتها. بقيت لنا خطوة واحدة الآن، وهي ربط الصفحة التي أنشأناها مع نقطة الوصول التي سبق و اضفناها. توجه إلى الملف index.js وعدِّل نقطة الوصول السابقة لتكون كالتالي: app.get("/carts", async (req, res) => { const response = await AbandonedCarts(); const renderedData = response["abandoned-carts"]; res.render("abandoned", { renderedData }); }); لاحظ أننا غيرنا السطر الأخير واستبدلنا التابع send بتابع جديد هو render، والذي يأخذ معاملين، المعامل الأول هو القالب، والمعامل الثاني هي البيانات التي ستُعرَض في القالب. يجب التأكد من أن اسم القالب المرسل كمعامل للتابع render هو بنفس الاسم الذي يحمله القالب المعني. يجب التأكد أيضًا أن عنوان المعامل الثاني والمرسل كبيانات للعرض، هي بنفس الأسم الموجود في القالب الذي أُنشئ لهذا الشأن. شغِّل الآن الخادم الخاص بنا عن طريق تنفيذ الأمر: yarn start لم يعمل معك! بل وظهرت الكثير من رسائل الخطأ، صحيح؟ عد إلى ملف index.js وأضف الأسطر التالية مباشرة قبل أول نقطة وصول Endpoint أنشأناها: app.set("views", path.join(__dirname, "views")); app.set("view engine", "pug"); app.use(express.static(path.join(__dirname, "public"))); ما الذي تعنيه تلك الأسطر؟ ببساطة، طلبنا من إطار ExpressJS أن يستخدم Pug كنظام قوالب، وأيضًا أن يتعرف على مسار ملفات القوالب التي أنشأناها والموجودة داخل المجلد views. أما بالنسبة للسطر الأخير، فهي أننا أخبرنا ExpressJS بأن المجلد النهائي للقوالب بعد أن تحدث عملية التصدير/الاستخراج rendering أن يضع الملفات الناتجة في المجلد public. قبل أن تعيد تشغيل الخادم، استورد المكتبة path في بداية الملف، تمامًا بعد استيراد express مع إنشاء ثابت جديد باسم dirname__ والذي سيحوي التابع resolve الخاص بالمكتبة path وبالتالي سيكون الملف index.js كالتالي: import express from "express"; import path from "path"; import AbandonedCarts from "./zid.js"; const __dirname = path.resolve(); var app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: false })); app.set("views", path.join(__dirname, "views")); app.set("view engine", "pug"); app.use(express.static(path.join(__dirname, "public"))); app.get("/carts", async (req, res) => { const response = await AbandonedCarts(); const renderedData = response["abandoned-carts"]; res.render("abandoned", { renderedData }); }); const port = process.env.PORT || 3000; app.listen(port, () => { console.log(`Server started on ${port}`); }); الآن، شغل الخادم الخاص بالتطبيق، وافتح المتصفح وادخل العنوان التالي: http://localhost:3000/carts ستظهر لنا النافذة التالي (اُخفيت معلومات العملاء حفاظا على الخصوصية): تهانينا، لقد أكملت أول صفحات تطبيق. إنشاء قسائم التخفيض Coupons ننتقل الآن إلى بناء صفحة إنشاء قسيمة تخفيض باستخدام الواجهة البرمجية لمنصة زد، يرجى مراجعة التوثيق الخاص بها من أجل معرفة المعلومات المطلوبة. أنشئ ملفًا جديدًا داخل المجلد views باسم coupon.pug وضع الشيفرة البرمجية التالية: extends page.pug block append head title Coupon block content form#form(action='/add-coupon' method='POST').place-items-center.max-w-max.m-4.p-2.bg-white.rounded.shadow-xl p.text-gray-800.font-medium Adding new coupon code div label.block.text-sm.text-gray-00(for='name') Choose a name for the coupon input.w-full.px-5.py-1.text-gray-700.bg-gray-200.rounded(name='name' type='text' required='' placeholder='Coupon Name') .mt-2 label.block.text-sm.text-gray-600(for='code') Coupon Code input.w-full.px-5.py-4.text-gray-700.bg-gray-200.rounded(name='code' type='text' required='' placeholder='Hsoub10') .mt-2 label.block.text-sm.text-gray-600(for='discount_type') Discount Type input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='discount_type' type='text' required='' placeholder='p for percentage and f for fixed') .mt-2 label.text-sm.block.text-gray-600(for='discount') Discount input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='discount' type='text' required='' placeholder='discount') .inline-block.mt-2.pr-1(class='w-1/2') label.block.text-sm.text-gray-600(for='free_shipping') Free Shipping input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='free_shipping' type='text' required='' placeholder='1 to enable, 0 to disable') .inline-block.mt-2.-mx-1.pl-1(class='w-1/2') label.block.text-sm.text-gray-600(for='free_cod') Free Cash on Delivery input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='free_cod' type='text' required='' placeholder='1 to enable, 0 to disable') div label.block.text-sm.text-gray-600(for='total') Total to apply coupon input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='total' type='text' required='' placeholder='Total to apply coupon') .inline-block.mt-2.pr-1(class='w-1/2') label.block.text-sm.text-gray-600(for='date_start') Starting Date input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='date_start' type='text' required='' placeholder='2021-06-01') .inline-block.mt-2.-mx-1.pl-1(class='w-1/2') label.block.text-sm.text-gray-600(for='date_end') Ending Date input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='date_end' type='text' required='' placeholder='2021-12-31') .mt-2 label.block.text-sm.text-gray-600(for='uses_total') Total Using input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='uses_total' type='text' required='' placeholder='1000') .mt-2 label.block.text-sm.text-gray-600(for='uses_customer') Total Using Per Customer input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='uses_customer' type='text' required='' placeholder='5') .mt-2 label.block.text-sm.text-gray-600(for='apply_to') Apply for all Products? input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='apply_to' type='text' required='' placeholder='all or apply_to_array[]') .mt-2 label.block.text-sm.text-gray-600(for='status') Active? input.w-full.px-2.py-2.text-gray-700.bg-gray-200.rounded(name='status' type='text' required='' placeholder='1 to enable, 0 to disable') .mt-4 button.px-4.py-1.text-white.font-light.tracking-wider.bg-gray-900.rounded(type='submit') Add في بداية الملف، استوردنا الشيفرة الموجودة في الملف page.pug والتي تحوي القائمة الجانبية واستيراد إطار TailwindCSS. بعدها أنشأنا نموذج Form لإرسال البيانات إلى نقطة الوصول التي سنبنيها الآن. أنشئ ملفًا جديدًا باسم addCoupon.js ونفّذ ما فعلناه في الملف zid.js ألا وهو استيراد مكتبة Axios من أجل إرسال طلبات إلى الواجهة البرمجية لمنصة زد ولكن هذه المرة بطريقة POST، وهذا حسب التوثيق الخاص بالمنصة: import axios from "axios"; const ZidAPI = "https://api.zid.dev/app/v1"; الآن سنحتاج إلى إنشاء دالة function ونسند إليها مهمة إرسال الطلب إلى الواجهة البرمجية لمنصة زد بالشكل التالي: const AddCoupon = async (couponInfo) => { const headers = { "X-MANAGER-TOKEN": process.env.MANAGER_TOKEN, Authorization: "Bearer " + process.env.auth, }; أنشأنا الدالة تحت اسم addCoupon والتي تأخذ معاملًا واحدًا ويجب أن يكون كائنًا. حددنا ترويسة الطلب الذي سنرسله داخل الثابت headers. الخطوة الثانية هي أن ننشئ ثابتًا constant يحوي جميع المعلومات المطلوبة من طرف الواجهة البرمجية لمنصة زد، الثابت يكون كائنا من أجل أن يحمل جميع المعلومات. const data = { name: couponInfo.name, code: couponInfo.code, discount_type: couponInfo.discount_type, discount: couponInfo.discount, free_shipping: couponInfo.free_shipping, free_cod: couponInfo.free_cod, total: couponInfo.total, date_start: couponInfo.date_start, date_end: couponInfo.date_end, uses_total: couponInfo.uses_total, uses_customer: couponInfo.uses_customer, apply_to: couponInfo.apply_to, status: couponInfo.status, }; الآن ننشئ كتلة Try - Catch لإرسال الطلب للواجهة البرمجية بحيث أنشأنا ثابتًا باسم addCoupon يحوي الطلب المرسل إلى الواجهة البرمجية عن طريق مكتبة Axios كالتالي: try { const addCoupon = await axios.post( `${ZidAPI}/managers/store/coupons/add`, data, { headers: headers, } ); if (addCoupon) { return addCoupon.data; } } catch (error) { return error; } تحققنا من عدم وجود أي خطأ وفي حالة وجود إجابة من الخادم نرجع محتوى الإجابة عن طريق السطر: return addCoupon.data; أما في حالة وجود خطأ، فسيكون الانتقال مباشرةً إلى الجزء catch وهنا سيُسترجع محتوى الخطأ عن طريق السطر: return error; في أخر الملف، نصدِّر الدالة حتى نستطيع استخدامها في أماكن أخرى باستخدام السطر: }; export default AddCoupon; اﻵن نضيف نقطة وصول جديدة Endpoint إلى الملف index.js بنفس الطريقة التي أضفنا بها نقاط الوصول السابقة. استدع في أعلى الملف الملف addCoupon كالتالي: import AddCoupon from ‘./addCoupon.js’ لتكون بداية الملف تمامًا كالتالي: import express from "express"; import dotenv from "dotenv"; import path from "path"; import AbandonedCarts from "./zid.js"; import AddCoupon from "./addCoupon.js"; بعدها سنضيف نقطة الوصول بالشكل التالي: app.post("/add-coupon", async (req, res) => { const data = req.body; const dataToSend = Object.assign({}, data); const response = await AddCoupon(dataToSend); if (response) { res.redirect("/"); } else { res.redirect("/error"); } }); أعتقد أنك قد ﻻحظت أن نقطة الوصول هذه مختلفة بعض الشيء عن سابقاتها، ﻻ تقلق، سأشرح كل شيء بالتفصيل. في السطر اﻷول، أنشأنا نقطة الوصول الجديدة والتي تستعمل POST ﻹرسال البيانات، الرابط سيكون: /add-coupon ﻻحظت أننا أضفنا كلمة مفتاحية جديدة هي async وهي ببساطة تعني أن هنالك عملية ستأخذ وقتا غير معروف لهذا قبل الانتهاء من جميع العمليات المطلوبة، يجب إنهاء العمليات التي تأخذ وقتا، من الأفضل أن تتعرف أكثر على تقنية async/await خصوصا في NodeJS. في السطر الثاني، أنشأنا ثابتا جديدا باسم data والذي يحوي جسم الطلب المرسل Request إلى نقطة الوصول، في هذه النقطة ﻻ يزال جسم الطلب خاما، ويجب أن يُعدَّل ليكون كائنًا Object؛ أما في السطر الثالث، فقد عدّلنا أو تنقية الثابت data باستخدام التابع assign المدمج افتراضيًا في لغة Javascript، أُسنِدت النتيجة إلى الثابت dataToSend. بينما في السطر الرابع، أنشأنا ثابتًا جديدًا باسم response وأسندنا نتيجة الدالة AddCoupon إليه. لاحظ أننا استخدمنا كلمة مفتاحية جديدة هي await قبل الدالة AddCoupon، وهنا طلبنا أن ينتظر NodeJS العملية حتى انتهائها قبل القيام بتنفيذ السطر الموالي. كخطوة أخيرة، وضعنا شرطًا للتحقق إن كنا قد تحصلنا على إجابة من الخادم Response أم ﻻ. في حالة الحصول على إجابة، سيُنفَّذ السطر: res.redirect("/"); وهنا، سيُعاد توجيه المستخدم إلى الصفحة الرئيسية. أما في حالة عدم الحصول على إجابة، فسيُنفَّذ السطر: res.redirect("/error"); ويعني أنه سيُعاد توجيه المستخدم إلى صفحة الخطأ وهي في هذه الحالة نقطة وصول ستُنشأ لاحقًا لعرض رسائل الخطأ. اﻵن، بقيت لنا خطوة أخيرة، وهي إنشاء صفحة يستطيع المتصفح الوصول إليها. ببساطة، ننشئ نقطة وصول جديدة باسم coupon والتي تكون من نوع GET، تعرض فقط القالب coupon الذي سبق وأنشأناه. نقطة الوصول ستكون كالتالي: app.get("/coupon", async (req, res) => { res.render("coupon"); }); شغل خادم التطبيق باستخدام الأمر: yarn start توجه إلى الرابط التالي: http://localhost:3000/coupon إن ظهرت لديك رسالة خطأ مشابهة لهذه الرسالة: Error:/zid-local/views/coupon.pug:5:1 Only named blocks and mixins can appear at the top level of an extending template at makeError (/zid-local/node_modules/pug-error/index.js:34:13) تأكد من إزاحة indentation السطور في الصفحة، ويفضل استعمال إضافة pug (jade) formatter والتي تساعدك في تنسيق الشفرات البرمجية الخاصة بمحرك القوالب Pug. بعد تثبيت اﻹضافة، اضغط على Alt+Shift+F لتنسيق الشيفرة البرمجية وحل المشكلة. سيظهر نموذج إنشاء قسيمة التخفيض التي أنشأناها سابقًا باستخدام الملف coupon.pug: أدخل المعلومات الخاصة بقسيمة التخفيض واضغط على إضافة Add من أجل إرسال المعلومات إلى نقطة الوصول التي اضفناها سابقًا add-Coupon ومنها تُعالَج البيانات وتُرسَل إلى الواجهة البرمجية لمنصة زد. في حالة إنشاء قسيمة التخفيض، فسيوجَّه المستخدِم إلى الصفحة الرئيسية التي نحن بصدد إنشائها، أما في حالة وجود خطأ ما، أو عدم القدرة على إرسال الطلب بطريقة صحيحة، سيُعاد توجيه المستخدم إلى صفحة الخطأ التي أنشأناها سابقًا. إنشاء صفحة الأخطاء اﻵن، أنشئ ملفًا جديدًا داخل المجلد views باسم error.pug وضع بداخله الشيفرة البرمجية التالية: doctype html block head meta(charset='UTF-8') meta(http-equiv='X-UA-Compatible' content='IE=edge') meta(name='viewport' content='width=device-width, initial-scale=1.0') link(href='https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css' rel='stylesheet') body block content style. .gradient { background-image: linear-gradient(135deg, #684ca0 35%, #1c4ca0 100%); } .gradient.text-white.min-h-screen.flex.items-center .container.mx-auto.p-4.flex.flex-wrap.items-center .w-full.text-center.p-4(class='md:w-7/12 md:text-left') .text-6xl.font-medium 404 .text-xl.font-medium.mb-4(class='md:text-3xl') | Oops. This page has gone missing. .text-lg.mb-8 | You may have mistyped the address or the page may have moved. a.border.border-white.rounded.p-4(href='/') Go Home في الملف index.js، أنشئ نقطة وصول جديدة كالتالي: app.get("/error", (req, res) => { res.render("error"); }); اﻷمر بسيط ونقطة الوصول هذه تعرض القالب error.pug الذي أنشأناه قبل قليل، حول أي أخطاء تظهر معك إلى الرابط ‎/error من أجل عرض هذه الصفحة. إنشاء الصفحة الرئيسية للتطبيق لننشئ الصفحة الرئيسية للتطبيق، أنشئ ملفًا جديدًا داخل المجلد views باسم index.pug، ثم ضع الشيفرة التالية بداخله: extends page.pug block append head title Welcome block content .flex.mx-auto.items-center.justify-center.shadow-lg.mt-65.mx-8.mb-4.max-w-lg form.w-full.max-w-xl.bg-white.rounded-lg.px-4.pt-2 .flex.flex-wrap.-mx-3.mb-6 h2.px-4.pt-3.pb-2.text-gray-800.text-lg أضف مفتاح المتجر الخاص بك .w-full.px-3.mb-2.mt-2(class='md:w-full') textarea.bg-gray-100.rounded.border.border-gray-400.leading-normal.resize-none.w-full.h-20.py-2.px-3.font-medium.placeholder-gray-700(class='focus:outline-none focus:bg-white' name='body' placeholder='Paste your store X-MANAGER-TOKEN HERE' required='') .w-full.flex.items-start.px-3(class='md:w-full md:w-full') .-mr-1 input.bg-white.text-gray-700.font-medium.py-1.px-4.border.border-gray-400.rounded-lg.tracking-wide.mr-1(type='submit' class='hover:bg-gray-100' value='Add') الآن، علينا أن ننشئ نقطة الوصول الخاصة بالصفحة الرئيسية، في ملف index.js ننشئ نقطة الوصول كما تعودنا، تستخدم طريقة GET لاستقبال البيانات من الخادم: app.get("/", async (req, res) => { res.render("index"); }); نقطة الوصول هذه بسيطة، بحيث أن رابطها هو الرابط الرئيسي للخادم، وتعرض فقط القالب الخاص بالصفحة الرئيسية، والنتيجة ستكون كالتالي: أضفنا حقلًا لإدخال مفتاح مفتاح الوصول الخاص بالمتجر X-MANAGER-TOKEN ليُستخدم مستقبلًا، وسنشرح سبب إضافة هذا الحقل -الواضح- عند الانتهاء من بناء المنصة. بناء خدمة إرسال رسائل بريد إلكتروني بعد أن استرجعنا واستعراض سلات الشراء المتروكة، وأنشأنا قسيمة تخفيض، علينا الآن إرسال بريد إلكتروني يحمل قسيمة التخفيض التي أنشأناها لأصحاب سلات الشراء المتروكة، من أجل تحفيزهم على إنهاء طلباتهم وبالتالي زيادة مبيعات المتجر الخاص بنا. لإرسال رسائل البريد الإلكتروني بطريقة بسيطة، سنستخدم SendGrid والذي يوفر خدمة إرسال مجاني لرسائل البريد الإلكتروني جيدًا للاستخدام البسيط (أو أي خدمة أخرى تختارها). أنشئ حسابًا على منصة SendGrid وفعل حسابك. بعدها، افتح نافذة سطر أوامر في نفس مجلد التطبيق ونفذ الأمر التالي: yarn add @sendgrid/mail سيثبّت هذا الأمر المكتبة الخاصة بمنصة SendGrid. أنشئ ملفا جديدا باسم mail.js وأضف الشيفرة البرمجية التالية: import sgMail from "@sendgrid/mail"; sgMail.setApiKey(process.env.SENDGRID_API_KEY); const sendMail = async (mailData) => { const msg = { to: mailData.to, // SendGrid أضف البريد اﻹلكتروني الذي سجلت به في منصة from: "info@email.com", subject: mailData.subject, text: mailData.text, html: mailData.html, }; const sendingMail = await sgMail.send(msg); if (sendingMail) { return "Mail has been sent"; } else { console.log("SENDING MAIL ERROR ===> ", sendingMail); return "There was a problem in sending the mail"; } }; export default sendMail; بداية، استوردنا مكتبة منصة SendGrid التي ثبتناها قبل قليل، بعدها أضفنا المفتاح المساعد الخاص بحسابنا على المنصة، والذي تحصل عليه من لوحة التحكم الخاصة بحسابك. أنشأنا دالة باسم sendMail والتي تأخذ معاملًا واحدًا يجب أن يكون كائنًا Object والذي سيحوي المعلومات المطلوبة لإرسال البريد الإلكتروني. أنشأنا ثابتًا جديدًا باسم msg والذي يحوي كل من الحقول التالي: Subject: يمثل عنوان البريد الإلكتروني الذي نريد إرساله From: وهو عنوان البريد الإلكتروني الذي سنرسل منه الرسائل، وهو نفس عنوان البريد الإلكتروني الذي أضفتَه إلى حسابك على منصة SendGrid `Subject: عنوان رسالة البريد الإلكتروني التي سنرسلها. Text: نص رسالة البريد الإلكتروني التي سترسله، يجب أن يكون نصا فقط Html: نفس نص رسالة البريد الإلكتروني، ولكن بإمكانك أن تضيف تنسيقات HTML. أنشأنا ثابتًا باسم sendingMail يحوي القيمة الراجعة من التابع send الخاص بمكتبة SendGrid والتي سترسل رسالة البريد اﻹلكتروني إن كانت جميع المدخلات صحيحة. أنشأنا شرطًا بعدها يتحقق إن كانت هنالك إجابة من الواجهة البرمجية لمنصة SendGrid، إن كانت هنالك إجابة ستُرجَع رسالة تفيد بأنه قد تمت عملية اﻹرسال بنجاح. في حالة عدم وجود إجابة من الواجهة البرمجية أو أرجعَت خطأ، نعرض الخطأ عن السطر الموجود بداخل الجزء الثاني من كتلة الشرط، وبعدها نرجع رسالة تفيد بأن هنالك مشكلة عند إرسال البريد اﻹلكتروني: console.log("SENDING MAIL ERROR ===> ", sendingMail); return "There was a problem in sending the mail"; في النهاية، صدّرنا الدالة من أجل نستخدمها في مختلف أجزاء التطبيق. اﻵن سنضيف نقطة وصول جديدة لمشروعنا، في الملف index.js أضف الشيفرة البرمجية التالية: app.post("/mail", async (req, res) => { const data = req.body; const dataToSend = Object.assign({}, data); const send = await sendMail(dataToSend); if (send) { res.send("mail has been sent"); } else { res.send("there was an error"); } }); متأكد أنك قد تعودت على صيغة إضافة نقاط الوصول إلى المشروع، نقطة الوصول هذه مشابهة جدا لنقطة الوصول السابقة التي أضفناها سابقًا. تركيب أجزاء التطبيق مع بعضها انتهينا إلى الآن من بناء الخصائص اﻷساسية للتطبيق، بقي لنا أن نجمع هذه الخصائص كلها من أجل الوصول إلى هدفنا، وهو إرسال بريد إلكتروني لجميع أصحاب سلات الشراء المتروكة حتى نحفزهم على إكمال عملية الشراء بإرسال قسيمة تخفيض إليهم عن طريق البريد اﻹلكتروني. أنشئ ملفًا جديدًا داخل المجلد views باسم loyalty.pug وضع بداخله الشيفرة البرمجية التالية: extends page.pug block append head title Loyalty block content .wrapper.px-2.w-full p.text3xl.items-center.justify-center Send a coupon code to all abandoned carts form.max-w-sm.bg-gray-100.px-3.py-5.rounded.shadow-lg.my-10.m-auto(action='/loyalty' method='POST') .flex.flex-col.space-y-3 .flex.items-center.bg-white.border.border-gray-100.rounded.px-2 input.w-full.py-2.px-1.placeholder-indigo-400.outline-none.placeholder-opacity-50(type='text' placeholder='Enter Coupon Code' autocomplete='off') button.text-white.bg-indigo-500.px-4.py-2.rounded(type='submit') | Send Coupon الصفحة بسيطة، فيها نافذة فقط ﻹضافة قسيمة التخفيض أنشئ ملفًا جديدًا باسم loyalty.js يحمل الشفرة البرمجية التالية: import AbandonedCarts from "./zid.js"; import sendMail from "./mail.js"; const Loyalty = async (couponCode) => { const getAbandondCarts = await AbandonedCarts(); if (getAbandondCarts) { const response = getAbandondCarts["abandoned-carts"]; if (response) { const getEmails = []; for (let i = 0; i < response.length; i++) { getEmails.push(response[i].customer_email); } const mailData = { to: getEmails, // استخدم عنوان البريد اﻹلكتروني الذي سجلت به from: "info@geekcademy.com", subject: "Special Offer for you", text: "يرجى استخدام قسيمة التخفيض التالية " + couponCode + " من أجل إنهاء طلبك", html: "يرجى استخدام قسيمة التخفيض التالية " + couponCode + " من أجل إنهاء طلبك", }; return await sendMail(mailData); } else { return "There was an error getting abandoned carts"; } } else { return "There is a server error"; } }; export default Loyalty; بداية استوردنا كل من دالة جلب سلات الشراء المتروكة AbandonedCarts ودالة إرسال رسائل البريد اﻹلكتروني. بعدها أنشأنا دالةً جديدةً تحت اسم Loyalty والتي ستدمج الدالتين السابقتين بحيث ستجلب سلات الشراء المتروكة أوﻻ، ومن ثم التحقق من وجود المعلومات المطلوبة: const getEmails = []; هنا أنشأنا ثابتًا جديدًا يمثل مصفوفة فارغة، ستوضع عناوين البريد المستخرجة من المعلومات التي حُصِّلت عليها من سلات الشراء المتروكة لعملاء المتجر، بعدها أنشأنا حلقة تكرارية، بحيث تمسح جميع المعلومات المتحصل عليها من الثابت response بعد التحقق من أنه يحوي المعلومات المطلوبة وهي مصفوفة كائنات. مع كل دورة للحلقة التكرارية، يُستخرَج البريد الإلكتروني للعميل الذي ترك سلته دون شراء وإضافته إلى الثابت getEmails ثم أنشأنا بعدها ثابتًا جديدًا تحت اسم mailData والذي سيحوي المعلومات المطلوبة في الدالة sendMail من أجل إرسال رسائل البريد اﻹلكتروني، بعدها أسندت قيمة الثابت mailData إلى الدالة sendMail من أجل إرسال رسالة إلى جميع أصحاب سلات الشراء المتروكة على عناوين بريدهم الإلكتروني المسجل. علينا اﻵن أن نضيف هذا الخاصية إلى ملف index.js، مثل أي نقطة نهاية أضفناها سابقا. نقطة الوصول اﻷولى، خاصة بعرض الصفحة التي أنشأناها للتو: app.get("/loyalty", async (req, res) => { res.render("loyalty"); }); تعرض نقطة الوصول هذه القالب الموجود داخل المجلد views المسمى باسم loyalty.pug. نقطة الوصول الثانية، وهي التي ستحوي على الدالة التي أضفناها قبل قليل بالشكل التالي: app.post("/loyalty", async (req, res) => { const response = await Loyalty(); res.send(response); }); يمكنك اﻵن التوجه إلى الرابط وجرب التطبيق: http://localhost:3000/loyalty اﻵن يمكنك إدخال قسيمة التخفيض في المكان المخصص وإرسالها إلى جميع أصحاب سلات الشراء المتروكة. عند اﻹنتهاء من جميع الخطوات التي ذُكرت في هذا المقال، ستكون الشيفرة البرمجية في الملف index.js كالتالي: import express from "express"; import path from "path"; import AbandonedCarts from "./zid.js"; import AddCoupon from "./addCoupon.js"; import sendMail from "./mail.js"; import Loyalty from "./loyality.js"; const __dirname = path.resolve(); var app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: false })); app.set("views", path.join(__dirname, "views")); app.set("view engine", "pug"); app.use(express.static(path.join(__dirname, "public"))); app.get("/carts", async (req, res) => { const response = await AbandonedCarts(); const renderedData = response["abandoned-carts"]; res.render("abandoned", { renderedData }); }); app.get("/", async (req, res) => { res.render("index"); }); app.get("/loyalty", async (req, res) => { res.render("loyalty"); }); app.get("/coupon", async (req, res) => { res.render("coupon"); }); app.get("/error", (req, res) => { res.render("error"); }); app.post("/loyalty", async (req, res) => { const response = await Loyalty(); res.send(response); }); app.post("/add-coupon", async (req, res) => { const data = req.body; const dataToSend = Object.assign({}, data); const response = await AddCoupon(dataToSend); if (response) { res.redirect("/"); } else { res.redirect("/error"); } }); app.post("/mail", async (req, res) => { const data = req.body; const dataToSend = Object.assign({}, data); const send = await sendMail(dataToSend); if (send) { res.send("mail has been sent"); } else { res.send("there was an error"); } }); const port = process.env.PORT || 3000; app.listen(port, () => { console.log(`Server started on ${port}`); }); أخيرًا، تجد شيفرة التطبيق كاملةً على GitHub بالمستودع zid-retention-app. خاتمة لقد استغللنا في البداية الواجهة البرمجية لمنصة زد وما تقدمه من نقاط وصول وبناء فكرة تطبيق منها يمكن أن يستفيد منه أصحاب المتاجر الذين يعتمدون على منصة زد، إذ يمكنك توفير التطبيق لهم بمقابل لكي يستفيدوا هم أيضًا منه وبذلك يستفيد الجميع. لا يقتصر الأمر على فكرة السلات المتروكة وزيادة الولاء وإنما يمكن بناء عشرات التطبيقات المفيدة لأصحاب المتاجر التي توسع من عمل متاجرهم وكان هذا مجرد مثال، وهو في الحقيقة ما يمكنك عمله مع معظم منصات التجارة اﻹلكترونية مثل منصة سلة وشوبيفاي Shopify، يكفي فقط أن تقرأ التوثيق الخاص بالواجهات البرمجية لتلك المنصات وبناء أفكار مفيدة منها. لكي يكون التطبيق تجاريًا، عليك إضافة نظام لتسجيل الاعضاء ونظام اشتراكات وأيضا نظام تسجيل الدخول والخروج مع إمكانية إضافة المعلومات الشخصية لصاحب المتجر الراغب في التسجيل، وهنا سنستخدم الصفحة الرئيسية التي أضفناها إلى التطبيق index.pug، بحيث سيكون بإمكان العميل المسجل إضافة مفتاح المتجر الخاص به سواءً على منصة زد، أو إضافة المعلومات المطلوبة للربط مع التطبيق في حالة استخدامه لمنصة أخرى مثل Shopify. يمكنك أيضًا إضافة خصائص جديدة لتطبيق كما أشرنا مثل إرسال رسالة نصية للعملاء أصحاب سلات الشراء المتروكة بالتزامن مع إرسال بريد إلكتروني. يمكنك استخدام منصات إرسال الرسائل النصية المتوفرة في بلدك إن وجدت أو استخدام حلول مثل Twilio أو MessageBird. وطبعًا يمكنك توسيع الخدمات التي تقدمها إلى خدمات أخرى يطلبها أصحاب المتاجر كما أشرنا وهنا نترك الأمر لك ولإبداعك. تهانينا، لقد أتممت بناء تطبيق مفيد بإمكانك استعماله بطريقة تجارية إن أحببت وﻹطلاق شركتك الناشئة العاملة في هذا المجال، ولم ﻻ توسعها لتشمل منصات أكثر غير منصة زد فقط! نرجو لك كل التوفيق في رحلتك القادمة. اقرأ أيضًا مدخل إلى الواجهات البرمجية API أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API التعرف على لوحة تحكم متجر زد الإلكتروني وضبط عمليات المتجر كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد

لا يكاد يخلو أي موقع ويب من وجود خرائط Google فمن خلال وضع خريطة على الموقع الخاص بك فإنك تعطي تأثيرًا غنيًا ومستوى أعلى للتفاعل بين المستخدمين. سأقوم في هذا المقال بشرح كيفيّة استخدام خرائط غوغل وإضافتها إلى صفحة الويب بالإضافة إلى كيفيّة تحديد أكثر من موقع بنفس الوقت على نفس الخريطة، وشرح بعض المزايا الـتي يمكنك إضافتها إلى خريطتك. يمكنك تحميل الملف المصدري للمثال الموضح في هذا الدرس. إستخدام مكتبة Google APIمكتبة Google Maps API هي عبارة عن مكتبة جافاسكربت ولنتمكن من إستخدام مكتبة Google API قم بإضافة الـسكربت الـخاص بذلك. <script src ="http://maps.google.com/maps/api/js?sensor=false" type="text/javascript"></script> إنشاء الخريطةقم الآن بإنشاء div بالأبعاد الـتي تريد أن تظهر بها الـخريطة وقم بإعطاءه "id="map. <div id="map" style="width: 600px; height: 400px;" ></div>الآن لنقم بإنشاء السكربت لإظهار الخريطة، يجب عليك عند وضع أي خريطة أن تقوم بتحديد الإحداثيات: خط الطول longitude وخط العرض latitude ضمن الخاصية center. يمكنك معرفة الإحداثيات لمنطقة ما بالدخول لموقع LatLong وكتابة اسم المدينة أو المنطقة. في هذا المثال ستعرض الخريطة موقع تركيا Turkey. لنقم الآن ضمن الدالة {} ()function initialize، بتحديد خصائص الـخريطة ضمن الـمتغير mapProp، مثل: الموقع الذي سيظهر عند تحميلها، نوعها، وحجم الـتكبير الذي نريده zoom. كما هو موضح في الـكود الـتالـي: <script type="text/javascript"> function initialize() { var mapProp = { center: new google.maps.LatLng(38.963745, 35.243322), zoom: 5, mapTypeId: google.maps.MapTypeId.ROADMAP }; } </script> نستخدم الخاصية zoom لتحديد البعد الذي نريده للمكان (قريب – بعيد).الخاصية mapTypeId تحدد نوع الخريطة الذي سيظهر:ROADMAP ( الخريطة العادية 2D map)SATELLITE (خريطة مصورة)HYBRID (خريطة مصورة بالإضافة الى أسماء الطرق والمدن)TERRAIN (خريطة تتضمن الجبال والأنهار…الـخ)لنقم الآن بتعريف متغير map وإعطاءه id الخاصة بالـ div: var map = new google.maps.Map(document.getElementById("map"), mapProp);ثم إضافة الحدث DOM listener الذي يقوم بتنفيذ الدالة ()initialize عند تحميل صفحة الويب: google.maps.event.addDomListener(window, 'load', initialize);ليصبح الكود على هذا الشكل: <script type="text/javascript"> function initialize() { var mapProp = { center: new google.maps.LatLng(38.963745, 35.243322), zoom: 5, mapTypeId: google.maps.MapTypeId.ROADMAP }; var map = new google.maps.Map(document.getElementById("map"), mapProp); } google.maps.event.addDomListener(window, 'load', initialize); </script>ستظهر لك الخريطة بهذا الشكل: وضع محددات Markersإضافة محدد واحدلنقم الآن بتحديد موقع معين ووضع محدد (marker). أولًا قم بتعريف مصفوفة تحتوي على الإحداثيات (خط الـطول وخط الـعرض) للمدينة أو البلد أو الموقع المعين الذي تريد تحديده. مثلًا مدينة اسطنبول Istanbul: var myLatLng = {lat: 41.008238, lng: 28.978359 };هنا سأقوم بإضافة محدد واحد ثم سأشرح كيف يمكننا إضافة أكثر من محدد. الآن نعطي للخاصية center الـمتغير myLatLng: var map = new google.maps.Map(document.getElementById('map'), { zoom: 8, center: myLatLng });ثم نقوم بتعريف الـمحدد وإعطاء للخاصية position الـمتغير myLatLng: var marker = new google.maps.Marker({ position: myLatLng, map: map, title: 'Hello World!' });سيظهر بهذا الشكل: إضافة أكثر من محدد على نفس الـخريطةقم بتعريف مصفوفة تحتوي على إحداثيات المواقع الـتي تود تحديدها، سأقوم بتحديد 6 مدن: Istanbul, Antalya, Ankara, Trabzon, Bursa, Adana كما هو موضح أدناه: var myLocations = [ ['Istanbul', 41.008238, 28.978359, 1], ['Antalya', 36.896891, 30.713323, 2], ['Ankara', 39.933363, 32.859742, 3], ['Trabzon', 41.002697, 39.716763, 4], ['Bursa', 40.188528, 29.060964, 5], ['Adana', 36.991419, 35.330829, 6] ];الآن عند تعريف المحدد قم بعمل for loop حلقة تكرار وتعريف متغير i ومن ثم إعطاء الـمصفوفة myLocations للخاصية position: var marker, i; for (i = 0; i < myLocations.length; i++) { marker = new google.maps.Marker({ position: new google.maps.LatLng(myLocations[i][1], myLocations[i][2]), map: map }); }وهذه هي المواقع التي قمنا بتحديدها: وضع محدد مع لصيقة (label) عند الـنقر على مكان معينسأقوم هنا بشرح فكرة عن الـevents في Google map ثم سأتطرق فيما بعد لشرح الـevents بالتفصيل في مقال مقبل إن شاء الله. الآن لنرى كيف يمكننا عند الضغط على مكان معين على الخريطة إظهار محدد مع لصيقة. مثال: marker A, marker B. أولاً يجب تعريف متغير Labels نضع فيه القيم الـتي نريد إظهارها في اللصيقة. مثال: الأحرف من A-Z. ونحتاج أيضًا إلى تعريف متغير labelIndex لتحديد الـقيمة الـتي نريد إظهارها. var labels = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'; var labelIndex = 0;الآن قم بتحديد المكان الـذي ستفتح عنده الخريطة. مثال: تركيا. var Turkey = { lat: 38.963745 , lng: 35.243322 }; var map = new google.maps.Map(document.getElementById('map'), { zoom: 12, center: Turkey });الدالة ()addMarkerيقوم الحدث event.addListener باستدعاء التابع ()addMarker عند الضغط على الخريطة. كما في المثال التالي: google.maps.event.addListener(map, ‘click’, function(event) { addMarker(event.latLng, map); });وليكون هناك marker محدد عند فتح الخريطة قم بإضافة محدد إلى Turkey: addMarker(Turkey, map);لنكتب الآن الدالة ()addMarker: نحتاج لتعريف 2 parameters (معاملين) هما الـخريطة والـموقع map & location ثم نقوم بتعريف marker وإعطاء المعامل location للخاصية position. ولإظهار label نقوم بإعطاء الـمتغير labels الـذي يحتوي على الأحرف من A-Z للخاصية label مع تحديد ++index لكي ينتقل عند كل نقرة جديدة لحرف جديد وإظهاره على الـ marker كما هو موضح في الكود الـتالي: function addMarker(location, map) { var marker = new google.maps.Marker({ position: location, label: labels[labelIndex++ % labels.length], map: map }); }ستظهر لك الخريطة بهذا الشكل: وعند النقر على الخريطة: إضافة تأثير Marker Animationيمكنك إضافة تأثير حركي على المحدد ليبدو وكأنه يقفز ، فقط باستخدام خاصية animation:google.maps.Animation.BOUNCE كما هو موضح في الكود الـتالـي: var marker = new google.maps.Marker({ position: myCenter, animation: google.maps.Animation.BOUNCE });إضافة أيقونة للمحدد يمكنك تغيير الأيقونة الخاصة بالمحدد ووضع أيقونة من اختيارك عن طريق الخاصية icon، حيث تقوم بإعطاء مسار الصورة للخاصية icon. كما هو موضح في الكود التالي: var marker = new google.maps.Marker({ position: myCenter, icon:'pin.png' });ستظهر لك الخريطة بهذا الشكل: إضافة شكل متعدد الخطوط Polyline تتيح لك ميزة polyline رسم خط يصل بين سلسلة إحداثيات على الخريطة بشكل متسلسل، على سبيل المثال يمكنك رسم مسار رحلة عبر مجموعة من المدن ويمكنك التحكم بخصائص عديدة للخط مثل اللون والشفافية والحجم. خصائص الميزة Polyline: path - تحدد مجموعة الإحداثيات التي سيمر بها الخط.strokeColor - يحدد لون الخط بالـHex كود.strokeOpacity - يحدد شفافية الخط بين 0.0 و 1.0.strokeWeight - يحدد عرض الخط بالبكسل.Editable - تحدد ما إذا كان الخط قابل للتعديل من قبل المستخدم أم لا. لنقم الآن بتحديد مجموعة إحداثيات لمدن ونصل فيما بينها عن طريق polyline، سأستخدم نفس الإحداثيات التي استخدمتها في تحديد المدن عندما وضعت أكثر من محدد، سأقوم برسم خط بين ثلاث مدن: اسطنبول، انطالـيا، طرابزون. أولاً: تحديد إحداثيات الـمدن: var istanbul = new google.maps.LatLng(41.008238, 28.978359); var antalya = new google.maps.LatLng(36.896891, 30.713323); var trabzon = new google.maps.LatLng(41.002697, 39.716763);ثانيًا: نقوم بتعريف مصفوفة myTrip وتعبئتها بأسماء المتغيرات (المدن الـتي نريد تحديد المسار عليها ): var myTrip = [ istanbul, antalya, trabzon];وثم نعطي المصفوفة للخاصية path: path: myTrip,ثالثًا: نقوم بتعريف متغير flightPath لاختيار الـخاصية polyline: كما هو موضح في الكود الـتالي: var map = new google.maps.Map(document.getElementById(“map”),mapProp); var myTrip = [ istanbul, antalya, trabzon]; var flightPath = new google.maps.Polyline({ path:myTrip, strokeColor: "#0000FF", strokeOpacity: 0.8, strokeWeight: 2 }); flightPath.setMap(map); }ستظهر لك الخريطة بهذا الشكل: إضافة مضلع Polygonتتيح لك هذه الـميزة إنشاء مضلع تكون زواياه عبارة عن سلسلة الإحداثيات التي تريد الوصل بينها. لا تختلف ميزة polygon كثيراً عن polyline من حيث كتابة الـتعليمات فقط نقم باستبدالـ polyline بـpolygon. خصائص الـميزة polygon: path - تحدد مجموعة الإحداثيات التي سيمر بها الخط.strokeColor - يحدد لون الخط بالـHex كود.strokeOpacity - يحدد شفافية الخط بين 0.0 و 1.0.strokeWeight - يحدد عرض الخط بالبكسل.fillColor - يحدد لون المضلع بالـHex كود.fillOpacity - يحدد نسبة الشفافية للمضلع بين 0.0 و 1.0.Editable - تحدد ما إذا كان الخط قابل للتعديل من قبل المستخدم أم لا. كما هو موضح في الكود التالي: var map = new google.maps.Map(document.getElementById(“map”),mapProp); var myTrip = [istanbul, antalya, trabzon]; var flightPath = new google.maps.Polygon({ path: myTrip, strokeColor: "#0000FF", strokeOpacity: 0.8, strokeWeight: 2 }); flightPath.setMap(map); }ستظهر لك الـخريطة بهذا الـشكل: إضافة دائرة Circleتتيح لك هذه الميزة إحاطة منطقة معينة على الخريطة بدائرة، يمكنك التحكم بقطر الدائرة ولونها وشفافيتها. خصائص الميزة Circle: center - تحديد إحداثيات مركز الدائرة. radius - تحديد قطر الدائرة بالمتر المربع. strokeColor - يحدد لون الخط بالـHex كود.strokeOpacity - يحدد شفافية الخط بين 0.0 و 1.0.strokeWeight - يحدد عرض الخط بالبكسل.fillColor - يحدد لون المضلع بالـHex كود.fillOpacity - يحدد نسبة الشفافية للمضلع بين 0.0 و 1.0.Editable - تحدد ما إذا كان الخط قابل للتعديل من قبل المستخدم أم لا.كما هو موضح في الكود التالي: var map = new google.maps.Map(document.getElementById(“map”), mapProp); var flightPath = new google.maps.Circle({ center: istanbul, radius: 20000, strokeColor: "#0000FF", strokeOpacity: 0.8, strokeWeight: 2, fillColor: "#0000FF", fillOpacity: 0.4 }); flightPath.setMap(map); ستظهر لك الخريطة بهذا الشكل: إضافة نافذة نصية InfoWindowتتيح لك ميزة infoWindow إظهار نافذة على موقع معين محدد باسم بحيث يمكنك كتابة اسم الموقع المحدد بداخلها. كما هو موضح في الكود التالي: var map = new google.maps.Map(document.getElementById(“map”), mapProp); var marker = new google.maps.Marker({ position: new google.maps.LatLng(38.963745, 35.243322), }); marker.setMap(map); var infowindow = new google.maps.InfoWindow({ content:”Hello World!” }); infowindow.open(map, marker); }ستظهر لك الخريطة بهذا الشكل: هكذا نكون قد استعرضنا أهم النقاط والميزات التي تتيح لك استخدام خرائط Google Maps بسهولة في موقعك الخاص. هل أنت جاهز الآن لإضافة Google Maps إلى موقعك والإستفادة من مزاياها؟ الـمصدر: Google Developers.حقوق الصورة البارزة: Designed by Freepik.

الواجهة البرمجية Promise رائعة ويمكنك جعلها مذهلة باستخدام async و await. إنّ الشيفرة المتزامنة سهلة التتبع والتنقيح إلا أنّ الشيفرة غير المتزامنة أفضل بشكل عام من حيث الأداء والمرونة، فلماذا "توقف العرض" بينما بإمكانك استقبال الكثير من الطلبات في وقت واحد ثمّ معالجة كلٍّ منها عندما يصبح جاهزًا؟ مع العديد من الواجهات البرمجية API الجديدة التي تم تحقيقها مع مبدأ الوعد، إذ أصبحت الوعود جزءًا كبيرًا في عالم الجافاسكربت. لنلقِ نظرة على كيفية استخدام الواجهة البرمجية للوعود. الوعود قيد التطبيق الواجهة البرمجية XMLHttpRequest غير متزامنة ولكنها لا تستخدم الواجهة البرمجية Promises. هناك عدة واجهات برمجية أصلية تستخدم الوعود الآن، مثل: Battery API. fetch API (بديل XHR) الواجهة البرمجية ServiceWorker ستصبح الوعود أكثر شيوعًا، لذا من المهم أن يعتاد عليها جميع مطوري الواجهات الأمامية، وتجدر الإشارة إلى أنّ Node.js هي منصة أخرى للوعود. (يبدو هذا واضحًا، كما الواجهة البرمجية Promise ميزة أساسية في اللغة). من المحتمل أن يكون اختبار الوعود أسهل مما تعتقد لأنه يمكنك استخدام setTimeout كـ "مهمة" لك غير متزامنة. استخدام Promise الأساسي يجب أن يستخدم الباني new Promise()‎ فقط للمهام الغير متزامنة الموروثة، مثل استخدام setTimeout أو XMLHttpRequest. يتم إنشاء وعدًا جديدًا باستخدام الكلمة المفتاحية new ويتم تمرير توابع resolve و reject لردّ النداء المزوَّد: var p = new Promise(function(resolve, reject) { // ...القيام بمهمة غير متزامنة وثم if(/* شرط جيد */) { resolve('Success!'); } else { reject('Failure!'); } }); p.then(function(result) { /* القيام بفعل ما مع النتيجة */ }).catch(function() { /* خطأ :( */ }).finally(function() { /* تنفّذ بغض النظر عن النجاح أو الفشل */ }); يعود الأمر للمطور فيما إذا كان يريد استدعاء resolve أو reject يدويًا ضمن جسم رد النداء اعتمادًا على نتيجة المهمة المعطاة. مثال واقعي لتحويل XMLHttpRequest إلى مهمة تعتمد على الوعد: // من وعود جاك أرشيبالد والعودة // http://www.html5rocks.com/en/tutorials/es6/promises/#toc-promisifying-xmlhttprequest function get(url) { //إعادة وعد جديد. return new Promise(function(resolve, reject) { // XHR القيام بالعمل الاعتيادي لـ var req = new XMLHttpRequest(); req.open('GET', url); req.onload = function() { // هذا يتم استدعاؤه حتى في حالة 404 // لذا اختبر الحالة if (req.status == 200) { // قم بإنهاء الوعد مع نص الرد resolve(req.response); } else { // وإلا ارفض مع نص الحالة // والذي نأمل أن يكون خطأ ذو معنى reject(Error(req.statusText)); } }; // معالجة أخطاء الشبكة req.onerror = function() { reject(Error("Network Error")); }; // القيام بالطلب req.send(); }); } // استخدمه! get('story.json').then(function(response) { console.log("Success!", response); }, function(error) { console.error("Failed!", error); }); إذا كان من الممكن اتخاذ إجراء غير متزامن قد لا تحتاج إلى إكمال المهام غير المتزامنة ضمن الوعد، لكن سيكون الأفضل هو أن تكون القيمة المعادة وعدًا لذا يمكنك أن تعدّ كم عدد الوعود التي حصلت عليها من تابع معطى. في تلك الحالة يمكنك ببساطة استدعاء Promise.resolve()‎ أو Promise.reject()‎ بدون استخدام الكلمة المفتاحية new. مثلًا: var userCache = {}; function getUserDetail(username) { // في كلتا الحالتين، تم إضافته إلى الذاكرة أو لا، سيتم إعادة وعد if (userCache[username]) { // new إعادة وعد بدون الكلمة المفتاحية return Promise.resolve(userCache[username]); } // لتحصل على المعلومات fetch استخدم الواجهة البرمجية // وعدًا fetch تعيد return fetch('users/' + username + '.json') .then(function(result) { userCache[username] = result; return result; }) .catch(function() { throw new Error('Could not find user: ' + username); }); } بما أن القيمة المعادة هي وعد لذا يمكنك استخدام التوابع then و catch عليها. then كل كائنات الوعد تملك التابع then الذي يسمح لك بالتفاعل مع الوعد. رد النداء الأول لتابع then يستدعي النتيجة المعطاة له عن طريق استدعاء ()resolve: new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { resolve(10); }, 3000); }) .then(function(result) { console.log(result); }); // console من الطرفية // 10 رد النداء لـ then يتم تشغيله عندما ينتهي الوعد. يمكنك أيضًا أن تسلسل ردود النداء للتابع then: new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { resolve(10); }, 3000); }) .then(function(num) { console.log('first then: ', num); return num * 2; }) .then(function(num) { console.log('second then: ', num); return num * 2; }) .then(function(num) { console.log('last then: ', num);}); // من الـ console // first then: 10 // second then: 20 // last then: 40 كل then تستقبل القيمة المعادة من استدعاء then السابق. إذا أُنهي الوعد قبل أن يتم استدعاء التابع then مجددًا، يتم إيقاف رد النداء مباشرةً. إذا تم رفض الوعد ثم استدعاء التابع then بعد الرفض، لا يتم استدعاء رد النداء أبدًا. catch يتم استدعاء رد النداء catch عندما يُرفض الوعد: new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { reject('Done!'); }, 3000); }) .then(function(e) { console.log('done', e); }) .catch(function(e) { console.log('catch: ', e); }); // console من الطرفية // 'catch: Done!' ما تمرره لتابع reject يعود لك ولكن النمط المعتاد هو إرسال Error لـ catch: reject(Error('Data could not be found')); finally رد النداء المعرّف حديثًا finally يتم استدعاؤه بغض النظر عن النجاح أو الفشل: (new Promise((resolve, reject) => { reject("Nope"); })) .then(() => { console.log("success") }) .catch(() => { console.log("fail") }) .finally(res => { console.log("finally") }); // >> fail // >> finally Promise.all فكر بمحمّلات الجافاسكربت: يوجد أوقات يتم فيها تشغيل عدة تفاعلات غير متزامنة وتريد الاستجابة عندما تكتمل جميعها، هنا يأتي دور التابع Promise.all، هذا التابع يأخذ مصفوفة من الوعود ويعطيك رد نداء واحد فقط عند إنهاء جميع الوعود. Promise.all([promise1, promise2]).then(function(results) { // كلا الوعدين تم إنهاؤهما }) .catch(function(error) { // تم رفض وعد واحد أو أكثر }); الطريقة المثالية للتفكير بـ Promise.all هي إطلاق عدة طلبات AJAX (باستخدام fetch) في نفس الوقت. var request1 = fetch('/users.json'); var request2 = fetch('/articles.json'); Promise.all([request1, request2]).then(function(results) { // كلا الوعدين تم تنفيذهما }); يمكنك أن تدمج عدة واجهات برمجية مثل fetch والواجهة البرمجية Battery بما أنّها تعيد وعودًا. Promise.all([fetch('/users.json'), navigator.getBattery()]).then(function(results) { // كلا الوعدين تم تنفيذهما }); التعامل مع الرفض صعب بالطبع. إذا تم رفض أيّ وعد سيتم إطلاق catch للرفض الأول: var req1 = new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { resolve('First!'); }, 4000); }); var req2 = new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { reject('Second!'); }, 3000); }); Promise.all([req1, req2]).then(function(results) { console.log('Then: ', results); }).catch(function(err) { console.log('Catch: ', err); }); // console من الـ // Catch: Second! ستكون Promise.all مفيدة أكثر للواجهات البرمجية التي تتجه لاستخدام الوعود. Promise.race تعدّ الدالة Promise.race مفيدة فبدلًا من أن يتم الانتظار حتى إنهاء جميع الوعود أو رفضها تقوم بتشغيل أيّ وعد في المصفوفة تم إنهاؤه أو رفضه. var req1 = new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { resolve('First!'); }, 8000); }); var req2 = new Promise(function(resolve, reject) { // setTimeout حدث زائف غير متزامن باستخدام setTimeout(function() { resolve('Second!'); }, 3000); }); Promise.race([req1, req2]).then(function(one) { console.log('Then: ', one); }).catch(function(one, two) { console.log('Catch: ', one); }); // console من الـ // Then: Second! يمكن أن تشغّل حالة الاستخدام طلبًا إلى مصدر أوليّ ومصدر ثانوي (في حال عدم توفر الأوليّ والثانوي). اعتد على الوعود كانت الوعود موضوعًا مثيرًا للاهتمام خلال السنوات القليلة الماضية (أو خلال السنوات العشرة الأخيرة إذا كنت مستخدم مجموعة أدوات Dojo) وانتقلت من كونها نمط في إطار عمل جافاسكربت إلى كونها من أساس اللغة. وربما من الأفضل افتراض أنك ستشاهد معظم الواجهات البرمجية الجديدة في جافاسكربت يتم تنفيذها بنمط يعتمد على الوعد، وهذا أمر ممتاز. إنّ المطورين قادرون على تجنب جحيم رد النداء وتمرير التفاعلات غير المتزامنة مثل أيّ متغير آخر. تستغرق الوعود بعض الوقت لتكون الأدوات الأصلية وقد حان الوقت لتعلّمها. يمكنك في أي وقت الرجوع إلى توثيق الكائن Promise في موسوعة حسوب كما ننصحك أيضًا بقراءة صفحة «استخدام الوعود» بعد هذه المقالة مباشرةً لوضع ما تعلمته موضع التطبيق. ترجمة -وبتصرف- للمقال JavaScript Promise API لصاحبه David Walsh

أتاح لي العمل في موزيلا وقتًا كافيًا للنظر في الواجهات البرمجية API الجديدة، وإحداها هي الواجهة البرمجية Battery. لقد كتبت سابقًا عن الواجهة البرمجية Battery عندما كانت واجهة برمجية جديدة في المتصفحات ولكنها تغيرت لاحقًا وأصبحت واجهة برمجية يعتمد تنفيذها على الوعود ومتوفرة فقط في متصفح غوغل كروم. لنأخذ نظرة عن كيفية استخدام الواجهة البرمجية الجديدة. بإمكانك الاطلاع على النسخة التجريبية. الوظيفة التي نحتاجها ما تزال موجودة لدى الكائن navigator ولكنها الآن على شكل تابع يدعى getBattery: navigator.getBattery().then(function(result) {}); يعيد استدعاء التابع getBattery وعدًا ورد النداء الممرّر لـ then يُعطى كائن BatteryManager يوفر المعلومات التالية كمثال: // النتيجة BatteryManagery { charging: false, chargingTime: Infinity, dischargingTime: 8940, level: 0.59, onchargingchange: null, onchargingtimechange: null, ondischargingtimechange: null, onlevelchange: null } بإمكانك الاطلاع على النسخة التجريبية. إنّ الواجهة البرمجية الجديدة مختلفة في طريقة التنفيذ ولكنها مشابهة في النتيجة. تذكّر أنّ الواجهة البرمجية القديمة لديها مشاكل مع بطاريات أجهزة ماك ولا يبدو أنّ هذا قد تغيّر. من الصعب مراعاة بادئات المتصفحات المختلفة ولكن حصلنا على نتيجة مقبولة تقريبًا ولكنها تصبح فاشلة تمامًا عندما تتغير المنهجية بالكامل. نأمل أن يكون مالكي المتصفحات الأخرى سريعي التحديث لنحصل مجددًا على واجهة تطبيق موحدة البادئات للمتصفح. ترجمة -وبتصرف- للمقال JavaScript Battery API: Promises‎ لصاحبه David Walsh

توفر الكثير من المواقع واجهات برمجية Application Programming Interface ،API بهدف إتاحة موارد الموقع لتطبيقات خارجية؛ قد تكون تطبيقات ٍللجوال، أجهزةً لوحية، أو أجهزةً مكتبية. قد نود مثلا إنشاء تطبيق للجوال نعرض فيه منتجات الموقع. نستخدم لغة البرمجة المناسبة للتطبيق (جافا مثلا لتطبيقات أندرويد) الذي يرسل طلبات لواجهتنا البرمجية يحصُل بموجبها على بيانات يتولى هو طريقة عرضها. نقول إن تطبيق الجوال في هذه الحالة يستهلك Consume الواجهة البرمجية. هذا الدرس جزء من سلسلة تعلم Laravel والتي تنتهج مبدأ "أفضل وسيلة للتعلم هي الممارسة"، حيث ستكون ممارستنا عبارة عن إنشاء تطبيق ويب للتسوق مع ميزة سلة المشتريات. يتكون فهرس السلسلة من التالي: مدخل إلى Laravel 5.تثبيت Laravel وإعداده على كلّ من Windows وUbuntu.أساسيات بناء تطبيق باستخدام Laravel.إنشاء روابط محسنة لمحركات البحث (SEO) في إطار عمل Laravel.نظام Blade للقوالب.تهجير قواعد البيانات في Laravel. استخدام Eloquent ORM لإدخال البيانات في قاعدة البيانات، تحديثها أو حذفها. إنشاء سلة مشتريات في Laravel.الاستيثاق في Laravel. إنشاء واجهة لبرمجة التطبيقات API في Laravel. (هذا الدرس)إنشاء مدوّنة باستخدام Laravel.استخدام AngularJS واجهةً أمامية Front end لتطبيق Laravel.الدوّال المساعدة المخصّصة في Laravel.استخدام مكتبة Faker في تطبيق Laravel لتوليد بيانات وهمية قصدَ الاختبار. نغطي في هذا الدرس المواضيع التالية: ماهي واجهات REST البرمجية؟الممارسات المنصوح بها في واجهات REST البرمجية.إنشاء واجهة برمجية لمشروع Larashop.ماهي واجهات REST البرمجية؟توصف الكثير من الواجهات البرمجية بأنها RESTful، فما المقصود بهذا الوصف؟ تختصر REST العبارة Representational State Transition (النقل التمثيلي للحالة) وهي طريقة لتصميم البرمجيات تعرِّف معاييرَ يجب على خدمات الويب اتباعها من أجل أداء أعلى وصيانة أسهل. تعتمد بنية التطبيقات REST على بروتوكول HTTP لإرسال الطلبات والحصول على إجابات؛ ومن أهم القيود التي يجب الالتزام بها في تطبيقات REST: العمل حسب مبدأ خادوم-عميل Server-Client، انعدام الحالة Stateless وتوحيد الواجهات (إضافة لقيود أخرى). مبدأ خادوم-عميل: يجب التفريق بين واجهة المستخدم والخادوم الذي يخزن البيانات ويطبق العمليات عليها.انعدام الحالة: يجب أن يحوي الطلب الموجّه من العميل إلى الخادوم كل المعلومات الضرورية ليستطيع الخادوم فهمه والإجابة عليه؛ دون الحاجة لسياق محفوظ على الخادوم (لفهم الطلب).توحيد الواجهات بمعنى أن كل مورد على الخادوم يمكن تعريفه فرديا واستغلاله عبر بيانات تمثله يحتفظ بها العميل. يجب أن تكون الطلبات واضحة يمكن فهمها والإجابة عنها دون الحاجة لمعلومات خارجة عنها. يدخل ضمن توحيد الواجهات أيضا افتراضُ العميل أن أي إجراء Action غيرُ متوفر على الخادوم، ما لم يصّرح هذا الأخير بتوفره.تساهم هذه القيود (والقيود الأخرى التي تعرفها بنية REST) في تسهيل عمل الواجهات، الرفع من أدائها، تيسير الصيانة وقابلية التمدد Scalability. سنرى في الفقرة التالية توصيات لبناء واجهات برمجية تساعد في احترام مبادئ REST. ملحوظة: يكثُر وصف الواجهات البرمجية بأنها RESTful (تلتزم بقيود REST) دون أن تلتزم بكامل القيود التي تعرِّفها بنية REST، وهو ما يجعلها أقرب لواجهات شبيهة لـREST منها لواجهات RESTful. الممارسات المنصوح بها في واجهات REST البرمجيةيُساعد الالتزام بالممارسات التالية في بناء واجهة تطبيقات برمجية ذات أداء عال وقابلية كبيرة للتمدد والصيانة. استخدام إجراءات HTTP لتحديد العمل الذي سيؤديه الخادوم: GET للحصول على مورد، POST لإنشاء مورد جديد، PUT لتحديث مورد وDELETE لحذفه.أَصْدَرَة Versioning الواجهة: يساعد استخدام إصدارات في عدم كسر التطبيقات التي تستهلك الواجهة البرمجية. يحدّد العميل إصدار واجهة التطبيق الذي يود العمل عليه مما يسمح بإحداث تغييرات على الخادوم تضمَّن في إصدار جديد دون أن يتوقف عملاء الواجهة البرمجية.من المتعارف عليه استخدام أسماء جموع لوصف الموارد، api.mysite/v1/products مثلا للمنتجات. ليس واجبا اتباع هذا العرف لكن الأهم هو تناسق تسمية الموارد: لا تخلط بين أسماء مفردة للموارد وجموع.استخدام الإجابات الجزئية: طلب العميل اسم المنتج؟ أرسل اسم المنتج فقط، وليس كامل بيانات المنتج، في الإجابة.استخدام رموز الحالة: تسهّل رموز الحالة في HTTP التخاطب مع العميل. عولج الطلب على النحو الأمثل؟ أرسِل الرمز 200 في الإجابة. طلب العميل إنشاء مورد وتم الأمر؟ أرسل الرمز 201 في الإجابة؛ وهكذا. راجع هذا الرابط للمزيد من رموز الحالة في HTTP.ضع حدًّا أقصى لعدد الطلبات القادمة من نفس عنوان IP في الواجهات المفتوحة للجميع. يساعد هذا الأمر في التصدي للعملاء الذي يفرطون في استخدام واجهة تطبيقاتك البرمجية. ينصح أيضا بحظر عناوين IP ذات السلوك المشبوه حتى لا يؤثر على بقية المستخدمين.قد يُختلف حول هذه التوصية، إلا أنه يُنصح باستخدام صيغة JSON لإرسال البيانات في الإجابة عن الطلب، ما لم يحدّد العميل عكس ذلك.خبِّئ Cache نتائج طلبات GET التي لا تتغير كثيرا. ربما تكون قائمة العلامات التجارية في مواقع التسوق مثالا جيدا للبيانات التي يجب تخبئتها (قد تمضي أشهر دون الحاجة لإضافة علامة تجارية جديدة).واجهة Larashop البرمجيةسننشئ في هذه الفقرة واجهة تطبيقات برمجية لمشروع Larashop. تشتمل الواجهة على المسارات أدناه. تستخدم جميع المسارات إجراء GET للحصول على المورد. التسلسل المورد الرابط الوصف رمز الحالة1Product/api/v1/productsسرد لائحة بالمنتجات وخاصياتها2002Product/api/v1/products/1سرد خاصيات المنتج رقم 12003Category/api/v1/categoriesسرد لائحة بتصنيفات المنتجات2004Category/api/v1/categories/1التصنيف ذو المعرّف 1200لاحظ أننا لم نتح إمكانية التعديل على الموارد عبر الواجهة. تشير v1 في المسارات إلى رقم الإصدار 1. نفتح ملف المسارات routes.php ونعدّله بإضافة المسارات التالية: // API routes... Route::get('/api/v1/products/{id?}', ['middleware' => 'auth.basic', function($id = null) { if ($id == null) { $products = App\Product::all(array('id', 'name', 'price')); } else { $products = App\Product::find($id, array('id', 'name', 'price')); } return Response::json(array( 'error' => false, 'products' => $products, 'status_code' => 200 )); }]); Route::get('/api/v1/categories/{id?}', ['middleware' => 'auth.basic', function($id = null) { if ($id == null) { $categories = App\Category::all(array('id', 'name')); } else { $categories = App\Category::find($id, array('id', 'name')); } return Response::json(array( 'error' => false, 'user' => $categories, 'status_code' => 200 )); }]);يعرف المسار Route::get('/api/v1/products/{id?}', ['middleware' => 'auth.basic', function($id = null)رابطًا يطلب المنتجات مع معرّف اختياري id. يُستخدم المعرف لطلب منتج واحد وفي حال عدم ذكره ترجِع واجهة التطبيقات جميع المنتجات. نحمي المورد بالتعليمة 'middleware' => 'auth.basic' التي تستوثق من العميل. حددنا نمط الاستيثاق بـauth.basic لاستخدام بريد المستخدِم (حقل email في جدول users) مع كلمة السر. يستدعي كل مسار النموذج المناسب للعثور على البيانات في القاعدة ثم نرسل الإجابة بصيغة JSON بالتعليمة Response::json. عند طلب الرابط http://larashop.dev/api/v1/products ستظهر نافذة تطلب إدخال بريد المستخدم وكلمة سره. استخدم الحساب الذي أنشأته في درس الاستيثاق وستظهر النتيجة التالية في المتصفح (بعد التنسيق) { "error":false, "products": [ { "id":"1", "name":"Mini skirt black edition", "price":"35" }, { "id":"2", "name":"T-shirt blue edition", "price":"64" }, { "id":"3", "name":"Sleeveless Colorblock Scuba", "price":"13" } ], "status_code":200 }حصلنا على إجابة بصيغة JSON للطلب الذي أرسلناه من أجل الحصول على منتجات الموقع. يشير الرمز 200 إلى أن معالجة الطلب تمّت دون مشاكل. يمكن للعميل الآن تنسيق الإجابة لعرضها بطريقة مناسبة. خاتمةوضعنا في هذا الدرس أساسا يمكن البناء عليه لإنشاء واجهات برمجية أكثر تطورا. يتلخص إنشاء واجهات برمجية في Laravel في تعريف المسارات، استخدام النماذج للحصول على البيانات المطلوبة ثم تهيئة الإجابة بصيغة JSON ثم إرسالها. ترجمة -وبتصرّف- للمقال Laravel 5 REST API لصاحبه Rodrick Kazembe.

اكتشفت مؤخرًا المتعة الكبيرة في استخدام مكتبة [Fractal المقدّمة من PHP League] لإنشاء استجابات للواجهات البرمجية التي تعطي مخرجات من نوع JSON وذلك عند العمل على نماذج Eloquent في إطاري العمل Laravel و Lumen للحصول على المخرجات التي أرغب بها. هذه الحزمة مشابهة إلى حدٍّ كبير لمكتبة ActiveModel Serializer في إطار العمل Rails، إذ إنّها تتيح لك التحكّم الدقيق بالمخرجات التي ترغب في وصولها إلى المستخدم، إضافة إلى أنّها تفصل الشيفرة المسؤولة عن إنشاء كائن JSON عن نموذج Eloquent وهذا أمر في غاية الأهمية. والآن بعد أن أتيح لي تطوير عدد من الواجهات البرمجية لفترة زمنية لا بأس بها، خطر لي أن أتحدّث عن الطرق التي اتبعتها في ربط Fractal مع تطبيقات Laravel و Lumen (تختلف طريقة الربط في إطار Lumen لأنّه لا يدعم ماكروات Response). المُسَلسِلات المخصّصة Costum Serializers بادئ ذي بدء، تدعم Fractal عددًا من المُسَلسِلات Serializers لتكوين بنية خاصة بالاستجابة، وتستخدم بصورة افتراضية المسَلسِل الذي يدعى بـ DataArraySerializer والذي يضيف مفتاح جذر root key يحمل الاسم data إلى الاستجابة، لذا إن كنت لا تمانع من استخدام هذا المُسَلسِل فيمكنك تجاوز هذه الخطوة. أما لو كنت ترغب في استخدام مُسَلسِل آخر فعليك تسجيل الصنف Manager مع حاوية IoC في مزوّد الخدمة AppServiceProvider أو في مزوّد خدمة آخر إن كنت ترى أنّه يناسبك أكثر، ولكن عليك الانتباه إلى أنّ دعم JSON-API غير مكتمل حتى الآن (المقالة الأصلية نشرت سنة 2015. (المترجم)). public function register() { $this->app->bind('League\Fractal\Manager', function($app) { $manager = new \League\Fractal\Manager; // Use the serializer of your choice. $manager->setSerializer(new \App\Http\Serializers\RootSerializer); return $manager; }); } إنشاء المحوّلات Transformers بعد ذلك سنحتاج إلى إنشاء بعض المحوّلات - محوّل لكل نوع من أنواع نماذج Eloquent التي ترغب في تخريجها بواسطة الواجهة البرمجية - وفي مثالنا هذا سأستخدم مدوّنة حيث يضمّ النموذج AppUser عددًا من نماذج AppPost وسنعرض المستخدم مع المقالات الخاصّة به. أنشأت مجلّدً للتحويلات داخل مجلّد Http: app/Http/Transoformers، والآن يمكنني إنشاء محوّلين، الأول لنموذج User والثاني لنموذج Post. محوّل المستخدمين User سيكون سهلًا، إذ أنّه سيُرجع الحقول المطلوبة من قبل واجهتي البرمجية. في هذا المثال، يمتلك النموذج User خاصّية is_admin وهي عبارة عن قيمة منطقية boolean. ويمكنني التعبير عن ذلك في المحوّل بواسطة العبارة (bool) $user->is_admin ولكن اعتبارًا من الإصدار 5.0 وما بعده من Laravel أصبح بالإمكان استخدام خاصّية $casts في النموذج وسيكون Eloquent قادرًا بعدها على معالجة عملية الوصف بالنيابة عنك. يستحسن معالجة مثل هذه الأمور ضمن النموذج لأنّها ستكون متاحة في التطبيق برمّته. <?php namespace App\Http\Transformers; use App\User; use League\Fractal\TransformerAbstract; class UserTransformer extends TransformerAbstract { /** * Turn this item object into a generic array. * * @param \App\User $user * @return array */ public function transform(User $user) { return [ 'id' => $user->id, 'first_name' => $user->first_name, 'last_name' => $user->last_name, 'email' => $user->email, 'is_admin' => $user->is_admin, 'created_at' => $post->created_at->toDateTimeString(), 'updated_at' => $post->updated_at->toDateTimeString() ]; } } بما أنّ خصائص التاريخ في نماذج Eloquent هي نسخ من مكتبة Carbon يمكن إذًا استخدام الدوال المساعدة التي تقدّمها هذه المكتبة لإرجاع التاريخ بالصيغة التي نرغب بها. وفي مثالنا سنستخدم الدالة toDateTimeString() وسيكون التاريخ بالصيغة التالية: Y-m-d H:i:s (السنة - الشهر - اليوم الساعة:الدقائق:الثواني). والآن سنحتاج إلى محوّل لأجل نموذج Post، وسيكون هذا المحوّل مختلفًا عن السابق لأنّنا نرغب في تضمين النموذج User المرتبط بنموذج Post مع هذه الاستجابة. <?php namespace App\Http\Transforers; use App\Post; use League\Fractal\TransformerAbstract; class PostTransformer extends TransformerAbstract { /** * List of resources possible to include * * @var array */ protected $availableIncludes = ['user']; /** * List of resources to automatically include. * * @var array */ protected $defaultIncludes = ['user']; /** * Turn this item object into a generic array. * * @param \App\Post $post * @return array */ public function transform(Post $post) { return [ 'id' => $post->id, 'title' => $post->title, 'content' => $post->content, 'created_at' => $post->created_at->toDateTimeString(), 'updated_at' => $post->updated_at->toDateTimeString(), 'published_at' => $post->published_at->toDateTimeString() ]; } /** * Include user. * * @param \App\Post $post * @return League\Fractal\ItemResource */ public function includeLevels(Post $post) { return $this->item($post->user, new UserTransformer); } } لاحظ أنّه بالإمكان إرجاع $this->collection داخل المحوّل إن كنت ترغب في ربط مجموعة بدل من عنصر واحد. إنشاء الاستجابات في Laravel عادة ما أنشئ مزوّد خدمة Fractal FractalServiceProvider والذي يضمّ التابع register() الذي قمت بوصفه سابقًا، ثم أسجّل بعض الماكروات في التابع boot() كما تلاحظ هنا. سيؤدي ذلك إلى إضافة تابعين إضافيين إلى معمل (factory) Response في Laravel وسيسهّل إرجاع الاستجابات على هيئة عناصر أو مجموعات. لاحظ أنّي حدّدت نوع (type hint) المحوّل ليكون نسخة من الصنف TransformerAbstract وذلك لأنّي أنشئ دائمًا المحوّلات من الاستجابات بدلًا من صيغة الدالة المغلقة closure لأنّي أرى بأنّ هذه الطريقة ستحافظ على ترتيب الشيفرات التي أكتبها. لكن إن كنت تفضل استخدام الدوال المغلقة بدلًا من المحوّلات فيمكنك بكل ساطة أن لا تحدد نوع المحوّل ضمن المعاملات. public function boot() { $fractal = $this->app->make('League\Fractal\Manager'); response()->macro('item', function ($item, \League\Fractal\TransformerAbstract $transformer, $status = 200, array $headers = []) use ($fractal) { $resource = new \League\Fractal\Resource\Item($item, $transformer); return response()->json( $fractal->createData($resource)->toArray(), $status, $headers ); }); response()->macro('collection', function ($collection, \League\Fractal\TransformerAbstract $transformer, $status = 200, array $headers = []) use ($fractal) { $resource = new \League\Fractal\Resource\Collection($collection, $transformer); return response()->json( $fractal->createData($resource)->toArray(), $status, $headers ); }); } والآن أصبح من السهل إنشاء استجابة واحدة (لمستخدم واحد مثلًا) ومجموعة من الاستجابات (لجميع مقالات المدوّنة مثلًا). /** * GET /users/1 * * @param int $userId * @return \Illuminate\Http\Response */ public function showUser($userId) { $user = \App\User::findOrFail($userId); return response()->item($user, new \App\Http\Transformers\UserTransformer); } /** * GET /posts * * @return \Illuminate\Http\Response */ public function showPosts() { $posts = \App\Post::with('user')->get(); return response()->collection($posts, new \App\Http\Transformers\PostTransformer); } إن كنت ترغب في استخدام حالة استجابة HTTP أخرى مثل 201 (تم الإنشاء) أو 204 (لا يوجد محتوى) يمكنك وبكل سهولة تمرير رمز الحالة كمعامل ثالث إلى الماكرو. إنشاء الاستجابات في Lumen يتطلّب إنشاء الاستجابات في Lumen اتباع أسلوب مختلف قليلًا؛ ذلك لأنّ Lumen لا يدعم الماكروات في معمل Response؛ لذا سأضيف هذه التوابع إلى المتحكّم الرئيسي في الواجهة البرمجية. /** * Create the response for an item. * * @param mixed $item * @param \League\Fractal\TransformerAbstract $transformer * @param int $status * @param array $headers * @return Response */ protected function buildItemResponse($item, \League\Fractal\TransformerAbstract $transformer, $status = 200, array $headers = []) { $resource = new \League\Fractal\Resource\Item($item, $transformer); return $this->buildResourceResponse($resource, $status, $headers); } /** * Create the response for a collection. * * @param mixed $collection * @param \League\Fractal\TransformerAbstract $transformer * @param int $status * @param array $headers * @return Response */ protected function buildCollectionResponse($collection, \League\Fractal\TransformerAbstract $transformer, $status = 200, array $headers = []) { $resource = new \League\Fractal\Resource\Collection($collection, $transformer); return $this->buildResourceResponse($resource, $status, $headers); } /** * Create the response for a resource. * * @param \League\Fractal\Resource\ResourceAbstract $resource * @param int $status * @param array $headers * @return Response */ protected function buildResourceResponse(\League\Fractal\Resource\ResourceAbstract $resource, $status = 200, array $headers = []) { $fractal = app('League\Fractal\Manager'); return response()->json( $fractal->createData($resource)->toArray(), $status, $headers ); } يمكنك الآن استدعاء أي تابع من هذه التوابع في أي متحكّم موروث من هذا المتحكّم لإنشاء نفس الاستجابات التي أنشأناها مع Laravel. return $this->buildItemResponse($user, new \App\Http\Transformers\UserTransformer); return $this->buildCollectionResponse($posts, new \App\Http\Transformers\PostTransformer); ترجمة - وبتصرّف - للمقال Using Fractal with Laravel and Lumen لصاحبه Dwight Conrad Watson.

بدأ تطوير لغة البرمجة Go بتجربة من مهندسين يعملون في Google لتلافي بعض التعقيدات الموجودة في لغات برمجة أخرى مع الاستفادة من نقاط قوّتها. تُطوَّر لغة Go باستمرار بمشاركة مجتمع مفتوح المصدر يزداد باضطّراد. تهدف لغة البرمجة Go إلى أن تكون سهلة، إلا أن اصطلاحات كتابة الشفرة البرمجية في Go قد تكون صعبة الاستيعاب. سأريكم في هذا الدرس كيف أبدأ جميع مشاريعي البرمجية عندما أستخدم Go، وكيفية استخدام التعابير التي توفّرها هذه اللغة. سننشئ خدمة سند خلفي Backend لتطبيق وِب. إعداد بيئة العمل الخطوة الأولى هي - بالطبع - تثبيتُ Go. يمكن تثبيت Go من المستودعات الرسمية على توزيعات لينكس؛ مثلا بالنسبة لأوبونتو: sudo apt install golang-go إصدارات Go الموجودة في المستودعات الرسمية تكون في العادة أقدم قليلا من تلك الموجودة على الموقع الرسمي، إلا أنها تؤدي الغرض؛ علاوة على سهولة التثبيت. يمكنك تثبيت إصدارات أحدث على أوبونتو (هنا) وCentos (هنا). بالنسبة لمستخدمي نظام Mac OS فيمكنهم تثبيت اللغة عن طريق Homebrew: brew install go يحوي الموقع الرسمي كذلك الملفات التنفيذية لتثبيت اللغة على أغلب أنظمة التشغيل، بما في ذلك ويندوز. تأكّد من تثبيت Go بتنفيذ الأمر التالي: go version مثال لنتيجة اﻷمر أعلاه (على توزيعة أوبونتو): go version go1.6.2 linux/amd64 – روابط للتثبيت على وندوز وإعداد المسارات – توجد الكثير من محرّرات النصوص والإضافات المتاحة لكتابة شفرات Go. أفضّل شخصيّا محرّر الشفرات Sublime Text وإضافة GoSublime؛ إلا أن طريقة كتابة Go تتيح استخدام محرّرات نصوص عاديّة بسهولة خصوصا للمشاريع الصغيرة. أعمل مع محترفين يقضون كامل اليوم في البرمجة بلغة Go باستخدام محرّر النصوص Vim، دون أي إضافة لإبراز صيغة الشفرات البرمجية Syntax highlighting. بالتأكيد لن تحتاج لأكثر من محرّر نصوص بسيط للبدء في تعلّم Go. مشروع جديد إن لم تكن أنشأت مجلّدا للعمل أثناء تثبيت Go وإعداده فالوقت مناسب لذلك. تتوقّع أدوات Go أن توجد جميع الشفرات البرمجية على المسار GOPATH/src$، وبالتالي سيكون عملنا دائما في هذا المجلّد. يمكن لمجموعة أدوات Go كذلك أن تتخاطب مع مشاريع مُضيَّفة على مواقع مثل GitHub وBitbucket إن أُعدّت لذلك. سننشئ لأغراض هذا الدرس مستودعا جديدا فارغا على GitHub ولنسمّه “hello” (أو أي اسم يناسبك). ننشئ مجلّدا ضمن مجلّد GOPATH لاستقبال ملفات المستودع (أبدل your-username باسم المستخدم الخاصّ بك على GitHub): mkdir -p $GOPATH/src/github.com/your-username cd $GOPATH/src/github.com/your-username ننسخ المستودع ضمن المجلّد الذي أنشأناه أعلاه: git clone git@github.com:your-username/hello cd hello سننشئ الآن ملفا باسم main.go ليحوي برنامجا قصيرا بلغة Go: package main func main() { println("hello!") } نفّذ الأمر go build لتصريف جميع محتويات المجلّد الحالي. سينتُج ملف تنفيذي بنفس الاسم؛ يمكنك بعدها طلب تشغيله بذكر اسمه على النحو التالي: go build ./hello النتيجة: hello! ما زلت رغم سنوات من التطوير بلغة Go أبدأ مشاريعي بنفس الطريقة: مستودع Git فارغ، ملف main.go وبضعة أوامر. يصبح أي تطبيق يتبع الطرق المتعارف عليها لتنظيم شفرة Go قابلا للتثبيت بسهولة بالأمر go get. إن أودعت على سبيل المثال الملف أعلاه ودفعته إلى مستودع Git فإن أي شخص لديه بيئة عمل Go يمكنه تنفيذ الخطوتين التاليتين لتشغيل البرنامج: go get github.com/your-username/hello $GOPATH/bin/hello إنشاء خادوم وب فلنجعل برنامجنا البسيط السابق خادوم وب: package main import "net/http" func main() { http.HandleFunc("/", hello) http.ListenAndServe(":8080", nil) } func hello(w http.ResponseWriter, r *http.Request) { w.Write([]byte("hello!")) } هناك بضعة سطور تحتاج للشرح. نحتاج أولا لاستيراد الحزمة net/httpمن المكتبة المعيارية لـGo: import "net/http" ثم نثبّت دالة معالجة Handler function في المسار الجذر لخادوم الوِب. تتعامل http.HandleFunc مع الموجّه المبدئي لطلبات Http في Go، وهو ServeMux. http.HandleFunc("/", hello) الدالة hello هي من النوع http.HandlerFunc الذي يسمح باستخدام دوال عاديّة على أنها دوال معالجة لطلبات HTTP. للدوال من النوع http.HandlerFunc توقيع Signature خاص (توقيع الدالة هو المعطيات المُمرَّرة لها وأنواع البيانات التي تُرجعها هذه الدالة) ويمكن تمريرها في معطى إلى الدالة HandleFunc التي تسجّل الدالة المُمرَّرة في المُعطى لدى الموجِّه ServeMux، وبالتالي يُنشئ خادوم الوِب، في كلّ مرة يصله فيها طلب جديد يطابق المسار الجذر، يُنشئ نسخة جديدة من الدالة hello. تستقبل الدالة hello متغيّرا من النوع http.ResponseWriter الذي تستخدمه الدالة المُعالِجة لإنشاء إجابة HTTP وبالتالي إنشاء ردّ على طلب العميل عن طريق التابع Write الذي يوفّره النوع http.ResponseWriter. بما أن التابع http.ResponseWriter.Write يأخذ معطى عامًّا من النوع []byte أو byte-slice، فنحوّل السلسة النصيّة hello إلى النوع المناسب: func hello(w http.ResponseWriter, r *http.Request) { w.Write([]byte("hello!")) } في الأخير نشغّل خادوم وب على المنفذ 8080 عبر الدالة http.ListenAndServe التي تستقبل معطيَين، الأول هو المنفَذ Port والثاني دالة معالجة. إذا كانت قيمة المعطى الثاني هي nil فهذا يعني أننا نريد استخدام الموجّه المبدئي DefaultServeMux. هذا الاستدعاء متزامن Synchronous، أو معترِض Blocking، يبقي البرنامج قيد التشغيل إلى أن يُقطَع الاستدعاء. صرّف وشغّل البرنامج بنفس الطريقة السابقة: go build ./hello افتح سطر أوامر - طرفيّة - آخر وأرسل طلب HTTP إلى المنفذ 8080: curl http://localhost:8080 النتيجة: hello! الأمر بسيط. ليست هناك حاجة لتثبيت إطار عمل خارجي، أو تنزيل اعتماديات Dependencies أو إنشاء هياكل مشاريع. الملف التنفيذي نفسه هو شفرة أصيلة Native code بدون اعتمادات تشغيلية. علاوة على ذلك، المكتبة المعيارية لخادوم الوِب موجهة لبيئة الإنتاج مع دفاعات ضدّ الهجمات الإلكترونية الشائعة. يمكن لهذه الشفرة الإجابة على الطلبات عبر الشبكة مباشرة ودون وسائط. إضافة مسارات جديدة يمكننا فعل أمور أكثر أهمية من مجرّد قول مرحبا (hello). فليكن المُدخَل اسم مدينة نستخدمه لاستدعاء واجهة تطبيقات برمجيّة API لأحوال الطقس ونعيد توجيه الإجابة - درجة الحرارة - في الرد على الطلب. توفّر خدمة OpenWeatherMap واجهة تطبيقات برمجيّة مجانيّة وسهلة الاستخدام للحصول على توقّعات مناخية. سجّل في الموقع للحصول على مفتاح API. يمكن الاستعلام من OpenWeatherMap حسب المدن. تُرجع واجهة التطبيقات البرمجية إجابة على النحو التالي (عدّلنا قليلا على النتيجة): { "name": "Tokyo", "coord": { "lon": 139.69, "lat": 35.69 }, "weather": [ { "id": 803, "main": "Clouds", "description": "broken clouds", "icon": "04n" } ], "main": { "temp": 296.69, "pressure": 1014, "humidity": 83, "temp_min": 295.37, "temp_max": 298.15 } } المتغيّرات في Go ذات أنواع ثابتة Statical type، بمعنى أنه ينبغي التصريح بنوع البيانات التي تخزّنها المتغيّرات قبل استخدامها. لذا سيتوجّب علينا إنشاء بنية بيانات لمطابقة صيغة رد الواجهة البرمجية. لا نحتاج لحفظ جميبع المعلومات، بل يكفي أن نحتفظ بالبيانات التي نهتم بشأنها. سنكتفي الآن باسم المدينة ودرجة الحرارة المتوقّعة التي تأتي بوحدة الكيلفن Kelvin. سنعرّف بنية لتمثيل البيانات التي نحتاجها من خدمة التوقعات المناخية. type weatherData struct { Name string `json:"name"` Main struct { Kelvin float64 `json:"temp"` } `json:"main"` } تعرّف الكلمة المفتاحية type بنية بيانات جديدة نسمّيها weatherData ونصرّح بكونها من النوع struct. يحوي كلّ حقل في المتغيّرات من نوع struct اسما (مثلا Name أو Main)، نوع بيانات (string أو struct آخر مجهول الاسم) وما يُعرَف بالوسم Tag. تشبه الوسوم في Go البيانات الوصفية Metadata، وتمكّننا من استخدام الحزمة encoding/json لإعادة صفّ الإجابة التي تقدّمها خدمة OpenWeatherMap وحفظها في بنية البيانات التي أعددناها. يتطلّب الأمر كتابة شفرة برمجية أكثر ممّا عليه الحال في لغات برمجيّة ذات أنواع ديناميكية للبيانات (بمعنى أنه يمكن استخدام متغيّر فور احتياجنا له دون الحاجة للتصريح بنوع البيانات) مثل روبي وبايثون، إلا أنه يمنحنا خاصيّة الأمان في نوع البيانات. عرّفنا بنية البيانات، نحتاج الآن لطريقة تمكّننا من ملْء هذه البنية بالبيانات القادمة من واجهة التطبيقات البرمجية؛ سنكتُب دالة لهذا الغرض. func query(city string) (weatherData, error) { resp, err := http.Get("http://api.openweathermap.org/data/2.5/weather?APPID=YOUR_API_KEY&q=" + city) if err != nil { return weatherData{}, err } defer resp.Body.Close() var d weatherData if err := json.NewDecoder(resp.Body).Decode(&d); err != nil { return weatherData{}, err } return d, nil } تأخذ الدالة سلسلة محارف تمثّل المدينة وتُرجِع متغيّرا من بنية بيانات weatherData وخطأ. هذه هي الطريقة الأساسية للتعامل مع الأخطاء في Go. تغلّف الدوال سلوكا معيَّنا، ويمكن أن يخفق هذا السلوك. بالنسبة لمثالنا، يمكن أن يخفق طلب GET الذي نرسله لـOpenWeatherMap لأسباب عدّة، وقد تكون البيانات المُرجَعة غير تلك التي ننتظرها. نُرجِع في كلتا الحالتين خطأ غير فارغ Non-nil للعميل الذي يُنتظَر منه أن يتعامل مع هذا الخطأ بما يتناسب مع السياق الذي أرسل فيه الطلب. إن نجح الطلب http.Get نؤجّل طلبا لغلق متن الإجابة لننفّذه بعد الخروج من نطاق Scope الدالة (أي بعد الرجوع من دالة طلب HTTP)، وهي طريقة أنيقة لإدارة الموارد. في أثناء ذلك نحجز بنية weatherData ونستخدم json.Decoder لقراءة بيانات الإجابة وإدخالها مباشرة في بنيتنا. عندما تنجح إعادة صياغة بيانات الإجابة نعيد المتغيّر weatherData إلى المُستدعي مع خطأ فارغ للدلالة على نجاح العملية. ننتقل الآن إلى ربط تلك الدالة بالدالة المعالجة للطلب: http.HandleFunc("/weather/", func(w http.ResponseWriter, r *http.Request) { city := strings.SplitN(r.URL.Path, "/", 3)[2] data, err := query(city) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } w.Header().Set("Content-Type", "application/json; charset=utf-8") json.NewEncoder(w).Encode(data) }) نعرّف دالة معالجة على السطر In-line بدلا من تعريفها منفصلة. نستخدم الدالة strings.SplitN لأخذ كل ما يوجد بعد /weather/ في المسار والتعامل معه على أنه اسم مدينة. ننفّذ الطلب وإن صادفتنا أخطاء نعلم العميل بها باستخدام الدالة المساعدة http.Error، ونوقف تنفيذ الدالة للدلالة على اكتمال طلب HTTP. إن لم يوجد خطأ نخبر العميل بأننا بصدد إرسال بيانات JSON إليه ونستخدم الدالة json.NewEncode لترميز محتوى weatherData بصيغة JSON مباشرة. الشفرة لحدّ الساعة أنيقة، تعتمد أسلوبا إجرائيا Procedural ويسهل فهمها. لا مجال للخطأ في تفسيرها ولا يمكنها تجاوز الأخطاء الشائعة. إن نقلنا الدالة المعالجة لـ "hello, world" إلى المسار hello/ واستوردنا الحزم المطلوبة فسنحصُل على البرنامج المُكتمل التالي: package main import ( "encoding/json" "net/http" "strings" ) func main() { http.HandleFunc("/hello", hello) http.HandleFunc("/weather/", func(w http.ResponseWriter, r *http.Request) { city := strings.SplitN(r.URL.Path, "/", 3)[2] data, err := query(city) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } w.Header().Set("Content-Type", "application/json; charset=utf-8") json.NewEncoder(w).Encode(data) }) http.ListenAndServe(":8080", nil) } func hello(w http.ResponseWriter, r *http.Request) { w.Write([]byte("hello!")) } func query(city string) (weatherData, error) { resp, err := http.Get("http://api.openweathermap.org/data/2.5/weather?APPID=YOUR_API_KEY&q=" + city) if err != nil { return weatherData{}, err } defer resp.Body.Close() var d weatherData if err := json.NewDecoder(resp.Body).Decode(&d); err != nil { return weatherData{}, err } return d, nil } type weatherData struct { Name string `json:"name"` Main struct { Kelvin float64 `json:"temp"` } `json:"main"` } نصرّف البرنامج وننفّذه بنفس الطريقة التي شرحناها أعلاه: go build ./hello نفتح طرفيّة أخرى ونطلب المسار http://localhost:8080/weather/tokyo (الحرارة بمقياس كلفن): curl http://localhost:8080/weather/tokyo النتيجة: {"name":"Tokyo","main":{"temp":295.9}} الاستعلام من واجهات برمجية عدّة ربما من الممكن الحصول على درجات حرارة أكثر دقّة إن استعلمنا من خدمات طقس عدّة وحسبنا المتوسّط بينها. تتطلّب أغلب الواجهات البرمجية لخدمات الطقس التسجيل. سنضيف خدمة Weather Underground، لذا سجّل في هذه الخدمة واعثر على مفاتيح الاستيثاق الضرورية لاستخدام واجهة التطبيقات البرمجية. بما أننا نريد أن نحصُل على نفس السلوك من جميع الخدمات فسيكون من المجدي كتابة هذا السلوك في واجهة. type weatherProvider interface { temperature(city string) (float64, error) // in Kelvin, naturally } يمكننا الآن تحويل دالة الاستعلام من openWeatherMap السابقة إلى نوع بيانات يوافق الواجهة weatherProvider. بما أننا لا نحتاج لحفظ أي حالة لإجراء طلب HTTP GET فسنستخدم بنية struct فارغة، وسنضيف سطرا قصيرا في دالة الاستعلام الجديدة لتسجيل ما يحدُث عند الاتصال بالخدمات لمراجعته في ما بعد: type openWeatherMap struct{} func (w openWeatherMap) temperature(city string) (float64, error) { resp, err := http.Get("http://api.openweathermap.org/data/2.5/weather?APPID=YOUR_API_KEY&q=" + city) if err != nil { return 0, err } defer resp.Body.Close() var d struct { Main struct { Kelvin float64 `json:"temp"` } `json:"main"` } if err := json.NewDecoder(resp.Body).Decode(&d); err != nil { return 0, err } log.Printf("openWeatherMap: %s: %.2f", city, d.Main.Kelvin) return d.Main.Kelvin, nil } لا نريد سوى استخراج درجة الحرارة (بالكلفن) من الإجابة، لذا يمكننا تعريف بنية struct على السطر Inline. في ما عدا ذلك فإن الشفرة البرمجية مشابهة لدالة الاستعلام السابقة، ولكنّها معرَّفة على صيغة تابع Method لبنية openWeatherMap. تتيح لنا هذه الطريقة استخدام عيّنة Instance من openWeatherMap مكان الواجهة weatherProvider. سنفعل نفس الشيء بالنسبة لخدمة Weather Underground. الفرق الوحيد مع الخدمة السابقة هو أننا سنخزّن مفتاح الواجهة البرمجية في بنية struct ثم نستخدمه في التابع. يجدر ملاحظة أن Weather Underground لا تعالج أسماء المدن المتطابقة بنفس جودة تعامل Open WeatherMap، وهو ما ينبغي الانتباه إليه في التطبيقات الفعلية. لن نعالج هذا الأمر في مثالنا البسيط هذا. type weatherUnderground struct { apiKey string } func (w weatherUnderground) temperature(city string) (float64, error) { resp, err := http.Get("http://api.wunderground.com/api/" + w.apiKey + "/conditions/q/" + city + ".json") if err != nil { return 0, err } defer resp.Body.Close() var d struct { Observation struct { Celsius float64 `json:"temp_c"` } `json:"current_observation"` } if err := json.NewDecoder(resp.Body).Decode(&d); err != nil { return 0, err } kelvin := d.Observation.Celsius + 273.15 log.Printf("weatherUnderground: %s: %.2f", city, kelvin) return kelvin, nil } لدينا الآن مزوّدا خدمة طقس. فلنكتب دالّة تستعلم من الاثنين وتعيد متوسّط درجة الحرارة. سنكفّ - حفاظا على بساطة المثال - عن الاستعلام إذا واجهتنا مشكلة في الحصول على بيانات من الخدمتين. func temperature(city string, providers ...weatherProvider) (float64, error) { sum := 0.0 for _, provider := range providers { k, err := provider.temperature(city) if err != nil { return 0, err } sum += k } return sum / float64(len(providers)), nil } لاحظ أن تعريف الدالة قريب جدّا من تعريف التابع temperature المُعرَّف في الواجهة weatherProvider. إن جمعنا الواجهات weatherProvider في نوع بيانات ثم عرّفنا تابعا باسم temperature على هذا النوع فسيمكننا إنشاء نوع جديد يجمع الواجهات weatherProvider. type multiWeatherProvider []weatherProvider func (w multiWeatherProvider) temperature(city string) (float64, error) { sum := 0.0 for _, provider := range w { k, err := provider.temperature(city) if err != nil { return 0, err } sum += k } return sum / float64(len(w)), nil } رائع! سنتمكّن من تمرير multiWeatherProvider إلى أي دالة تقبل weatherProvider. نربُط الآن خادوم HTTP بدالة temperature للحصول على درجات الحرارة عند طلب مسار به اسم مدينة: func main() { mw := multiWeatherProvider{ openWeatherMap{}, weatherUnderground{apiKey: "your-key-here"}, } http.HandleFunc("/weather/", func(w http.ResponseWriter, r *http.Request) { begin := time.Now() city := strings.SplitN(r.URL.Path, "/", 3)[2] temp, err := mw.temperature(city) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } w.Header().Set("Content-Type", "application/json; charset=utf-8") json.NewEncoder(w).Encode(map[string]interface{}{ "city": city, "temp": temp, "took": time.Since(begin).String(), }) }) http.ListenAndServe(":8080", nil) } صرّف البرنامج، شغّله واطلب رابط خادوم الوب كما فعلنا سابقا. ستجد - علاوة على الإجابة بصيغة JSON في نافذة الطلب - مُخرجات قادمة من تسجيلات الخادوم التي أضفناها أعلاه في النافذة التي شغّلت منها البرنامج. ./hello 2015/01/01 13:14:15 openWeatherMap: tokyo: 295.46 2015/01/01 13:14:16 weatherUnderground: tokyo: 273.15 $ curl http://localhost:8080/weather/tokyo {"city":"tokyo","temp":284.30499999999995,"took":"821.665230ms"} جعل الاستعلامات تعمل بالتوازي نكتفي لحدّ الساعة بالاستعلام من الواجهات البرمجية بالتتالي، الواحدة تلو الأخرى. لا يوجد ما يمنعنا من الاستعلام من الواجهتيْن البرمجيّتين في نفس الوقت، وهو ما سياسهم في تقليل الوقت اللازم للإجابة. نستفيد من إمكانات Go في التشغيل المتزامن عبر وحدات Go الفرعية goroutines والقنوات Channels. سنضع كل استعلام في وحدة فرعية خاصّة به ثم نشغّلها بالتوازي. نجمع الإجابات بعد ذلك في قناة واحدة ثم نحسب المعدّلات عندما تكتمل جميع الاستعلامات. func (w multiWeatherProvider) temperature(city string) (float64, error) { // ننشئ قناتيْن، واحدة لدرجات الحرارة والأخرى للأخطاء // يُضيف كل مزوّد خدمة قيمة إلى إحدى القناتيْن فقط temps := make(chan float64, len(w)) errs := make(chan error, len(w)) // نطلق بالنسبة لكلّ مزوّد خدمة وحدة فرعية جديدة بدالة مجهولة الاسم. تستدعي الدالة مجهولة الاسم التابع temperature ثم تعيد توجيه النتيجة المتحصًّل عليها. for _, provider := range w { go func(p weatherProvider) { k, err := p.temperature(city) if err != nil { errs <- err return } temps <- k }(provider) } sum := 0.0 // نجمع درجات الحرارة - أو الأخطاء في حالة وجودها - من كل خِدمة for i := 0; i < len(w); i++ { select { case temp := <-temps: sum += temp case err := <-errs: return 0, err } } // نُرجع الحرارة كما في السابق return sum / float64(len(w)), nil } يساوي الوقت اللازم الآن لتنفيذ جميع الاستعلامات المدة الزمنية اللازمة للحصول على إجابة من أبطأ خدمة طقس؛ بدلا من مجموع المدد الزمنية لجميع الاستعلامات كما كان سابقا. كل ما احتجنا له هو تعديل سلوك multiWeatherProvider الذي ما زال مع ذلك يُرضي حاجات واجهة weatherProvider البسيطة وغير المتوازية. السهولة انتقلنا ببضع خطوات وبالاقتصار فقط على المكتبة المعيارية لـGo من مثال “hello world” إلى خادوم سند خلفي Backend server يحترم مبادئ REST. يمكن نشر الشفرة التي كتبناها على أي معمارية خواديم تقريبا. الملف التنفيذي الناتج سريع ويتضمّن جميع ما يحتاجه للعمل؛ والأهم من ذلك، الشفرة البرمجيّة واضحة لقراءتها وفهمها. كما تمكن صيانتها وتمديدها بسهولة حسب الحاجة. أنا مقتنع أن كلّ هذه الميزات هي نتيجة لتفاني Go في البساطة. ترجمة - بتصرّف - للمقال How I start Go لصاحبه Peter Bourgon.

هنالك الكثير من الواجهات البرمجية المبنية على JSON التي توفر وصولًا عبر دوال من جهة الخادوم فقط، فلو أردنا استخدام عميل JavaScript مع تلك الواجهات البرمجية الخارجية، فسنحتاج إلى ضبط خادومنا للوصول إلى تلك الواجهات البرمجية الخارجية ثم تخديم تلك البيانات عبر Ajax أو عبر نقطة نهاية (endpoint) خاصة بك. ولحسن الحظ، فعل ذلك سهلٌ جدًا في ووردبريس. سأريك في هذا الدرس كيفية الحصول على أجور الشحن عبر Easy Post API باستخدام نقطة نهاية في ووردبريس. لتبسيط هذا الدرس (وجعله قصيرًا) فسنرسل ستة معاملات (وهو عدد كاف لواجهة Easy Post البرمجية لإعادة أجور الشحن): عرض الطرد ارتفاع الطرد طول الطرد وزن الطرد كود Zip للمرسل كود Zip للمستقبل ضبط نقطة نهاية JSON أوّل خطوة هي ضبط المسار الذي ستُخدَّم منه بيانات JSON، وفي هذه الحالة هو: /wp-json/easy-post/v1/rates/ الشيفرة: /** * Sets up a JSON endpoint at /wp-json/easy-post/v1/rates/ */ function easy_post_api_init() { $namespace = 'easy-post/v1'; register_rest_route( $namespace, '/rates/', array( 'methods' => 'GET', 'callback' => 'easy_post_return_rates', ) ); } add_action( 'rest_api_init', 'easy_post_api_init' ); عرض البيانات تتوقع نقطة النهاية إرسال ست قيم من البيانات كطلبية، وستستخدمها للحصول على البيانات من الواجهة البرمجية الخارجية، فلو لم تكن تلك القيم موجودةً فستستعمل القيم الافتراضية، وسنحرص أن تكون تلك القيم رقميةً فقط. مثال عن رابط URL مع قيم لكل المعاملات: /wp-json/easy-post/v1/rates/?zip=78701&width=10&length=10&height=10&weight=10&shipping_zip=78751 الشيفرة: /** * عرض مخرجات Easy Post عبر النهاية الطرفية * * نستخدم القيم المبدئية في حال عدم ذكر بيانات في الطلب، إلا أن إعادة خطأ ربما تكون فكرة أفضل. * Valid URL: /wp-json/easy-post/v1/rates/?zip=78701&width=10&length=10&height=10&weight=10&shipping_zip=78751 */ function easy_post_return_rates( WP_REST_Request $request ) { // الإعدادات المبدئية للشحن $defaults = array( 'zip' => 78701, 'width' => 10, 'length' => 10, 'height' => 10, 'weight' => 16, 'shipping_zip' => 94105 ); // الحصول على المعطيات من الطلب $params = $request->get_query_params(); // التأكد من توفر جميع المعطيات $params = array_replace( $defaults, $params ); // تنظيف المفاتيح $params = array_map( "absint", $params ); // إنشاء قيم مفاتيح فريدة لتحديد قيم البيانات المؤقتة transient أو العثور عليها $key = 'easy_post_' . implode( "_", $params ); /** * نحتفظ بالإجابة في قيمة مؤقتة transient ضمن قاعدة بيانات ووردبريس * لتجنب إرسال الكثير من الطلبات في وقت قصير * * تنتهي صلاحية هذه البيانات بعد عشر دقائق */ if ( false === ( $data = get_transient( $key ) ) ) { $data = easy_post_make_request( $params ); $response = new WP_REST_Response( $data ); // التخبئة لمدة عشر دقائق set_transient( $key, $response, 60 * 10 ); } else { // إرجاع القيمة المخبّأة return get_transient( $key ); } return $response; } الحصول على البيانات الدالة easy_post_make_request()‎ هي الدالة التي تطلب البيانات من الواجهة البرمجية الخارجية، والغرض من أغلبية الشيفرات التي هنا هي تجهيز الطلبية ضمن مصفوفة يمكن لواجهة Easy Post البرمجية أن تعالجها: /** *العثور على البيانات من الواجهة البرمجية لـ Easy Post باستخدام الدالة wp_remote_post */ function easy_post_make_request( $params ) { $to_address = array( 'zip' => $params['shipping_zip'], 'country' => 'US' ); $from_address = array( 'zip' => $params['zip'], 'country' => 'US' ); $parcel = array( 'length' => $params['length'], 'width' => $params['width'], 'height' => $params['height'], 'weight' => $params['weight'] ); $request = array( 'shipment' => array( 'to_address' => $to_address, 'from_address' => $from_address, 'parcel' => $parcel ) ); $args = array( 'method' => 'POST', 'blocking' => true, 'headers' => array( 'Content-Type' => 'application/json' ), 'timeout' => 15, 'sslverify' => false, 'body' => json_encode( $request ) ); // ضع مفتاح API الخاص بك مكان EASYPOST_TEST_API_KEY $api_url = 'https://' . EASYPOST_TEST_API_KEY . ':@api.easypost.com/v2/shipments'; $response = wp_remote_post( $api_url, $args ); if ( ! is_wp_error( $response ) ) { $response = json_decode( $response['body'] ); } return $response; } استخدام البيانات عندما نحاول الوصول إلى نقطة النهاية التي أنشأناها، فإن بيانات JSON التي جلبناها من Easy Post ستظهر لنا: يمكنك الآن الحصول على أجور الشحن ديناميكيًا في موقعك باستخدام نقطة النهاية التي أنشأناها في هذا الدرس. يمكنك الاطلاع على كامل الشيفرة هنا. ترجمة –وبتصرّف– للمقال How to Set JSON Endpoints in WordPress to Access an External API لصاحبه Devin Price حقوق الصورة البارزة محفوظة لـ Freepik

قدّمنا في الدرس السابق جافاسكريبت وذكرنا تموضعها في الوِب بالنسبة لـHTML وCSS، كما تحدّثنا عن واجهات برمجة التطبيقات الخاصّة بالمتصفّح وتلك القادمة من طرف ثالث. سنبدأ في هذا الجزء من الدرس النظر في بعض التعليمات البرمجية، وأثناء ذلك، يمكنك استكشاف ما يحدث فعليًا عند تشغيل شفرة جافاسكريبت في صفحتك. ما الذي تفعله جافاسكريبت على صفحتك؟ لنلخص بإيجاز قصة ما يحدث عند تنزيل صفحة وِب في المتصفح. عندما يُنزّل المتصفّح الشفرة التي كتبتها، والمكوّنة من وسوم HTML، أنماط CSS وتعليمات جافاسكريبت فإنه يشغّلها داخل بيئة تنفيذ (علامة تبويب Tab في المتصفح). تشبه هذه العملية المصنع الذي يأخذ المواد الخام (الشفرة) ويُخرج المنتح (صفحة وِب). يُنفّذ معالج جافاسكريبت JavaScript engine الموجود في المتصفّح تعليمات جافاسكريبت بعد أن تُجمَّع HTML وCSS وتوضعان في صفحة وِب. يضمن انتظار التجميع أنّ بنية الصفحة وتنسيقها موجودان بالفعل عند بدء تشغيل جافاسكريبت، أي أنه عند تشغيل جافاسكريبت تكون جميع تعليمات HTML وCSS موجودة ونفّذها المتصفّح. يعدّ هذا الأمر جيّدًا، إذ أن استخدام جافاسكريبت الشائع هو تعديل HTML و CSS ديناميكًيا لتحديث واجهة المستخدم، من خلال واجهة برمجة التطبيقات DOM التي تحدّثنا عنها في الدرس السابق؛ فإن نُزِّلت تعليمات جافاسكريبت وحاول المتصفّح تشغيلها قبل أن يكون هناك HTML و CSS فستحدث أخطاء. أمان المتصفح تعدّ كل علامة تبويب Tab في المتصفح دلوًا منفصلًا لتشغيل الشفرة (تسمى هذه الدلاء “بيئات التنفيذ” Execution environments من الناحية التقنية). يعني هذا أنه في معظم الحالات تُشغَّل الشفرة في كل علامة تبويب منفصلة عن الشفرات في بقية التبويبات، ولا يمكن للتعليمات البرمجية في علامة تبويب واحدة أن تؤثر مباشرة على التعليمات البرمجية في علامة تبويب أخرى - أو على موقع وِب آخر. هذا إجراء أمني جيد. لو لم يكن هذا هو الحال، لكان بإمكان القراصنة كتابة صفحات وِب مهمّتها سرقة المعلومات من المواقع الأخرى التي يزورها المتصفّح، وغيرها من هذه الأشياء السيئة. ملاحظة: هناك طرق لإرسال التعليمات البرمجية والبيانات بين مواقع وِب / علامات تبويب مختلفة بطريقة آمنة، ولكن هذه تقنيات متقدمة لن نغطيها في هذا الدرس. جافاسكريبت قيد التشغيل عندما يواجه المتصفح كتلة تعليمات برمجية من جافاسكريبت، فإنه يعمل بالترتيب، من أعلى إلى أسفل. وهذا يعني أنك تحتاج إلى توخي الحذر في الترتيب الذي تضعه فيه. على سبيل المثال، في شفرة جافاسكريبت التي شاهدناها في المثال الأول: var para = document.querySelector('p'); para.addEventListener('click', updateName); function updateName() { var name = prompt('Enter a new name'); para.textContent = 'Player 1: ' + name; } قمنا باختيار فقرة نصية (السطر 1)، ثم استدعينا مستمع الحدث Event listener بتطبيق التابعaddEventListener على الفقرة النصية المُخزَّنة في المتغيّر para (السطر 3)؛ لذا عندما يُنقر على النص تُشغَّل كتلة التعليمات البرمجية في الدالة updateName(). تُسمّى كُتلة التعليمات البرمجية القابلة لإعادة الاستخدام باستدعاء اسمها “وظائف” أو “دوال” Functions. يُطلب من المستخدم اسم جديد ثم يُدرَج هذا الاسم في الفقرة لتحديث العرض. إذا بدّلت ترتيب أول سطرين من التعليمات البرمجية، فإن الشفرة البرمجية لن تعمل . ستحصُل بدلا من ذلك خطأ في وحدة تحكم المتصفح الخاصة بالمطورين Console: -TypeError: para is undefined. وهذا يعني أن الكائن para غير موجود بعد، لذلك لا يمكننا إضافة مستمع الحدث إليه. ملاحظة: هذا خطأ شائع جدًا. يجب أن تكون حذرًا أن الكائنات Objects المشار إليها في التعليمات البرمجية موجودة قبل محاولة استخدامها. الفرق بين التعليمات البرمجية المفسَّرة Interpreted و المُترجَمة Compiled لابد وأنك سمعت في سياق البرمجة بمصطلحيْ التفسير Interpretation و الترجمة Compilation. جافاسكريبت هي لغة مفسَّرة. تُشغَّل تعليمات جافاسكريبت البرمجية من أعلى إلى أسفل وتُرجَع نتيجة تشغيل التعليمات البرمجية على الفور. لست بحاجة لتحويل التعليمات البرمجية إلى شكل مختلف قبل أن يقوم المتصفح بتشغيلها. من ناحية أخرى، تُحوَّل الشفرة البرمجية للغات المترجمة إلى شكل آخر قبل أن يشغّلها الحاسوب. على سبيل المثال تُجمَّع C / C ++ في لغة Assembly التي يُشغّلها الحاسوب. لكلّ من المنهجيْن ميزات، لكنّها خارج نطاق هذا الدرس. جانب الخادوم Server Side و جانب العميل Client Side لابد وأنك سمعت بمصطلحي من جانب الخادوم وجانب العميل، خاصة في سياق تطوير الوِب: الشفرة من جانب العميل Client side هي شفرة تُشغَّل على حاسوب المستخدم. يُنزّل العميل التعليمات البرمجية التي ينفّذها المتصفّح ليعرض صفحة الوٍب. سنتحدّث في هذا الدرس عن جافاسكريبت من جانب العميل. من ناحية أخرى تُنفَّذ شفرة جانب الخادوم على الخادوم، ثم تُرسَل نتيجة التنفيذ إلى المتصفّح ليعرضها. مثال على لغات الوِب الشائعة من جانب الخادوم PHP وبايثون وروبي و ASP.NET. وجافاسكريبت! يمكن أيضا استخدام جافاسكريبت كلغة من جانب الخادوم، على سبيل المثال في بيئة Node.js الشائعة. يُستخدم مصطلح ديناميكي Dynamic لوصف كل من جافاسكريبت من جانب العميل واللغات من جانب الخادوم. تشير كلمة ديناميكي إلى القدرة على تحديث عرض صفحة الوِب أو التطبيق لإظهار أشياء مختلفة في ظروف مختلفة، وتوليد محتوى جديد حسب الطلب. تُنشِئ الشفرة من جانب الخادوم ديناميكيا محتوى جديدًا على الخادوم، سحب بيانات من قاعدة بيانات على سبيل المثال؛ في حين أن جافاسكريبت من جانب العميل تُنشِئ ديناميكيا محتوى جديدًا داخل المتصفح (العميل)، على سبيل المثال إنشاء جدول HTML جديد، وإدراج البيانات المطلوبة من الخادوم في ذلك الجدول، ثم عرض الجدول في صفحة وِب للمستخدم. يعمل المنهجان معًا عادة. يشار إلى صفحة الوِب التي لا يوجد بها محتوى ديناميكي بأنها ثابتة Static، حيث يظهر دائما نفس المحتوى بغضّ النظر عن الزائر. كيف تضيف جافاسكريبت إلى صفحتك؟ يتم تطبيق جافاسكريبت على صفحة HTML بطريقة مشابهة لـ CSS. في حين تستخدم CSS عناصر <link> لتطبيق الأنماط الخارجية وعناصر <style> لتطبيق الأنماط الداخلية على HTML، تحتاج جافاسكريبت إلى صديق واحد فقط في عالم HTML، العنصر <script>. دعونا نتعلم كيفية العمل. جافاسكريبت داخلي أنشئ مستند HTML بالمحتوى التالي <!DOCTYPE html> <html lang="ar" dir="rtl"> <head> <title>مثال تطبيقي لجافاسكريبت</title> </head> <body> <button>انقر هنا</button> </body> </html> </html> استعرض الملف في متصفح الوِب وفي محرر النصوص. سترى أن HTML أنشأت صفحة وِب بسيطة تحتوي على زر قابل للنقر. بعد ذلك، انتقل إلى محرر النصوص وأضف ما يلي مباشرة قبل وسم الإغلاق <body/>: <script> // سنضع تعليمات جافاسكريبت هنا </script> سنضيف الآن بعض جافاسكريبت داخل عنصر <script> لجعل الصفحة تفعل شيئا أكثر إثارة للاهتمام. أضف الشفرة التالية أسفل السطر // سنضع تعليمات جافاسكريبت هنا مباشرة: function createParagraph() { var para = document.createElement('p'); para.textContent = 'لقد نقرت على الزرّ!'; document.body.appendChild(para); } var buttons = document.querySelectorAll('button'); for (var i = 0; i < buttons.length ; i++) { buttons[i].addEventListener('click', createParagraph); } احفظ الملف في محرّر النصوص ثم حدّث الصفحة على المتصفح. يجب أن الآن أن تظهر فقرة جديدة أسفل الزّر عند النقر عليه. ملاحظة: إذا لم يعمل المثال الخاص بك، راجع الخطوات مرة أخرى وتحقق من أنك فعلت كل شيء بشكل صحيح. هل حفظت الملف بامتداد html (مثلا lesson1.html)؟ هل أضفت العنصر <script> بعد علامة <body/> مباشرة؟ هل أدخلت جافاسكريبت تماما كما هو موضح؟ جافاسكريبت حساسة لحالة الأحرف +(صغيرة Lowercase أو كبيرة Uppercase)، لذلك تحتاج إلى إدخال الشفرة تماما كما هو مبين، وإلا فلن تعمل. جافاسكريبت خارجي ماذا لو أردنا وضع جافاسكريبت لدينا في ملف خارجي؟ دعونا نستكشف هذا الآن. أولا، أنشئ ملفًا جديدا في نفس المجلّد الذي يوجد به ملف HTML وسمّه script.js. تأكد من أنه يحتوي على امتداد اسم الملفjs، وهذه هي الطريقة التي يُتعرَّف بها على أننا أمام ملف يحوي شفرات برمجية مكتوبة بجافاسكريبت. بعد ذلك، انسخ كل النص البرمجي من الوسم <script> في ملف HTML (تلك التعليمات الموجودة في الخطوة 4 من الفقرة السابقة) وألصقه في الملف script.js ثم احفظ هذا الملف. الآن استبدل العنصر الحالي <script> بما يلي. <script src="script.js"></script> يصبح محتوى الملف HTML على النحو التالي: <!DOCTYPE html> <html lang="ar" dir="rtl"> <head> <title>مثال تطبيقي لجافاسكريبت</title> </head> <body> <button>انقر هنا</button> <script src="script.js"></script> </body> </html> احفظ الملفّ ثم حدّث صفحة الوِب في المتصفح. ويجب أن تحصُل على نفس النتيجة تمامًا! ولكن الآن لدينا جافاسكريبت في ملف خارجي. يعدّ هذا عموما أمرا جيّدًا من حيث تنظيم التعليمات البرمجية الخاصة بك، وجعلها قابلة لإعادة الاستخدام عبر ملفات HTML متعددة. بالإضافة إلى HTML تصبح أسهل للقراءة دون وجود قطع ضخمة من السكربت ملقاة فيها. شفرات جافاسكريبت المضمنة في وسوم HTML تُكتَب شفرة جافاسكريبت أحيانا داخل HTML على النحو التالي: function createParagraph() { var para = document.createElement('p'); para.textContent = 'You clicked the button!'; document.body.appendChild(para); } <button onclick="createParagraph()">Click me!</button> استعرض المثال على Jsfiddle لهذا العرض التوضيحي نفس الوظائف التي عرضناها في الحالتيْن أعلاه، إلا أن عنصر <button> يتضمن خاصيّة onclick مضمنة لتشغيل وظيفة الدالة عند الضغط على زر. رجاءً لا تضمّن شفرات جافاسكريبت في وسوم HTML فهذه الطريقة من الممارسات السيئة (خلط HTML مع جافاسكريبت)، كما أنها غير فعالة لأن عليك أن تدرج الخاصيّة onclick="createParagraph()" على كل زر تريد تطبيق جافاسكريبت عليه. أما باستخدام شفرة جافاسكريبت منفصلة عن HTML فيمكنك تحديد كافة الأزرار باستخدام تعليمة واحدة. الشفرة التي استخدمناها أعلاه لهذا الغرض تبدو كما يلي: var buttons = document.querySelectorAll('button'); for (var i = 0; i < buttons.length ; i++) { buttons[i].addEventListener('click', createParagraph); } قد يبدو هذا الأمر أطول قليلا من الخاصيّة onclick، ولكنه سيعمل على جميع الأزرار بغض النظر عن عدد الأزرار الموجودة في الصفحة وعدد العناصر التي أُضيفت أو أزيلت، فلا يلزم تغيير جافاسكريبت. ملاحظة: جرب تعديل ملف HTML وإضافة بضعة أزرار أخرى في الملف. عند إعادة التحميل، يجب أن تجد أن جميع الأزرار عند النقر عليها سوف تُظهر فقرة. هذا رائع أليس كذلك؟ التعليقات Comments كما هو الحال مع HTML و CSS، يمكنك كتابة تعليقات في شفرة جافاسكريبت وسيتجاهلها المتصفح. تُستخدم التعليقات لتقديم توضيحات لزملائك المطورين عن كيفية عمل الشفرة، كذلك تمثل مرجعًا لك عن التعليمات البرمجية التي كتبتها عندما تعود مثلًا بعد 6 أشهر لتتذكر مالذي فعلته. التعليقات مفيدة جدًا، ويجب عليك استخدامها في كثير من الأحيان، وخاصة بالنسبة للتطبيقات الكبيرة. هناك نوعان من التعليقات: تعليقات من سطر واحد، وتُكتَب بعد عموديْن مائليْن؛ مثلا: // هذا تعليق تعليق متعدّد الأسطر. يُكتَب بين المحارف / * و * / على النحو التالي: /* هذا تعليق هو الآخر */ تطبيق التعليقات على تعليمات جافاسكريبت السابقة: // دالة تنشئ فقرة جديدة وتضيفها إلى نهاية متن الصفحة function createParagraph() { var para = document.createElement('p'); para.textContent = 'You clicked the button!'; document.body.appendChild(para); } /* 1. نحصُل على مراجع بجميع الأزرار الموجودة في الصفحة ونضعها في مصفوفة 2. نمرّ على جميع الأزرار ونضيف إلى كلّ منها مستمعًا لحدث النقر تُنفَّذ الدالة ()createParagraph عندما ينقر على زرّ في الصفحة. */ var buttons = document.querySelectorAll('button'); for (var i = 0; i < buttons.length ; i++) { buttons[i].addEventListener('click', createParagraph); } كانت هذه خطوتك الأولى في عالم جافاسكريبت. لقد بدأنا بالمفاهيم النظرية فقط لجعلك تفهم لماذا تُستخدم جافاسكربت وما الأشياء التي يمكنك القيام بها باستخدام هذه اللغة. تعرّفت في هذا المقال على بضعة أمثلة من التعليمات البرمجية وتعلّمت كيفية تتفاهم لغةُ جافاسكريبت مع بقية التعليمات البرمجية على موقع الوِب. قد تبدو الآن جافاسكريبت شاقة بعض الشيء، ولكن لا تقلق - في هذه السلسلة من الدروس سوف نأخذك في خطوات بسيطة تمكّنك من المضي قدمًا في عالم جافاسكربت. ترجمة - بتصرف - للمقال What is JavaScript? الذي اشترك في كتابته مساهمو موزيللا.

سنتعرّف في هذا الدّرس على لغة البرمجة جافاسكربت من منظور عامّ وسنجيب على تساؤلاتك ماهي جافاسكربت؟ وما الذي تقوم بعمله في صفحات الوِب؟ و نتأكد من أن مفهوم جافاسكريبت قد أصبح واضحًا لديك. ملحوظة: يتوجَّه هذا الدرس، والدروس التي تليه - إلى من لديهم معرفة سابقة بأساسيّات التطوير للوِب: HTML وCSS. التعريف العام لجافاسكريبت تُعرَّف جافاسكريبت بأنّها لغة برمجة تسمح لك بتنفيذ أشياء معقدة على صفحات الوِب، تعدّ صفحات الوِب الحديثة أكثر من مجرد موقع يُظهر لك معلومات ثابتة تتصفحها، فهي - مثلًا - تعرض تحديثات المحتوى المباشرة، أو تعرض الخرائط التفاعلية، أو الرسومات المتحركة ثنائية أو ثلاثية الأبعاد، أو تمرّر ملفات الفيديو المصورة، وما إلى ذلك. تمثّل جافاسكريبت الطبقة الثالثة من طبقات تقنيات الوِب القياسية. الطبقتان الأوليان هما HTML وCSS. HTML هي لغة توصيف Markup نستخدمها لإنشاء محتوى الوِب وإضفاء معنى عليه، مثل تعريف الفقرات، العناوين وجداول البيانات أو تضمين الصور ومقاطع الفيديو في الصفحة. CSS هي لغة تعرّف قواعد الأنماط Style rules التي نستخدمها لتطبيق التصميم على المحتوى الذي تصفه HTML، على سبيل المثال، تعيين ألوان وخطوط الخلفية، ووضع محتوى ما في أعمدة متعددة. Javascript هي لغة برمجة تمكّنك من إنشاء محتوى حيوي وديناميكي، التحكم في الوسائط المتعددة، وتحريك الصور وأمورا وكل شيء آخر. حسنًا، ليس كل شيء، ولكن من المدهش ما يمكنك تحقيقه مع بضعة أسطر من شفرة جافاسكريبت. سنأخذ مثالًا يوضح كيفية بناء هذه الطبقات الثلاث فوق بعضها بشكل لطيف. لنأخذ تسمية نص بسيط كمثال. سنضع علامة عليه باستخدام HTML لإعطائه هيكلًا وغرضًا: <p>Player 1: Chris</p> النتيجة حتى الآن. سنضيف تحسينات على الشكل باستخدام CSS: p { font-family: 'helvetica neue', helvetica, sans-serif; letter-spacing: 1px; text-transform: uppercase; text-align: center; border: 2px solid rgba(0,0,200,0.6); background: rgba(0,0,200,0.3); color: rgba(0,0,200,0.6); box-shadow: 1px 1px 2px rgba(0,0,200,0.4); border-radius: 10px; padding: 3px 10px; display: inline-block; cursor:pointer; } أصبحت النتيجة الآن كالتالي. وأخيرًا، نضيف بضعة تعليمات جافاسكريبت لتنفيذ السلوك الديناميكي. var para = document.querySelector('p'); para.addEventListener('click', updateName); function updateName() { var name = prompt('Enter a new name'); para.textContent = 'Player 1: ' + name; } غرضنا الآن ليس شرح التعليمات السابقة (سنفعل ذلك لاحقا) ولكن توضيح ما يمكن أن تضيفه جافاسكريبت لـHTML وCSS. عند النقر على النص تظهر نافذة تطلُب إدخال اسم ثم عند إدخال الاسم في النافذة المنبثقة والنقر على زر OK تأخذ النص وتطبعه أمام الجملة Player 1. استعرض المثال على Jsfiddle. الشفرة المصدرية الكاملة للمثال. التشغيل المباشر. يمكن لجافاسكريبت أن تفعل أكثر من ذلك بكثير؛ دعونا نستكشف مزيدًا من التفاصيل. مالذي يمكن لجافاسكريبت فعله حقا؟ تتكون لغة جافاسكريبت الأساسية من بعض ميزات البرمجة الشائعة التي تسمح لك بفعل أشياء مثل: تخزين قيم مفيدة داخل متغيرات Variables. في المثال السابق على سبيل المثال، نطلب من المستخدم ادخال اسم جديد ثم يُخزَّن هذا الاسم في متغير يسمى name. العمليات على أجزاء من النص (المعروفة باسم سلاسل المحارف Strings في البرمجة). في المثال أعلاه، نأخذ سلسلة المحارف Player 1: ونضمها إلى متغير الاسم المذكور أعلاه لإنشاء الجملة الكاملة، على سبيل المثال Player 1: Chris. تشغيل التعليمات البرمجية ردًا على أحداث معينة تحدث على صفحة وِب. في المثال أعلاه استخدمنا الحدث click الذي يخبرنا أن المستخدم نقر على النصّ ثم نشغّل الشفرة التي تعمل على تحديث النص. والكثير! ولكن ما هو أكثر إثارة هو وظيفة بُنيت على لبّ لغة جافاسكريبت الأساسي. تسمى APIs وهي اختصار لـ Application Programming Interface واجهات برمجة التطبيقات. تتيح لك واجهات برمجة التطبيقات (APIs) المزيد من القوة لاستخدامها في شفرة جافاسكريبت. تُعرّف واجهات برمجة التطبيقات (APIs) على أنها مجموعات جاهزة من الشفرات البرمجيّة تسمح لمطور البرامج بتنفيذ برامج سيكون من الصعب أو المستحيل تنفيذها من دون استخدام واجهة برمجة التطبيقات. لأوضح لك الفكرة، تخيل أنك تريد عمل رف خشبي للكتب، سيكون الأمر أسهل بكثير لو توافرت لك الألواح الخشبية والمسامير بالمقاسات المناسبة وما عليك سوى تجميعها معًا لعمل رف الكتب. في حين سيكون الأمر أصعب بكثير لو توجّب عليك أنت العثور على الخشب المناسب وتقطيعه إلى الحجم والشكل الصحيح وإيجاد قياس المسامير المناسب ومن ثم تجميعها معًا لعمل رف الكتب. هذا ما تسهل عمله واجهات برمجة التطبيقات. تنقسم واجهات برمجة التطبيقات (APIs) عمومًا إلى فئتين. واجهات برمجة التطبيقات الخاصّة بالمتصفّح Browser APIs: تُدمَج واجهات برمجة تطبيقات في المتصفّح لإعطائه القدرة على عرض البيانات من بيئة الحاسوب المحيطة به، أو القيام بأشياء معقدة مفيدة. فمثلا: تسمح لك واجهة برمجة تطبيقات DOM وهي اختصار لـ Document Object Model بمعالجة HTML و CSS، إنشاء، إزالة وتغيير HTML ، تطبيق أنماط Styles جديدة ديناميكيًّا على صفحتك، وما إلى ذلك. في كل مرة تُعرَض فيها نافذة منبثقة تظهر على صفحة، أو يُعرَض محتوى جديد -كما رأينا أعلاه في مثالنا السابق- فواجهة DOM هي المسؤولة عن ذلك. تستعيد واجهة برمجة التطبيقات Geolocation API معلومات الموقع الجغرافي، ممّا يفسّر كيف يمكن لخرائط جوجل Google Maps أن تعثُر على موقعك الجغرافي وترسمه على الخريطة. تسمح لك واجهات برمجة تطبيقات اللوحة Canvas و WebGL بإنشاء رسومات متحركة ثنائية الأبعاد وثلاثية الأبعاد. يقوم الأشخاص بأشياء مدهشة باستخدام تقنيات الوِب هذه. تسمح لك واجهات برمجة التطبيقات الصوتية والمرئية مثل HTMLMediaElement و WebRTC بالقيام بأشياء مثيرة للاهتمام حقًا مع الوسائط المتعددة، مثل تشغيل الصوت والفيديو مباشرة في صفحة وِب أو التقاط الفيديو من كاميرا الوِب الخاصة بك وعرضها على جهاز كمبيوتر شخص آخر (جرب العرض التوضيحي snapshot) ملاحظة: لن تعمل العديد من العروض التوضيحية المذكورة أعلاه في متصفح أقدم. عند التجربة، من الأفضل استخدام متصفح حديث مثل فايرفوكس أو كروم أو Edge أو Opera لتشغيل الشفرة. واجهة برمجة التطبيقات الخاصّة بطرف ثالث Third party APIs. لا تُضمَّن هذه الواجهات في المتصفح مبدئيًّا. وعليك عمومًا الحصول على التعليمات البرمجية والمعلومات من مكان ما على الوِب. فمثلا: تتيح لك واجهة برمجة تطبيقات تويتر Twitter API إجراء أشياء مثل عرض أحدث التغريدات على موقعك الإلكتروني. تسمح لك واجهة برمجة التطبيقات لخرائط غوغل Google Maps API بتضمين الخرائط المخصصة في موقعك على الوِب، وغير ذلك من الوظائف. ملاحظة: واجهات برمجة التطبيقات هذه متقدمة، ولن يتم تغطية أي منها في هذه الدّروس، ولكن الروابط الواردة أعلاه توفّر وثائق شاملة إذا كنت مهتمًا بمعرفة المزيد. يوجد الكثير لتعلّمه، لا تفقد حماسك. دراسة جافاسكريبت لمدة 24 ساعة لن تعطيك القدرة على بناء فيسبوك، خرائط غوغل أو إنستغرام. هناك الكثير من الأساسيات التي يجب تغطيتها أولًا. وهذا هو السبب في أنك هنا. سنكمل في الدرس السابق حديثنا عن جافاسكريبت وستكون فرصة على للنظر الفعلي في شفرات برمجية. ترجمة - بتصرف - للمقال What is JavaScript? الذي اشترك في كتابته مساهمو موزيللا.

بدأنا في دروس سابقة بـإنشاء متجر إلكتروني على WooCommerce وقمنا بضبط إعدادات المتجر العامة General، إعدادات المنتجات Products، الضريبة Tax، الدفع Checkout، والشحن Shipping. سنغطي في هذا الدرس ما تبقّى من إعدادات المتجر والتي تتضمن إعدادات الحسابات Accounts، البريد الإلكتروني Email، والواجهة البرمجية API. إعدادات الحسابات من هذا التبويب تستطيع ضبط كيفيّة عمل حسابات عملائك. للوصول إلى هذه الإعدادات قم بتسجيل الدخول إلى موقعك ثم اذهب إلى: Dashboard > WooCommerce > Settings > Accounts يحتوي هذا التبويب على ثلاثة أقسام: Account Pages ومنه تقوم بإعداد صفحات الحسابات للعملاء: عندما تقوم بتثبيت WooCommerce سيقوم بإنشاء هذه الصفحة تلقائيًا، تأكّد من إبقاء الصفحة الافتراضية التي تم إنشاؤها، أو قم بإنشاء واحدة لكي يستطيع العميل استعراض الوظائف الخاصة بحسابه، كالطلبات، بالإضافة إلى تغيير تفاصيل الحساب عند الحاجة. My Account Endpoints Endpoints هي أجزاء من عنوان الصفحة URL، كصفحة My Account، تُلحق بذلك العنوان لمعالجة إجراءات معيّنة على الصفحة: إذا كنت تريد إنشاء Endpoints مخصّصة لعرض الطلب View Order، تعديل الحساب Edit Account، أو الإجراءات الأخرى، تأكّد من كون هذه الأجزاء فريدة ولا تظهر في عناوين الصفحات الأخرى على المتجر. وإلا ستعطل الروابط وستسبب مشاكل أخرى في صفحات حسابات العملاء. Registration Options من هذا القسم تتحكّم في خيارات التسجيل: بإمكانك تمكين التسجيل من على صفحة الدفع بتأشير الخيار Enable registration on the Checkout page، و/أو التسجيل من على صفحة "حسابي" Enable registration on the My Account page. هذه الخيارات مفيدة في حال كنت لا تسمح بإجراء الدفع من قبل زوار المتجر (غير المسجّلين)، ويتيح للعملاء الجدد سهولة التسجيل وإنشاء الحساب. من الخيارات الأخرى المفيدة هو Display returning customer login reminder on the Checkout page الذي يقوم بعرض تذكير بتسجيل الدخول للعملاء المتكررين على صفحة الدفع مما يتيح لهم سهولة الدخول إلى حساباتهم من على صفحة الدفع: وأخيرا من خيارات إنشاء الحساب Account Creation بإمكانك القيام بتوليد اسم مستخدم للعميل تلقائيًا من عنوان بريده الإلكتروني بتأشير الخيار Automatically generate username from customer email، وكذلك توليد كلمة سريّة لحساب العميل تلقائيًا بتأشير الخيار Automatically generate customer password، وسيتم إرسال تلك الكلمة السرية إلى عنوان البريد الإلكتروني الخاص بالعميل. انقر على Save Changes لحفظ التغييرات والانتقال إلى التبويب التالي. إعدادات البريد الإلكتروني توجد في هذا التبويب خيارات تعديل إعدادات البريد الإلكتروني والقوالب. للبدء بضبط الإعدادات اذهب إلى: Dashboard > WooCommerce > Settings > Emails يحتوي هذا التبويب أيضًا على ثلاثة أقسام: Email Notifications يحتوي هذا القسم على قائمة الإشعارات التي ستصلك (أو تُرسل للعميل) على البريد الإلكتروني والتي يمكنك تفعيلها أو إلغاء تفعيلها. ولكل رسالة إشعار، تستطيع تعديل بعض الخيارات مثل عنوان البريد الإلكتروني الذي سيُرسل إليه، عنوان الرسالة، إلخ: يمكن أن يقوم WooCommerce بإرسال إشعارات في الحالات التالية: الطلبات الجديدة New Order الطلبات الملغية Cancelled Order الطلبات الفاشلة Failed Order الطلبات الجارية Processing Order الطلبات المكتملة Completed Order الطلبات المستردّة Refunded Order فواتير العملاء Customer Invoice ملاحظات العملاء Customer Note استعادة الكلمة السرية Reset Password إنشاء حسابات جديدة New Account ملاحظة: الإشعارات الثلاثة الأولى تُرسل إلى عنوان البريد الإلكتروني الذي تحدده، أما الإشعارات المتبقية فتُرسل إلى العميل. يملك كل إشعار نفس الإعدادات تقريبًا، مع بعض الاختلافات التي سنأتي إلى ذكرها. بإمكانك الوصول إلى الإعدادات أما بالنقر على عنوان الإشعار في القائمة، أو النقر على أيقونة الترس المقابلة للعنوان في أقصى اليمين. لنبدأ بإعدادات إشعار New Order أولًا: الخيار الأول هو تفعيل/ إلغاء تفعيل هذا الإشعار بتأشير/إلغاء تأشير الخيار Enable this email notification. يفضّل معظم أصحاب المتاجر الإلكترونية استلام إشعار عن الحصول على طلب جديد، مع ذلك، الخيار راجع لك. في حقل (Recipient(s قم بإدخال عنوان/عناوين البريد الإلكتروني الذي تريد استلام الإشعار عليه. إذا قمت بإدخال أكثر من عنوان، تأكّد من فصلها بواسطة الفاصلة (,). في حقل Subject قم بإدخال عنوان الإشعار الذي سيصلك، بإمكانك استخدام العنوان الافتراضي الذي يحتوي على عنوان الموقع+ "New Customer Order"+ رقم الطلب+ تاريخ الطلب في نهايته: {site_title}] New customer order ({order_number}) - {order_date} أو بإمكانك إنشاء واحد مخصص بإدخال نص العنوان والتفاصيل الإضافية المرغوبة. من حقل Email Header يمكنك التحكم في العنوان الرئيسي لإشعار البريد الإلكتروني، ووظيفته تشبه وظيفة العنوان Subject. بإمكانك تركه فارغًا لاستخدام العنوان الرئيسي الافتراضي. لهذا الحقل المزيد من المعلومات التقنية التي سنتجاوزها لأنّها غير مهمة في هذا الدرس. من حقل Email Type يمكنك التحكّم في الصيغة التي سيرسل بها البريد الإلكتروني. الخيارات المتاحة هي Plain Text (نص عادي)، HTML، أو Multipart (أجزاء متعددة). أخيرًا، هناك خياران تحت حقل Email Type، وهما يعتمدان على صيغة البريد الإلكتروني التي اخترتها. الأول Copy file to theme والذي من خلاله تقوم بنسخ قالب البريد الإلكتروني الحالي إلى مجلد القوالب للقيام بتخصيصه أكثر ممّا توفّره هذه الإعدادات. إذا قمت بالفعل بنسخ مجلّد woocommerce/templates/emails بالكامل إلى مجلد القوالب، فلا حاجة إلى نسخ القوالب بشكل منفصل مجددا. وفي تلك الحالة ستجد زر Delete template file بدلًا من Copy file to theme. الخيار الثاني هو View template ويمكنك من خلاله عرض شيفرة قالب البريد الإلكتروني الحالي وستتمكّن من تعديل القالب إذا قمت بالفعل بنسخه إلى مجلد القوالب. وبالرغم من أننا لا ننصحك بتغيير شفرة القوالب مباشرة من هذه النافذة، لكن تأكّد من امتلاك نسخ احتياطية لهذه القوالب والنقر على Save Changes بعد الانتهاء من تخصيص الشفرة إذا قمت بتعديل القالب من ووردبريس. كما ذكرنا سابقًا، تحتوي بقية إعدادات إشعارات البريد الإلكتروني على نفس الحقول التي قم بشرحها في إعدادات New Order. هناك بعض الاستثناءات في إعدادات إشعار الطلبات المكتملة، الطلبات المستردّة، وفواتير العملاء. هناك حقلان إضافيان في إعدادات Completed Order: هذه الحقول خاصّة بعنوان الإشعار (Subject (downloadable والعنوان الرئيسي (Email Heading (downloadable للمنتجات الرقمية القابلة للتنزيل. وفي إعدادات Refunded Order، هناك حقلان للعنوان وحقلان للعنوان الرئيسي: الحقلان الأولان هما للطلبات المستردّة بشكل جزئي Partial Refund والآخران للطلبات المستردّة بشكل كلي Full Refund، مما يتيح لك مستوى تحكّم جيّد في النص المرسل إلى العميل في الحالتين، الاسترداد الجزئي، والاسترداد الكلي. أما إعدادات Customer Invoice فتحتوي على حقلين إضافيين، الأول لعنوان إشعار الفاتورة المدفوعة (Email Subject (paid والثاني للعنوان الرئيسي لإشعار الفاتورة المدفوعة (Email Heading (paid: بعد الانتهاء من ضبط إعدادات كل إشعار، انقر على Save Changes لحفظ التغييرات. Email Sender Options من خيارات مرسل البريد الإلكتروني يمكنك التحكّم في اسم المرسل من حقل "From" Name بالإضافة إلى عنوان البريد الإلكتروني للمرسل "From" Address. من المهم ضبط هذه الإعدادات لأنّها ستُعرض على العملاء في صندوق الوارد لبريدهم الإلكتروني: على سبيل المثال، من خلال الإعدادات أعلاه، سيستلم العميل بريد إلكتروني من المرسل "My Store" صاحب عنوان البريد الإلكتروني " example@gmail.com". Email Template من هذه الخيارات يمكنك تخصيص قالب البريد الإلكتروني الافتراضي الذي يستخدمه WooCommerce: بإمكانك إدخال رابط لصورة الترويسة في حقل Header Image، أو رفع صورة من خلال المسار: Dashboard > Media > Add New وكذلك بإمكانك تخصيص نص هامش القالب بإدخال النص المرغوب في حقل Footer Text وسيظهر هذا النص في الجزء السفلي من جميع رسائل البريد الإلكتروني التي ترسلها. بعد ذلك يمكنك اختيار لون الأساس Base Color، لون الخلفية Background Color، لون خلفية متن البريد الإلكتروني Body Background Color، وكذلك لون نص المتن Body Text Color. بإمكانك معاينة القالب أثناء تخصيصه بالنقر على رابط Click here to preview your email template. بإمكانك عمل المزيد من التخصيصات المعقّدة بنسخ قالب البريد الإلكتروني إلى مجلد القوالب. قم بنسخ مجلد emails من على الامتداد woocommerce/templates/emails ولصقه في مجلد قالبك على الامتداد "theme name"/woocommerce/emails. اعلم فقط أنّ ذلك سيؤدي إلى إلغاء أي تخصيص قمت به من إعدادات قالب البريد الإلكتروني Email Template المذكورة. بعد الانتهاء من ضبط جميع الاعدادات انقر على Save Changes لحفظ التغييرات. إعدادات API من هذا التبويب تستطيع تفعيل REST API، بالإضافة إلى إنشاء Keys و Webhooks لتطبيقاتك. للوصول إلى تبويب إعدادات API اذهب إلى Dashboard > WooCommerce > Settings > API يحتوي هذا التبويب على ثلاثة تبويبات فرعية: Settings من هذا التبويب تستطيع تفعيل/إلغاء تفعيل REST API بتأشير/إلغاء تأشير الخيار Enable the REST API: إنّ هذا الخيار ضروري لكي تعمل تطبيقات للهاتف المحمول في متجرك. فهو يتيح للتطبيقات الخارجية معرفة أشياء مثل حالة المخزون، الطلبات، معلومات المنتجات، وغيرها الكثير. يُعتبر RESU API من الأجزاء الفعّالة في WooCommerce ويمكن أن يحقق الكثير من الأشياء الرائعة. Keys/Apps يتيح لك هذا التبويب إدارة التحكّم في الوصول إلى REST API: ترتبط المفاتيح keys بالمستخدمين على موقعك. ولإنشاء مفتاح انقر على Add Key: في حقل User، قم بتحديد المستخدم الذي تريد توليد مفتاح له، ثم قم بإضافة وصف في حقل Description. من قائمة Permissions قم بتحديد مستوى الوصول لهذا المفتاح. الخيارات المتاحة هي Read (قراءة)، Write (كتابة)، أو Read/Write (قراءة/كتابة). بعد ذلك انقر على زر Generate API Key، وسيقوم WooCommerce بتوليد مفتاح API لذلك المستخدم. بعد توليد المفتاح ستلاحظ وجود مفتاح المستهلك Consumer Key، الرمز السري للمستهلك Consumer Secret، رمز QR، بالإضافة إلى زر إبطال المفتاح Revoke API Key: قم بوضع مفتاح المستهلك والرمز السري للمستهلك في التطبيق الذي يستخدم WooCommerce API. وكذلك يجب أن يطلب ذلك التطبيق عنوان URL لمتجرك. Webhooks Webhooks هي عبارة عن أداة يمكنك استخدامها لإرسال إشعار حول حدث ما إلى عنوان URL من اختيارك. على سبيل المثال عند إنشاء منتج جديد، أو إنشاء قسيمة جديدة. وهي توفّر طريقة سهلة للتكامل مع الخدمات الخارجية وAPI الخارجية الأخرى التي تدعم Webhooks: سنقوم بإنشاء Webhook وهمي لاستخدامه لنشر منشور على منصة تواصل اجتماعي من اختيارنا عندما نقوم بإنشاء منتج جديد. وهذه من الطرق البسيطة للترويج لمنتجاتنا الجديدة عبر الإنترنت بصورة تلقائية. انقر على زر Add Webhook: قم بإدخال عنوان مناسب في حقل Title ثم حدّد الحالة من قائمة Status حسب حاجتك. خيارات الحالة المتوفّرة هي Active (مفعّل)، Paused (متوقف مؤقتًا)، أو Disabled (غير مفعّل). إذا رغبت في تشغيل Webhook تأكّد من اختيار الحالة Active. الخطوة التالية هي تحديد الموضوع من قائمة Topic، ويقصد به الحدث الذي سيشغّل Webhook. تتضمن القائمة العديد من الخيارات، مثل إنشاء طلب Order Created، حذف منتج Product Deleted، أو تحديث عميل Customer Updated. وكذلك يوجد خيار تحديد موضوع مخصص Custom لغرض إنشاء Webhook أكثر تقدّمًا. سنحدد Product Created مثلا. الحقل التالي هو Delivery URL ويُستخدم لتحديد العنوان الذي سيتم توصيل حمل Webhook إليه. في مثالنا هذا سنبحث في توثيق المطوّرين لمنصة التواصل الاجتماعي التي اخترناها للعثور على Webhook يمكننا استخدامه للتوصيل. في حقل Secret قم بإعداد مفتاح سرّي يدويًا، أو اترك الحقل فارغًا وسيتم استخدام مفتاح Consumer Secret للمستخدم الحالي والذي يوجد في قسم API لحساب المستخدم على WooCommerce. بعد الانتهاء من ضبط الإعدادات أعلاه، انقر على Save Webhook لبدء تشغيله ورصد المنتجات الجديدة. عندما يُشغّل Webhook بإمكانك العودة إلى هذه النافذة لمشاهدة التسجيلات في قسم Webhook Logs. إذ ستكون هناك مدخلات تبيّن وقت تشغيله وما هي استجابات الخدمات الأخرى التي تتكامل معها. وهذه التسجيلات توفّر لك طريقة سهلة لاختبار Webhook وإصلاحه. لن نكون قادرين على تغطية جميع التفاصيل التقنية المتعلّقة بالتكامل مع الخدمات الأخرى، لأنها ستكون معقّدة جدًا بالنسبة لغرض هذا الدرس. بهذا تكون قد تمكّنت من ضبط جميع إعدادات متجرك الإلكتروني على WooCommerce. سنغطّي في الدرس القادم -إن شاء الله- كيفية إنشاء المنتجات وسنلقي نظرة عامة على أنواعها.

لطالما وفّر إطار العمل Laravel آليات سهلة للاستيثاق Authentication بالطرق التقليدية مثل استمارات Forms تسجيل الدخول في واجهة الوِب؛ إلا أن الأمر لم يكن سهلا بما فيه الكفاية بالنسبة للاستيثاق من الطلبات القادمة عبر واجهة تطبيقات برمجية. يأتي الإصدار 5.3 بحزمة جديدة، تُسمّى Passport، تهتم بتيسير استخدام Laravel لضبط خادوم Oauth وإعداده. يتناول هذا الدرس كيفية إعداد Laravel ليوفّر وظيفة خادوم Oauth اعتمادا على حزمة Passport. خادوم Oauth من المحتمل جدّا أنه سبق لك التعامل مع خادوم Oauth؛ مثلا عند استخدام حسابات على الشبكات الاجتماعية (فيس بوك، تويتر، … إلخ) للتسجيل في موقع على الشبكة. الفكرة التي تنبني عليها آلية الاستيثاق هذه هي تفويض عمليّة الاستيثاق إلى خادوم Oauth. نفترض مثلا أن لديك موقعا يستخدم هذه الآلية؛ عند تسجيل دخول الموقع عن طريق الحساب على فيس بوك فإن ما يحدُث هو التالي: يلج المستخدم إلى الموقع ويختار طريقة تسجيل الدخول (فيس بوك). يُنقَل المستخدم إلى صفحة تسجيل الدخول في فيس بوك حيثُ يُطلَب منه تسجيل الدخول إن لم يكن سبق له ذلك ثم يؤكّد سماحه لموقعك باستخدام حسابه على فيس بوك. يُعاد توجيه المستخدم إلى الموقع مع تسجيل دخوله إليه. يفترض هذا الدرس أن لديك إلماما بكيفية عمل خواديم Oauth للتصريح بالدخول. يمكن الاطّلاع على مقال مدخل إلى OAuth 2 للمزيد عن هذا الموضوع. إن كنتَ تبحث عن كيفية تسجيل الدخول إلى تطبيقك باستخدام حساب على موقع يوفّر وظيفة Oauth فراجع درس تسجيل الدخول عبر الشبكات الاجتماعية في Laravel باستخدام Socialite. إعداد خادوم Oauth على Laravel 5.3 يحتاج إعداد Passport على Laravel لتنفيذ بضعة أوامر وتحرير ملفات إعداد؛ إلا أن العملية عموما سهلة. ابدأ بتثبيت الإصدار 5.3 من Laravel: composer create-project --prefer-dist laravel/laravel laravel53oauth "5.3.*" نستخدم composer لإضافة حزمة Passport إلى متطلبات المشروع: composer require laravel/passport نسجّل مزوّد الخدمة Passport في ملفّ الإعداد config/app.php. افتح الملف ثم أضف السطر التالي إلى مصفوفة providers: Laravel\Passport\PassportServiceProvider::class, تأكّد من إعدادات قاعدة البيانات ثمّ نفّذ أمر التهجير Migration التالي: php artisan migrate ستلاحظ تنفيذ تهجيرات إضافية علاوة على تلك التي تأتي مبدئيّا مع Laravel: Migration table created successfully. Migrated: 2014_10_12_000000_create_users_table Migrated: 2014_10_12_100000_create_password_resets_table Migrated: 2016_06_01_000001_create_oauth_auth_codes_table Migrated: 2016_06_01_000002_create_oauth_access_tokens_table Migrated: 2016_06_01_000003_create_oauth_refresh_tokens_table Migrated: 2016_06_01_000004_create_oauth_clients_table Migrated: 2016_06_01_000005_create_oauth_personal_access_clients_table يأتي مزوّد الخدمة Passport مع تهجيرات لإنشاء جداول تخزّن عملاء Client التطبيق ومعلومات رموز الوصول Access tokens. ثم ننفّذ الأمر التالي الذي سيولّد مفاتيح التعميّة Encryption keys الخاصّة بمشروع كما أنه ينشئ رموز الوصول ويخزّنها في جدول البيانات المناسب: php artisan passport:install ننتقل الآن إلى نموذج المستخدم User ونضيف إليه السّمة Trait المسمّاة HasApiTokens. يُصبح النموذج على النحو التالي (بعد نزع التعليقات للاختصار): <?php namespace App; use Illuminate\Notifications\Notifiable; use Illuminate\Foundation\Auth\User as Authenticatable; // استيراد السّمة use Laravel\Passport\HasApiTokens; class User extends Authenticatable { // استخدام السمة use HasApiTokens, Notifiable; protected $fillable = [ 'name', 'email', 'password', ]; protected $hidden = [ 'password', 'remember_token', ]; } توفّر هذه السّمة مجموعة من الدوال المساعدة التي تتيح الحصول على رموز الوصول الخاصّة بالمستخدمين ومدى الصلاحيّات Permissions scope المتاح للعميل. الخطوة المواليّة هي استدعاء الدالة Passport::routes ضمن الدالة boot الموجودة في مزوّد خدمة الاستيثاق app/Providers/AuthServiceProvider.php: public function boot() { $this->registerPolicies(); Passport::routes(); } لا تنس استدعاء الصنف Laravel\Passport\Passport في مزوّد خدمة الاستيثاق: use Laravel\Passport\Passport; يمكنك ملاحظة المسارات الجديدة التي أضافتها الدالة Passport::routes بتنفيذ أمر Artisan التالي الذي يسرُد لائحة بالمسارات الموجودة في المشروع: php artisan route:list الخطوة الأخيرة هي تعديل ملف الإعداد config/auth.php وتحديد قيمة driver في المصفوفة api لتصبح passport بدلا من token: 'api' => [ 'driver' => 'passport', 'provider' => 'users', ], يعتمد Laravel مبدئيا على رموز للاستيثاق من الطلبات القادمة عبر واجهة التطبيقات البرمجية؛ إلا أن هذه الرموز المبدئية لا تتيح إلا القليل من الخيارات، عكس ما يوفّره Passport. بهذا نكون أنهينا إعداد Laravel لأداء وظيفة خادوم Oauth. اختبار خادوم Oauth المرحلة المواليّة بعد إعداد Laravel ليعمل خادوم Oauth هي اختبار ما أعددناه. سنحتاج لعميل نجرّب عن طريقه الاستيثاق من الخادوم. نعيد النظر، قبل الانتقال للجانب التطبيقي من الاختبار، في كيفية الاستيثاق من مستخدم في خادوم Oauth. تضمّ العمليّة ثلاثة أطراف: المستخدِم، الخادوم والعميل. يريد المستخدِم تسجيل الدخول إلى العميل بالاعتماد على معلوماته الموجودة في الخادوم: ينقُل العميل المستخدِم إلى صفحة تسجيل الدخول على الخادوم. يُسجّل المستخدم الدخول إلى حسابه على الخادوم عن طريق بريده الإلكتروني وكلمة السّر. يتحقّق الخادوم من بيانات المستخدِم، ثم ينشئ - إذا كانت البيانات صحيحة - رمز وصول خاصًّا بالمستخدِم ويعيده إلى العميل. يستعمل العميل رمز الوصول الذي أرسله إليه الخادوم في طلباته المقبلة للتدليل على أن المستخدم فوّضه التعامل باسمه مع الخادوم. إنشاء مستخدمين للاختبار نبدأ بإنشاء مستخدمين لتجربة الاستيثاق. ننفذ أمر Artisan التالي لإنشاء صنف بذر Seed جديد: php artisan make:seeder UsersTableSeeder ثم نعدّل الدالة run لإنشاء مستخدمَيْن جديديْن: public function run() { $user1 = [ 'name' => 'Med Ahmed Eyil', 'email' => 'medeyil@laravel.com', 'password' => Hash::make('1234'), ]; $user2 = [ 'name' => 'Fatima Benziane', 'email' => 'fbenziane@laravel.com', 'password' => Hash::make('4567'), ]; User::create($user1); User::create($user2); } لا تنس استيراد النموذج User: use App\User; ثم نعتمد صنف البذر بتعديل الدالة run في الصنف DatabaseSeeder: public function run() { $this->call(UsersTableSeeder::class); } ثم ننفذ أمر البذر: php artisan db:seed جهّزنا الآن طرفيْن من الأطراف الثلاثة التي تحدثنا عنها، بقي العميل. إعداد العميل يوفّر Laravel بواسطة Passport مسارات من بينها المسار oauth/token/ الذي يمكّن من الحصول على رمز وصول. ينتظر المسار المعطيَات التاليّة: طريقة منح الصلاحيّة grant_type. معرّف المستخدم client_id. عبارة سر العميل client_secret. يحدّد المعطى grant_type طريقةَ توليد رموز الوصول. بما أننا نريد أن يطلُب الخادوم من المستخدم بريده الإلكتروني وكلمة السّر لكي يولّد رمز وصول للتطبيق العميل، فإن هذا المعطى سيأخذ القيمة password. يمكن لهذا المعطى أن يأخذ قيما أخرى حسب الطريقة التي تريد للتطبيقات العميلة أن تصل بها إلى موارد محميّة على خادومك. يعيّن المعطى الثاني معرّف العميل الذي نريد الاستيثاق منه؛ أما عبارة السّر فمهمتها إثبات أن العميل لديه ترخيص للاستيثاق بخادوم Oauth الذي أعددناه. سنحتاج أيضا لتمرير بريد المستخدم الإلكتروني وكلمة سره، بما أننا اخترنا طريقة password لتوليد الرموز. نعود لمشروع Laravel حيث يوجد الخادوم ثم ننفذ الأمر التالي: php artisan passport:client --password What should we name the password grant client? [Laravel Password Grant Client]: > Academy Password Client Password grant client created successfully. Client ID: 3 Client Secret: 17ZNjWn5A1I3mYOhGXZQFNACTdyt9Nwxup9jXG4M يطلُب الأمر أعلاه إنشاء تصريح لعميل للاستيثاق بخادوم Oauth ويحدّد طريقة توليد رموز الوصول بـpassword. يطلُب الأمر اسمًا للعميل ثم بعد كتابته وتأكيده يمنحنا معرّفا للعميل وعبارة سرّ. ملحوظة: رمز الوصول المولَّد فريد Unique، القيمة التي ستظهر لديك مختلفة حتما عن القيمة الظاهرة هنا. نعرّج قليلا، قبل الانتقال إلى العميل، على قاعدة البيانات وننظر في الجدول oauth_clients. لاحظ في الجدول وجود العميل الذي أنشأناه للتو، إضافة إلى عميليْن آخرين؛ أنشأهما الأمر passport:install عندما نفّذناه. تمكن ملاحظة أن قيمة العمود password_client بالنسبة للعميل الذي أنشأناه هي 1 للدلالة على أنه من نوع password. نأتي الآن للعميل، الذي يمكن أن يكون تطبيق وِب، تطبيقا للأجهزة المحمولة أو غيره. بالنسبة لي سأختار إضافة Postman على متصفح Chrome، وهي إضافة تمكّن من اختبار واجهات التطبيقات البرمجية. إرسال الطلبات نشغّل خادوم Passport بتنفيذ الأمر: php artisan serve ثم نفتح واجهة Postman ونعطيه المسار oauth/token/ ونمرّر له المعطيات التي تحدّثنا عنها سابقا. نحدّد نوع الإجراء بـ POST، ونختار تبويب Body لأننا في صدد ذكر بيانات جسم الطلب، ونختار x-www-form-urlencode للترميز. يؤدي استخدام الترميز x-www-form-urlencode إلى إرسال البيانات بنفس الطريقة التي تُرسَل بها بيانات استمارة Form على موقع وِب باستخدام الإجراء POST. إن كنتَ تُفضّل سطر الأوامر فبإمكانك تنفيذ أمر curl التالي والذي يؤدي نفس المهمّة (الخيار d- لاستخدام الترميز x-www-form-urlencode): curl -d "grant_type=password&client_id=3&client_secret=17ZNjWn5A1I3mYOhGXZQFNACTdyt9Nwxup9jXG4M&username=medeyil@laravel.com&password=1234" http://localhost:8000/oauth/token نحصُل بعد ذكر المعطيات الصحيحة وتنفيذ الطلب على الرد التالي: { "token_type": "Bearer", "expires_in": 31536000, "access_token":"رمز طويل هنا" , "refresh_token": "رمز طويل هنا" } تتضمن الإجابة أربعة حقول: نوعية الرمز token_type. يعني النوع bearer أن بإمكان الرمز منح الوصول إلى الخادوم دون الحاجة لذكر معلومات إضافية (مثل مفاتيح التعمية). مدة صلاحيّة الرمز expires_in. يحدّد مدّة صلاحيّة الرمز، بالثواني. يحدّد Laravel مبدئيا مدة طويلة (حوالي سنة)؛ إلا أنه يمكن تغيير هذه المدة. رمز الوصول access_token. رمز التحديث refresh_token. يُستخدَم لطلب رمز وصول جديد عند انتهاء مدة صلاحية رمز الوصول الحالي. حصلنا على رمز الوصول؛ سنرى الآن كيفية استخدامه للوصول إلى موارد على الخادوم. يُرسِل العميل من الآن فصاعدا رمزَ الوصول الذي حصل عليه مع كل طلب موجّه للخادوم يحتاج للاستيثاق. إن نظرت في ملفّ مسارات واجهة التطبيقات البرمجية routes/api.php فستجد أن المسار user/ محميّ بـ auth:api: Route::get('/user', function (Request $request) { return $request->user(); })->middleware('auth:api'); يعني هذا أنه يتوجّب على المستخدم تقديم بيانات الاستيثاق الخاصّة بواجهة التطبيقات، التي جعلناها تعتمد على التعريف passport، حتى يتمكن من الحصول على المورِد (الذي هو في المثال أعلاه بيانات المستخدم الذي أرسل الطلب). نعود لـPostman لطلب المسار api/user/ مع تقديم رمز الوصول الذي حصلنا عليه سابقا. ملحوظة: تنبغي إضافة api/ إلى جميع المسارات المعرّفة في الملف routes/api.php. نحدّد في خانة الترويسة Headers طبيعة المعلومات التي نريد تقديمها إلى المسار والإجراء GET المعرَّف في المسار user/ الخاص بواجهة التطبيقات. الترويسة التي نريد تحديد قيمتها هي Authorization (طلب استيثاق) وقيمتها هي: Bearer access_token حيث access_token رمز الوصول الذي حصلنا عليه في الخطوة السابقة، مسبوقا بنوع الرمز (Bearer). نحصُل على معلومات المستخدِم الذي قدّم الطلب. يمكن الحصول على نفس النتيجة بأمر curl التالي: curl -H "Authorization: Bearer access_token" http://localhost:8000/api/user يعني الخيار H- أننا نريد تضمين الترويسة التاليّة له في الطلب. نلاحظ أن الإجابات التي نحصُل عليها من خادوم Passport مهيّأة بصيغة JSON، وهو ما يجعل التعامل معها سهلا في التطبيقات العميلة على الأجهزة المحمولة والمتصفّحات. الخلاصة هي أننا استخدمنا بيانات المستخدم (البريد وكلمة السر) للحصول على رمز وصول من خادوم Passport ثم استخدمنا رمز الوصول هذا للاطلاع على موارد محميّة على الخادوم.

أصبحت واجهات REST البرمجية أكثر انتشارًا بين المطوّرين، نظرًا لأنها توفّر واجهة بسيطة، موحّدة وواضحة لخدمات الطرف الثالث third-party مثل Twitter، MailChimp وGitHub. ومع ازدياد شهرة واجهة ووردبريس البرمجية (المتوفرة عبر إضافة) فإن الوقت قد حان لنتعلم حول واجهة HTTP البرمجية في ووردبريس، وكيفية عملها واستخداماتها. ما هي واجهة HTTP في ووردبريس؟ لن يكون من المستغرب القول بأنها طريقة لإرسال واستقبال الرسائل بواسطة HTTP – لغة شبكة الويب. حيث يقوم المتصفح بإرسال واستقبال الرسائل طوال الوقت وبهذا الشكل يتم استقبال صفحات الويب. ويمكن من خلال واجهة REST البرمجية، يمكن باستخدام رسائل HTTP القيام بأشياء أكثر كتعديل منشور، حذف حساب مستخدم أو نشر وصفة جديدة على موقعك. لهذا السبب تعتبر واجهة ووردبريس البرمجية مهمة جدًا، فهي تسمح بفصل التطبيق من جهة المستخدم عن النواة البرمجية الخاصة بووردبريس. ولاستخدامها، تحتاج أن تكون معتادًا على إرسال طلبات HTTP واستقبال الأجوبة، وهذا هو أساس عمل واجهة HTTP البرمجية. وهناك العديد من الطرق لإرسال طلبات HTTP، حيث توفّر واجهة HTTP البرمجية طريقة موحّدة باستخدام مجموعة من التوابع المساعدة والتي سنطّلع عليها بعد قليل. طرق HTTP ومصادرها ترتكز HTTP حول الطرق methods (تسمّى أحيانًا بالأفعال verbs) والمصادر resources. تحدّد المصادر العنصر الذي سيتم تنفيذ العملية عليه، وتحدّد الطريقة نوع العملية التي سيتم تنفيذها. ويعتبر العنوان URL هو المصدر الذي يشير إلى الغرض على شبكة الويب، كمنشور على سبيل المثال. وتوجد العديد من الطرق، لكن الأهم فيها هي GET, POST, PUT و DELETE. ولا بد أن لديك الكثير من الخبرة مع GET فهذه الطريقة هي المستخدمة في الحصول على المصادر، فمثلًا عند استعراض مقال في المتصفح يتم إرسال طلب GET إلى عنوان المقال وليكن مثلًا https://premium.wpmudev.org/blog/using-the-wordpress-http-api/. أما طلبات PUT فتستخدم لتعديل المصادر، وتستخدم طلبات POST لإنشاء مصادر جديدة، وتستخدم طلبات DELETE لحذف مصادر موجودة مسبقًا. ولو كان لدى موقع WPMU DEV واجهة REST برمجية، فربما كان من الممكن أن يقوم المدير بإرسال طلب DELETE لحذف المقال على الرابط https://premium.wpmudev.org/blog/wordpress-http-api، وهذا الأمر مفيد جدًا للمواقع الكبيرة التي تملك برامج إدارة على الهواتف الذكية. مثال عن طلب HTTP بسيط للقيام بإرسال طلب GET بسيط على سبيل التجربة، سنقوم باستخدام التابع wp_remote_get() الذي يملك مُعاملين، المُعامل الأول هو رابط المصدر، والمُعامل الثاني هو مصفوفة اختيارية optional من الخيارات التي من الممكن استخدامها لتحديد بعض التفاصيل. $test = wp_remote_get( 'http://google.com' ); echo "<pre>"; var_dump($test); echo "</pre>"; يقوم المثال السابق بجلب الصفحة الرئيسية لموقع جوجل، ومن ثم يتم طباعة محتوى المتغير test الذي يحوي على جواب الطلب الذي أرسله موقع جوجل – حيث يمكن رؤية جميع العناصر التي يحتويها. تحتوي الترويسات headers على المزيد من المعلومات عن كل رسالة. وقد تطلب منك بعض واجهات REST البرمجية أن تقوم بإرسال معلومات محددة في الترويسات عندما ترسل الطلب. يحتوي الجواب response على رمز الحالة status code وعبارة قد تكون معروفة بالنسبة لك كأخطاء 404، أو خطأ في معالجة الطلب 500 أو تحويل من النوع 301 أو 302. يحتوي موقع W3.org على جميع رموز أخطاء HTTP المعرّفة والمشروحة، ويعتبر مصدرًا مفيدًا إن احتجت أن تعرف ما يعني أي خطأ. بإمكانك أيضا الاطّلاع على هذا المقال على أكاديمية حسوب لتعرف المزيد حول هذه الرّموز: رموز الإجابة في HTTP يحتوي الجسم body على الجواب وهو المكان الذي تحتاج أن تنظر إليه بحثًا عن النتيجة المطلوبة. في حالة المثال السابق، فإننا نحصل على وسوم HTML التي تشكّل الصفحة الرئيسية، ولكن عند التعامل مع واجهات REST البرمجية فمن الشائع أن نحصل على نص بصيغة JSON. وعادة ما تطلب الواجهات البرمجية APIs أن يتم إضافة نص محدّد إلى الجسم عند إرسال طلبات أيضًا. يحتوي قسم cookies على أي كعكات تم استلامها مع الرسالة. كما ترى، فإن إرسال طلب باستخدام واجهة HTTP البرمجية أمر بسيط جدًا. ما يجعل العمل مع HTTP معقّد نوعًا ما هو أن واجهات REST البرمجية قد تكون حساسة جدًا لصيغة البيانات المدخلة (وهو أمر جيّد) لذا فإن تجاوزت سطرًا عند دراسة توثيق الواجهة البرمجية قد ينتهي بك الأمر ببرمجية لا تعمل كما ترغب. العمل مع الواجهات البرمجية أعتقد بأنه من الآمن القول بأن معظمكم سيستخدم HTTP للتعامل مع واجهات REST البرمجية في شبكة الويب، وفي هذه الحالة سنحتاج لاستخدام المعامل الثاني لتحديد بعض الأمور، كالاستيثاق وتجنب بعض الأخطاء الشائعة. لنبدأ بمثال بسيط – استعادة البيانات من لوحة Pinterest. تتطلب جميع الواجهات البرمجية الجيّدة تنفيذ عملية استيثاق للتعريف عن المستخدم الذي يرسل الطلب، لكنّنا سنغش قليلًا في هذا المثال باستخدام مولّد رموز الأمان الخاص بـ Pinterest. بعد إكمال الاستيثاق ستحصل على رمز أمان يمكن استخدامه في المثال التالي، حيث سنقوم بإنشاء طلب لجلب وعرض قائمة بمنشورات Pinterest. $request = wp_remote_get( 'https://api.pinterest.com/v1/boards/marticz/home-office/pins/?access_token=<your access token>' ); $pins = json_decode( $request['body'], true ); if( !empty( $pins['data'] ) ) { echo '<ul>'; foreach( $pins['data'] as $pin ) { echo '<li><a href="' . $pin['url'] . '">' . $pin['note']. '</a></li>'; } echo '</ul>'; } لو قمنا بنسخ المثال السابق ولصقه في صفحة content-page.php في قالب Twenty Fifteen لتجربته فإن النتيجة هو الحصول على لائحة بالمنشورات من لوحة Pinterest حول المكاتب الشخصية في المنزل. لا تنس أن تستبدل <your access token> في المثال السابق برمز الأمان الذي حصلت عليه. يقوم السطر الثاني في المثال بفك ترميز جسم الجواب من JSON إلى شكله الأساسي كمصفوفة ونقوم بإنشاء حلقة loop تقوم بطباعة محتوى عنصر المصفوفة $pins['data']. الاستيثاق يقع العديد من الأشخاص في عثرات في هذه المرحلة لأنها تتطلب خطوة إضافية على الأقل وربما بعض الترويسات الإضافية أيضًا. ولننظر إلى واجهة تويتر البرمجية على سبيل المثال، وتحديدًا إلى الاستيثاق الخاص بالتطبيقات، الذي يمكنك استخدامه لاستيثاق تطبيقك مع تويتر. قراءة التوثيق إن أول خطأ قد يتم ارتكابه هو عدم قراءة التوثيق بشكل جيّد. ولو كنت مبرمجًا متمرسًا في واجهات REST البرمجية فيمكنك القفز مباشرة إلى الجزء حول الاستيثاق، ولو فعلت هذا فقد لا تنتبه إلى سطر يقول: وإهمال هذا الشرط سيؤدي إلى فشل حتمًا في الحصول على نتيجة، على الرغم من أن كل شيء آخر مطبّق بشكل كامل، لذا حتى توفّر على نفسك الحاجة لمراجعة شفرة برنامجك، تأكد من قراءة التوثيق بشكل جيّد وكامل. إضافة ترويسات ومعاملات أخرى بعد اتباع التوجيهات في التوثيق حرفيًّا، قمت بإنشاء طلب POST، ينبغي أن يؤدي إلى توليد رمز أمان للوصول من أجلي، ويبدو الكود على الشكل: $key = base64_encode( urlencode( "n8KP16uvGZA6xvFTtb8IAA:i4pmOV0duXJv7TyF5IvyFdh5wDIqfJOovKjs92ei878" ) ); $request = wp_remote_post('https://api.twitter.com/oauth2/token', array( 'headers' => array( 'Authorization' => 'Basic ' . $key, 'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8' ), 'body' => 'grant_type=client_credentials', 'httpversion' => '1.1' )); $token = json_decode( $request['body'] ); echo "<pre>"; var_dump($token); echo "</pre>"; إن الخطوة الأولى هو ترميز رمز أمان الوصول والكلمة السرّية بصيغة URL encoding. قمت أيضًا بإضافة ترويستين، واحدة ترويسة استيثاق تحوي على بيانات الوصول. أما الترويسة الثانية فهي ترويسة نوع المحتوى content type، والتي يطلب توثيق تويتر إضافتها. إضافة لما سبق، قمت بملء جسم الطلب تمامًا كما ذكرت الملاحظة السابقة حول grant_type=client_credentials وتم إضافة إصدار HTTP كما يطلب توثيق تويتر أيضًا. سيحتوي الجواب بالإضافة للعديد من المعلومات الأخرى على رمز أمان الوصول في جسم الجواب، وسنحتاج لرمز الأمان هذا في جميع الطلبات اللاحقة المرسلة إلى الواجهة البرمجية الخاصة بتويتر. تخزين رمز أمان الوصول إن رمز الأمان صالح لبعض الوقت، ويعتبر طلبه مجدّدًا هدرًا غير ضروري عند تحميل كل صفحة أو عندما يحتاج تطبيقك أن يقوم بعملية ما وسيؤدي إلى استهلاك عدد الطلبات المسموح بسرعة. يمكن في ووردبريس استخدام عابرة transient لتخزين قيمة رمز الأمان ومن ثم استخدام العابرة عند كل طلب لاحق للواجهة البرمجية. $token = get_transient( 'twitter_access_token' ); $token = ( empty( $token ) ) ? get_twitter_access_token() : $token; $request = wp_remote_get('https://api.twitter.com/1.1/followers/ids.json?screen_name=danielpataki&count=5', array( 'headers' => array( 'Authorization' => 'Bearer ' . $token, 'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8' ), 'httpversion' => '1.1' )); $token = json_decode( $request['body'] ); سيؤدي إرسال الطلب السابق إلى واجهة تويتر البرمجية إلى عرض 5 من متابعيّ على تويتر (قائمة بسيطة لأرقام حساباتهم Ids). وكما يظهر في المثال السابق، فإنني أقوم بجلب القيمة التي خزّنتها في العابرة فإن لم تكن موجودة سأقوم باستدعاء التابع get_twitter_access_token() للحصول على رمز أمان جديد ومن ثم إضافته إلى العابرة كي أستخدمه في الطلبات اللاحقة. تجدر الإشارة إلى أن هذه الطريقة تهدف فقط إلى إظهار آلية التنفيذ وليست أفضل طريقة للتنفيذ، وكسيناريو أبسط كنت لأقوم بوضع جميع العبارات الشرطية IFs داخل التابع get_twitter_access_token() الذي سيقوم بتنفيذ جميع الشيفرة السابقة ضمنيًا. التوابع المساعدة في واجهة HTTP البرمجية الآن وبعد أن حصلنا على لمحة جيدة حول هدف المقال، دعونا نلق نظرة على التوابع التي ستساعدك في واجهة HTTP البرمجية في ووردبريس. هناك 4 توابع يمكن بواسطتها تنفيذ طلبات: wp_remote_get() wp_remote_post() wp_remote_head() wp_remote_request() ومن الواضح تمامًا وظيفة كل تابع، أما التابع الأخير wp_remote_request() فهو تابع عام يمكنك استخدامه مع أي طريقة HTTP method. أما التوابع الخمسة التالية فتسمح لك بالحصول على جواب على الطلب بسهولة باستخدام توابع قياسية عوضًا عن الخوض في التعامل مع المصفوفات وعناصرها. wp_remote_retrieve_body() wp_remote_retrieve_header() wp_remote_retrieve_headers() wp_remote_retrieve_response_code() wp_remote_retrieve_response_message() أيضًا يبين اسم كل تابع الهدف الوظيفي له بسهولة، وينصح عند الإمكان باستخدام هذه التوابع عوضًا عن التعامل مع المصفوفات يدويًا، حيث ستسمح هذه الطريقة الموحّدة لمطوّرين آخرين بفهم البرمجية بسهولة واستخدام الخطافات hooks إن أصبحت متاحة في المستقبل. الخلاصة كما ترى فإن التعامل مع واجهة REST البرمجية سهل باستخدام واجهة HTTP البرمجية في ووردبريس وبعض توابع ووردبريس كالعبّارات. أنصح بشدّة تجربة هذا الأمر لأن عملية التطوير في ووردبريس تسير بثقة باتجاه العالم المُقاد باستخدام الواجهات البرمجية وعليك أن تقفز إلى الموكب قبل فوات الأوان. إن كان لديك المزيد من الأسئلة حول استخدام واجهة HTTP البرمجية أو لديك بعض الأفكار حول كيفية استخدامها، فلا تتردد بمناقشة الأمر في قسم التعليقات في الأسفل. ترجمة -وبتصرّف- للمقال How to Use the WordPress HTTP API لصاحبه Daniel Pataki.

تعرفنا في الدرسين الماضيين عن مفهوم حاويات لينكس (LXC) ومبدأ عملها ثم شرعنا في كيفية البدء في استعمالها. سنعرج في هذا الدرس إلى كيفية استغلال مختلف نقاط ومراحل دورة حياة حاويات لينكس (LXC) لإدراج بعض من الإضافات (hooks) التي تقوم بإجراء مهمة ما. إضافات إدارة دورة التشغيل بدءًا من أوبنتو 12.10، أصبح من الممكن تعريف إضافات (hooks) تُنفَّذ عند نقاط محددة من دورة تشغيل الحاوية: الإضافات التي تحدث قبل التشغيل تُنفَّذ من مجال أسماء المضيف قبل أن تُنشَأ طرفيات أو نقاط وصل الحاويات؛ إذا أُجري أي وصل في هذه الفترة، فيجب أن يُنظَّف في إضافة تحدث بعد إيقاف التشغيل. الإضافات التي تحدث قبل الوصل تُنفَّذ في مجال أسماء الحاوية، لكن قبل أن يوصل جذر نظام الملفات؛ سينظف أي وصل لنظام الملفات في هذه الفترة تلقائيًا عند إيقاف تشغيل الحاوية. إضافات الوصل هي إضافات تنفذ بعد وصل أنظمة ملفات الحاوية، لكن قبل أن تُنفِّذ الحاوية pivot_root لتغيير جذر نظام ملفاتها. الإضافات التي تحدث بعد إيقاف التشغيل ستنفَّذ بعد إيقاف تشغيل الحاوية. إذا أعادت أيّة إضافة خطأً، فسيلغى تشغيل الحاوية، لكن أي إضافة تحدث بعد إيقاف التشغيل ستنفَّذ، ستُسجَّل أيّة مخرجات تولد من السكربت بأولوية التنقيح (debug). رجاءً راجع صفحة دليل lxc.container.conf لصيغة ملف الضبط التي سيحدد الإضافات؛ يمكن أن تأتي بعض أمثلة الإضافات في الحزمة lxc لتخدم كمثال حول طريقة كتابة إحدى تلك الإضافات. سطر الأوامر لدى الحاويات عدد مضبوط من «أسطر الأوامر» (consoles)؛ أحدها موجودٌ دائمًا في ‎/dev/console؛ الذي يظهر في الطرفية عندما تُشغِّل lxc-start ما لم تحدد الخيار ‎-d؛ يمكن إعادة توجيه ناتج خرج ‎/dev/console إلى ملف باستخدام ‎-c console-file في الأمر lxc-start؛ يمكن تحديد عدد إضافي من أسطر الأوامر باستخدام المتغير lxc.tty المضبوط عادةً إلى 4؛ يمكن أن تظهر أسطر الأوامر تلك في ‎/dev/ttyN (حيث N أكبر أو تساوي 1، وأصغر أو تساوي 4)؛ ولتسجيل الدخول إلى console 3 من المضيف، فنفِّذ الأمر: sudo lxc-console -n container -t 3 إذا لم تحدد الخيار ‎-t N، فسيتم اختيار سطر أوامر غير مُستخدَم؛ للخروج منه، استخدام عبارة الخروج Ctrl-a q؛ لاحظ أن عبارة الخروج لا تعمل في سطر الأوامر الناتج عن lxc-start دون الخيار ‎-d. استكشاف الأخطاء التسجيل إذا حدث شيء ما خاطئ عند تشغيل حاوية، فإن أول خطوة هي الحصول على سجل كامل من LXC: sudo lxc-start -n C1 -l trace -o debug.out هذا سيؤدي إلى جعل lxc يسجل في أعلى درجة إسهاب، التي هي trace، وسيكون ملف التخزين هو ملف باسم «debug.out»، إذا كان الملف debug.out موجودًا مسبقًا، فستُضاف معلومات السجل الجديد إليه. مراقبة حالة الحاوية هنالك أمران متوفران لمراقبة تغيرات حالة الحاوية: lxc-monitor الذي يراقب حاويةً أو أكثر ﻷي تغيرات في الحالة، حيث يأخذ اسم الحاوية مع الخيار ‎-n كالعادة؛ لكن في هذا الحالة، يمكن أن يكون اسم الحاوية تعبيرًا نمطيًا من نمط POSIX للسماح بمراقبة مجموعة من الحاويات؛ يستمر lxc-monitor بالعمل ويعرض تغيرات حالات الحاويات؛ أما lxc-wait فينتظر تغيِّرًا محددًا في الحالة ثم ينتهي تنفيذه؛ على سبيل المثال: sudo lxc-monitor -n cont[0-5]* هذا سيعرض جميع تغيرات الحالة لأي حاوية تطابق التعبير النمطي؛ بينما: sudo lxc-wait -n cont1 -s 'STOPPED|FROZEN' سينتظر إلى أن تتغير حالة الحاوية cont1 إلى STOPPED أو FROZEN ثم ينتهي. الوصل من الممكن في أوبنتو 14.04 الوصل (attach) إلى مجال أسماء حاوية، أبسط طريقة هي تنفيذ: sudo lxc-attach -n C1 الذي سيبدأ صدفة موصولة لمجال الحاوية C1، أو داخل الحاوية؛ آلية عمل الوصل هي معقدة جدًا، مما يسمح بوصل مجموعة فرعية من مجالات أسماء (namespaces) الحاوية ونمط الحماية (security context)، راجع صفحة الدليل لمزيدٍ من المعلومات. درجة إسهاب init في الحاوية إذا أكمل LXC بدء تشغيل الحاوية، لكن فشل إكمال تنفيذ init فيها (على سبيل المثال، لم يُعرَض محث الدخول)، فمن المفيد طلب درجة إسهاب أكبر من عملية init، فلحاوية upstart: sudo lxc-start -n C1 /sbin/init loglevel=debug يمكنك أيضًا بدء تشغيل برامج مختلفة عن init، على سبيل المثال: sudo lxc-start -n C1 /bin/bash sudo lxc-start -n C1 /bin/sleep 100 sudo lxc-start -n C1 /bin/cat /proc/1/status واجهة LXC البرمجية API يمكن الوصول إلى غالبية وظائف LXC عبر واجهة برمجية (API) مُصدَّرة من liblxc التي تكون ارتباطاتها متوفرة لعدة لغات برمجية بما فيها بايثون، و lua، وروبي، و go. ما يلي هو مثال عن استخدام ربط بايثون (المتوفرة في حزمة python3-lxc)، التي تُنشِئ وتبدأ حاوية، ثم تنتظر إلى أن يوقف تشغيلها: # sudo python3 Python 3.2.3 (default, Aug 28 2012, 08:26:03) [GCC 4.7.1 20120814 (prerelease)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import lxc __main__:1: Warning: The python-lxc API isn't yet stable and may change at any p oint in the future. >>> c=lxc.Container("C1") >>> c.create("ubuntu") True >>> c.start() True >>> c.wait("STOPPED") True الحماية يربط مجال الأسماء المعرفات (ids) إلى الموارد؛ لكنه لا يوفر للحاوية أي معرِّف يمكنه أن يشير إلى المورد، لذلك يمكن أن يُحمى المورد؛ وهذا هو أساس بعض الحماية الموفرة لمستخدمي الحاوية؛ على سبيل المثال، مجال أسماء IPC معزول تمامًا؛ لكن مجالات أسماء أخرى فيها بعض «التسربات» (leaks) التي تسمح للامتيازات بأن تُستخرَج بشكل غير ملائم من الحاوية إلى حاوية أخرى، أو إلى المضيف. افتراضيًا، تُشغَّل حاويات LXC بسياسة AppArmor التي تقيّد بعض الأفعال، تفاصيل دمج AppArmor مع LXC موجودة في قسم «AppArmor» في الدرس السابق، الحاويات دون امتيازات تربط الجذر في الحاوية إلى مستخدم دون امتيازات في المضيف، وهذا يمنع الوصول إلى ملفات ‎/proc و ‎/sys التي تمثل موارد المضيف، وغيرها من الملفات المملوكة من الجذر في المضيف. الثغرات في استدعاءات النظام ميزة أساسية من مزايا الحاويات أنها تشارك النواة مع المضيف؛ وهذا يعني أنه إذا حوت النواة على أيّة ثغرات في استدعاءات النظام (system calls)، فيمكن أن تستغلها الحاوية؛ وبعد أن تتحكم حاوية بالنواة، فيمكنها أن تسيطر سيطرةً كاملةً على أي مورد معروف للمضيف! بدءًا من أوبنتو 12.10، يمكن أن تقيَّد الحاوية من مرشِّح seccomp، إن Seccomp هو ميزة جديدة في النواة التي تُرشِّح استدعاءات النظام التي يمكن أن تُستخدَم من المهمة وأولادها؛ بينما يتوقع الوصول إلى إدارة سهلة ومحسنة للسياسة في المستقبل القريب، لكن تحتوي السياسة الحالية على قائمة بيضاء بسيطة لأرقام استدعاءات النظام؛ يبدأ ملف السياسة برقم الإصدار (الذي يجب أن يكون 1) في أول سطر ونوع السياسة (الذي يجب أن يكون whitelist) في ثاني سطر؛ وتُلحَق بقائمة أرقام، كل رقم في سطر. سنحتاج عادةً لتشغيل حاوية بتوزيعة كاملة إلى عدد كبير من استدعاءات النظام؛ لكن لحاويات البرامج، يمكن أن نقلل عدد استدعاءات النظام المتوفرة إلى رقم قليل؛ وحتى للحاويات التي تشغل توزيعات كاملة يمكن الحصول على فوائد أمنية إذا حذفت -على سبيل المثال- استدعاءات النظام المتوافقة مع 32 بت في حاوية 64 بت؛ راجع صفحة دليل lxc.container.conf للمزيد من التفاصيل حول كيفية ضبط الحاوية لتستخدم seccomp؛ لن تُحمَّل افتراضيًا سياسة seccomp. مصادر كتاب «Secure Containers Cookbook» يشرح كيفية استخدام أنماط الحماية لجعل الحاويات أكثر أمانًا. مشروع LXC مُستضاف في linuxcontainers.org. مشاكل LXC الأمنية مذكورة ومناقشة في صفحة وكي «LXC Security». ترجمة -وبتصرف- للمقال Ubuntu Server Guide: LXC.

يهدف هذا الدرس إلى بناء تطبيق CRUD (إدراج بيانات في قاعدة بيانات، القراءة منها، تحديثها وحذفها؛ اختصار لـUpdate، Read، Create وDelete). التطبيق عبارة عن واجهة لإدارة لائحة من الموظفين: إضافة موظّف، تحرير بياناته أو حذفها. سنستخدم Laravel 5 للنهاية الخلفية Backend و AngularJS للنهاية الأمامية Frontend. سنستخدم أيضا Bootstrap لإضافة لمسة جمالية إلى التطبيق. هذا الدرس جزء من سلسلة تعلم Laravel والتي تنتهج مبدأ "أفضل وسيلة للتعلم هي الممارسة"، حيث ستكون ممارستنا عبارة عن إنشاء تطبيق ويب للتسوق مع ميزة سلة المشتريات. يتكون فهرس السلسلة من التالي: مدخل إلى Laravel 5.تثبيت Laravel وإعداده على كلّ من Windows وUbuntu.أساسيات بناء تطبيق باستخدام Laravel.إنشاء روابط محسنة لمحركات البحث (SEO) في إطار عمل Laravel.نظام Blade للقوالب.تهجير قواعد البيانات في Laravel.استخدام Eloquent ORM لإدخال البيانات في قاعدة البيانات، تحديثها أو حذفها.إنشاء سلة مشتريات في Laravel.الاستيثاق في Laravel.إنشاء واجهة لبرمجة التطبيقات API في Laravel.إنشاء مدوّنة باستخدام Laravel.استخدام AngularJS واجهةً أمامية Front end لتطبيق Laravel. (هذا الدرس)الدوّال المساعدة المخصّصة في Laravel.استخدام مكتبة Faker في تطبيق Laravel لتوليد بيانات وهمية قصدَ الاختبار. AngularJS هو إطار عمل جافاسكريبت قويّ وفعّال، يتبنى مبدأ النموذج-العرض-المتحكم MVC ويعمل لدى العميل (المتصفّح). للاطلاع على المزيد عن AngularJS تابع سلسلة دروس مدخل إلى تعلم AngularJS . يفترض هذا الدرس معرفة أساسيات Laravel 5، تثبيت كلّ من PHP، MySQL، ِApache وComposer. يغطي الدرس المواضيع التالية: إنشاء نهاية خلفية في Laravel 5، ستكون عبارة عن واجهة برمجية API.بنية تطبيق AngularJS.واجهة برمجية باستخدام Laravel 5ننشئ في هذه الفقرة النهاية الخلفية للتطبيق الذي نعمل عليه. سيتولى Laravel هذه المهمة. نبدأ بإنشاء تطبيق Laravel ثم نعدّه لتوفير الواجهة البرمجية. الخطوة الأولى: إنشاء تطبيق Laravelننفذ الأمر التالي في أصل المستند Document root لإنشاء مشروع Laravel باسم angulara: composer create-project laravel/laravel angularaراجع درس تثبيت Laravel 5 وإعداده على Windows وUbuntu للمزيد حول تثبيت Laravel وإعداده. سنفترض في بقية هذا الدرس تثبيت Laravel على المنصة المفضلة لديك وإنشاء مضيف افتراضي باسم angulara.dev. الخطوة التالية هي إعداد تهجير قاعدة البيانات. الخطوة الثانية: إعداد قاعدة البياناتستحتاج لقاعدة بيانات للعمل مع التطبيق. استخدم برنامج إدارة قاعدة البيانات المفضل لديك أو نفذ الأمر التالي في سطر أوامر MySQL لإنشاء قاعدة بيانات للمشروع: CREATE DATABASE `angulara`;ننتقل الآن لإعداد Laravel لكي يعمل مع قاعدة البيانات. افتح ملف env. في مجلد تطبيق Laravel وعدل القيم التالية بما يناسب: DB_HOST=localhost // اسم قاعدة البيانات DB_DATABASE=angulara // اسم مستخدم في MySQL لديه صلاحيات الكتابة والقراءة في القاعدة أعلاه DB_USERNAME=root // كلمة سر المستخدم DB_PASSWORD=melodyاحفظ التعديلات. نستغل أداة Artisan لإنشاء ملف تهجير خاص بجدول يحوي بيانات الموظفين employees. نفذ الأمر التالي لإنشاء ملف التهجير: php artisan make:migration create_employees_tableستحصُل على الرسالة التالية التي تعرض اسم الملف المنشأ: Created Migration: 2016_01_05_203637_create_employees_tableينشئ الأمر ملفا في المجلد database/migrations، نفتحه للتعديل عليه. عدّل المحتوى كالتالي: <?php use Illuminate\Database\Schema\Blueprint; use Illuminate\Database\Migrations\Migration; class CreateEmployeesTable extends Migration { /** * Run the migrations. * * @return void */ public function up() { Schema::create('employees', function (Blueprint $table) { $table->increments('id'); $table->string('name')->unique(); $table->string('email')->unique(); $table->string('contact_number'); $table->string('position'); $table->timestamps(); }); } /** * Reverse the migrations. * * @return void */ public function down() { Schema::drop('employees'); } }احفظ التعديلات ثم نفذ أمر ِArtisan التالي: php artisan migrateينفذ الأمر التهجيرات وينشئ جدول بيانات الموظفين. تظهر الرسائل التالية بعد تنفيذ الأمر: Migration table created successfully. Migrated: 2014_10_12_000000_create_users_table Migrated: 2014_10_12_100000_create_password_resets_table Migrated: 2016_01_05_203637_create_employees_tableتحقق من قاعدة بيانات MySQL، ستجد أن جدولا جديدا أُدرِج في القاعدة. الخطوة الثالثة: إنشاء واجهة برمجيةننشئ متحكما Controller للتطبيق، سنسميه Employees: php artisan make:controller Employeesثم يأتي دور النموذج Model: php artisan make:model Employeeسنضيف مصفوفة في النموذج لتفعيل الإسناد الشامل؛ افتح ملف النموذج وعدّله على النحو التالي: <?php namespace App; use Illuminate\Database\Eloquent\Model; class Employee extends Model { protected $fillable = array('id', 'name', 'email','contact_number','position'); }احفظ التعديلات. ننتقل للتعديل على المتحكم. افتح ملف المتحكم Employees وعدله ليصبح كالتالي <?php namespace App\Http\Controllers; use App\Employee; use Illuminate\Http\Request; use App\Http\Requests; use App\Http\Controllers\Controller; class Employees extends Controller { /** * Display a listing of the resource. * * @return Response */ public function index($id = null) { if ($id == null) { return Employee::orderBy('id', 'asc')->get(); } else { return $this->show($id); } } /** * Store a newly created resource in storage. * * @param Request $request * @return Response */ public function store(Request $request) { $employee = new Employee; $employee->name = $request->input('name'); $employee->email = $request->input('email'); $employee->contact_number = $request->input('contact_number'); $employee->position = $request->input('position'); $employee->save(); return 'Employee record successfully created with id ' . $employee->id; } /** * Display the specified resource. * * @param int $id * @return Response */ public function show($id) { return Employee::find($id); } /** * Update the specified resource in storage. * * @param Request $request * @param int $id * @return Response */ public function update(Request $request, $id) { $employee = Employee::find($id); $employee->name = $request->input('name'); $employee->email = $request->input('email'); $employee->contact_number = $request->input('contact_number'); $employee->position = $request->input('position'); $employee->save(); return "Sucess updating user #" . $employee->id; } /** * Remove the specified resource from storage. * * @param int $id * @return Response */ public function destroy($id = null) { if ($id == null) { } else { $employee = Employee::find($id); $employee->delete(); return "Employee record successfully deleted #" . $id; } } }يعرِّف المتحكم الدوالّ index لسرد قائمة بالموظفين، store لإضافة موظف جديد، show لعرض موظف بناء على معرّفه، update لتحديث بيانات موظّف وdestroy لحذف موظّف. تبقى لنا إعداد المسارات Routes في Laravel. افتح ملف المسارات routes.php وعدله كالتالي: <?php /* |-------------------------------------------------------------------------- | Application Routes |-------------------------------------------------------------------------- | | Here is where you can register all of the routes for an application. | It's a breeze. Simply tell Laravel the URIs it should respond to | and give it the controller to call when that URI is requested. | */ Route::get('/', function () { return view('index'); }); Route::get('/api/v1/employees/{id?}', 'Employees@index'); Route::post('/api/v1/employees', 'Employees@store'); Route::post('/api/v1/employees/{id}', 'Employees@update'); Route::delete('/api/v1/employees/{id}', 'Employees@destroy');لاحظ استخدام إجراءات HTTP وفقا للمبدأ المشروح في درس إنشاء واجهة برمجية API في Laravel 5. يختلف التعامل مع المسار api/v1/employees حسب إجراء HTTP المستخدم: get يُستخدم للحصول على معلومات موظف أو قائمة بالموظفين، post لإضافة موظف جديد، put لتحديث بيانات موظّف وdelete لحذف موظّف. أكملنا الآن جانب النهاية الخلفية بإنشاء واجهة برمجية. ننتقل للواجهة الأمامية التي ستستخدم الواجهة البرمجية للحصول على بيانات الموظفين وتنسيقها قبل عرضها في المتصفح. بنية تطبيق AngularJSسيأخذ مجلد public (الواجهة الأمامية لتطبيق Laravel) الشكل التالي: يحوي المجلّد الفرعي app ملفات جافاسكريبت التابعة لـAngularJS.توجد متحكمات AngularJS في المجلّد app/controllers.توجد ملفات نواة AngularJS في المجلّد app/lib. توجد أيضا إمكانية استخدام شبكة توصيل محتوى Content delivery network, CDN.توجد ملفات CSS في المجلد css.ملفات جافاسكريبت غير التابعة لـAngularJS توجد في المجلد js.توجد ملفات الواجهة الأمامية في الملف المرفق، سنشرح ما يحتاج لشرح منها. الملف app.jsسنستخدم الملف public/app/app.js لتعريف التطبيق الخاص بنا: var app = angular.module('employeeRecords', []) .constant('API_URL', 'http://angulara.dev/api/v1/');ننشئ وحدة Module في AngularJS ونسند الكائن إلى المتغير app. سيُستخدم هذا المتغير في جميع ملفات AngularJS؛ ثم نعرّف ثابتا Constant لرابط الواجهة البرمجية API_URL. ملحوظة: إن كنت اخترت اسما مختلفا للمضيف فضعه مكان angulara.dev. المتحكم Employees.jsسيكون هذا الملف مسؤولا عن التفاعل مع عروض تطبيق AngularJS: app.controller('employeesController', function($scope, $http, API_URL) { // الحصول على لائحة الموظفين $http.get(API_URL + "employees") .success(function(response) { $scope.employees = response; }); // عرض نافذة منبثقة $scope.toggle = function(modalstate, id) { $scope.modalstate = modalstate; switch (modalstate) { case 'add': $scope.form_title = "Add New Employee"; break; case 'edit': $scope.form_title = "Employee Detail"; $scope.id = id; $http.get(API_URL + 'employees/' + id) .success(function(response) { console.log(response); $scope.employee = response; }); break; default: break; } console.log(id); $('#myModal').modal('show'); } //save new record / update existing record $scope.save = function(modalstate, id) { var url = API_URL + "employees"; var request_method = 'POST'; //append employee id to the URL if the form is in edit mode if (modalstate === 'edit'){ url += "/" + id; request_method = 'PUT'; } $http({ method: request_method, url: url, data: $.param($scope.employee), headers: {'Content-Type': 'application/x-www-form-urlencoded'} }).success(function(response) { console.log(response); location.reload(); }).error(function(response) { console.log(response); alert('This is embarassing. An error has occured. Please check the log for details'); }); } //delete record $scope.confirmDelete = function(id) { var isConfirmDelete = confirm('Are you sure you want this record?'); if (isConfirmDelete) { $http({ method: 'DELETE', url: API_URL + 'employees/' + id }). success(function(data) { console.log(data); location.reload(); }). error(function(data) { console.log(data); alert('Unable to delete'); }); } else { return false; } } });نعرِّف متحكما باسم employeesController في المتغيّر app الذي أنشأناه في الملف app.js. حدّدنا الاعتماديات بـ $http، scope$ وAPI_URL. نستدعي خدمة http$ في AngularJS لإرسال طلب إلى الواجهة البرمجية، مع تمرير المعطى API_URL + "employees": $http.get(API_URL + "employees").success(function(response) {$scope.employees = response;});عند نجاح الطلب نُسنِد الإجابة إلى المتغير scope.employees$ الذي سيصبح متاحا في العرض View لإظهار محتواه. تعرض الدالة: $scope.toggle = function(modalstate, id) {…}نافذة منبثقة تحوي استمارة لإضافة موظّف جديد أو تعديل بيانات موظّف موجود حسب الحالة. نستخدم الدالة: $scope.save = function(modalstate, id){…}في حالتيْ الإضافة والتعديل. بالنسبة لإضافة موظّف نستخدم إجراء POST؛ وفي حالة التعديل نستخدم الإجراء PUT. تحذف الدالة: $scope.confirmDelete = function(id){…}بيانات موظّف من جدول الموظفين. عرض البيانات المتحصل عليها من الواجهة البرمجية بـAngularJSسننشئ عرضا لإظهار البيانات التي نتحصل عليها من الواجهة البرمجية؛ يستخدم كل من angularJS وBlade الحاضنات المزدوجة {{}} لعرض البيانات، لذا لن نحفظ عرض AngularJS بلاحقة blade.php حتى لا يعدّ نظام Blade العرض موجها له. محتوى العرض هو التالي، نحفظ الملف index.php في ملف العروض resources/views حتى يُحمّل عند طلبه من المسار / (الصفحة الرئيسية للموقع): <!DOCTYPE html> <html lang="en-US" ng-app="employeeRecords"> <head> <title>Laravel 5 AngularJS CRUD Example</title> <!-- Load Bootstrap CSS --> <link href="<?= asset('css/bootstrap.min.css') ?>" rel="stylesheet"> </head> <body> <h2>Employees Database</h2> <div ng-controller="employeesController"> <!-- Table-to-load-the-data Part --> <table class="table"> <thead> <tr> <th>ID</th> <th>Name</th> <th>Email</th> <th>Contact No</th> <th>Position</th> <th><button id="btn-add" class="btn btn-primary btn-xs" ng-click="toggle('add', 0)">Add New Employee</button></th> </tr> </thead> <tbody> <tr ng-repeat="employee in employees"> <td>{{ employee.id }}</td> <td>{{ employee.name }}</td> <td>{{ employee.email }}</td> <td>{{ employee.contact_number }}</td> <td>{{ employee.position }}</td> <td> <button class="btn btn-default btn-xs btn-detail" ng-click="toggle('edit', employee.id)">Edit</button> <button class="btn btn-danger btn-xs btn-delete" ng-click="confirmDelete(employee.id)">Delete</button> </td> </tr> </tbody> </table> <!-- End of Table-to-load-the-data Part --> <!-- Modal (Pop up when detail button clicked) --> <div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">×</span></button> <h4 class="modal-title" id="myModalLabel">{{form_title}}</h4> </div> <div class="modal-body"> <form name="frmEmployees" class="form-horizontal" novalidate=""> <div class="form-group error"> <label for="inputEmail3" class="col-sm-3 control-label">Name</label> <div class="col-sm-9"> <input type="text" class="form-control has-error" id="name" name="name" placeholder="Fullname" value="{{name}}" ng-model="employee.name" ng-required="true"> <span class="help-inline" ng-show="frmEmployees.name.$invalid && frmEmployees.name.$touched">Name field is required</span> </div> </div> <div class="form-group"> <label for="inputEmail3" class="col-sm-3 control-label">Email</label> <div class="col-sm-9"> <input type="email" class="form-control" id="email" name="email" placeholder="Email Address" value="{{email}}" ng-model="employee.email" ng-required="true"> <span class="help-inline" ng-show="frmEmployees.email.$invalid && frmEmployees.email.$touched">Valid Email field is required</span> </div> </div> <div class="form-group"> <label for="inputEmail3" class="col-sm-3 control-label">Contact Number</label> <div class="col-sm-9"> <input type="text" class="form-control" id="contact_number" name="contact_number" placeholder="Contact Number" value="{{contact_number}}" ng-model="employee.contact_number" ng-required="true"> <span class="help-inline" ng-show="frmEmployees.contact_number.$invalid && frmEmployees.contact_number.$touched">Contact number field is required</span> </div> </div> <div class="form-group"> <label for="inputEmail3" class="col-sm-3 control-label">Position</label> <div class="col-sm-9"> <input type="text" class="form-control" id="position" name="position" placeholder="Position" value="{{position}}" ng-model="employee.position" ng-required="true"> <span class="help-inline" ng-show="frmEmployees.position.$invalid && frmEmployees.position.$touched">Position field is required</span> </div> </div> </form> </div> <div class="modal-footer"> <button type="button" class="btn btn-primary" id="btn-save" ng-click="save(modalstate, id)" ng-disabled="frmEmployees.$invalid">Save changes</button> </div> </div> </div> </div> </div> <!-- Load Javascript Libraries (AngularJS, JQuery, Bootstrap) --> <script src="<?= asset('app/lib/angular/angular.min.js') ?>"></script> <script src="<?= asset('js/jquery.min.js') ?>"></script> <script src="<?= asset('js/bootstrap.min.js') ?>"></script> <!-- AngularJS Application Scripts --> <script src="<?= asset('app/app.js') ?>"></script> <script src="<?= asset('app/controllers/employees.js') ?>"></script> </body> </html>نربط تطبيق AngularJS بوسم html حتى يكون له كامل التحكّم في العناصر الموجودة في الصفحة: <html lang="en-US" ng-app="employeeRecords"> نفس الشيء بالنسبة للمتحكم employeesController الذي نربطه بعنصر div حتى نجعل جميع دوال المتحكم متاحة في هذا العنصر: <div ng-controller="employeesController">نستخدم تعليمة ng-repeat للمرو على جميع عناصر المجموعة employees: <tr ng-repeat="employee in employees">تعمل ng-repeat بطريقة مشابهة لعمل الحلقة التكرارية foreach. التحقق من بيانات استمارات AngularJSاستخدمنا في استمارات الموظفين طرقا للتحقق من المُدخلات. اعثر على الشفرات التالية في ملف العرض index.php ولاحظ استخدامها: <form name="frmEmployees" class="form-horizontal" novalidate="">تعرّف هذه الشفرة استمارة باسم frmEmployees وتضيف إليها خاصيّة novalidate للطلب من HTML 5 الامتناع عن تدقيق الاستمارة، سنتولى الأمر. <input type… ng-model="employee.name" ng-required="true">تستخدم تعليمة ng-model لربط حقول الاستمارة ببيانات النموذج Employee. ربطنا الحقل أعلاه بخاصية name في النموذج. بهذه الطريقة يكون محتوى الحقل متاحا للنموذج، والعكس أيضا. تدل التعليمة ng-required أن الحقل مطلوب. إن لم تذكر قيمة لهذا الحقل فلن يمكن إرسال الاستمارة. <span class="help-inline" ng-show="frmEmployees.name.$invalid && frmEmployees.name.$touched">لا يظهر هذا العنصُر إلا إذا أخفق التحقق من حقل name قبله. تظهر رسالة تفيد أن قيمة الحقل مطلوبة. ng-disabled="frmEmployees.$invalid" تعطّل هذه التعليمة إمكانية إرسال الاستمارة عند إخفاق التحقق من أحد الحقول المطلوبة. حان الآن وقت تجربة ما عملناه في الخطوات السابقة، افتح الموقع (بالنسبة لي اخترتُ إنشاء مضيف افتراضي angulara.dev): http://angulara.dev/ستحصُل، إن اتبعت الخطوات السابقة، على الواجهة التالية: اضغط على زر Add New Employee لإضافة موظّف. ستظهر نافذة منبثقة لإضافة بيانات الموظّف. تصبح الواجهة بعد إضافة موظفين على النحو التالي: تمكّن الأزرار edit و delete الموجودة في كل سطر تحديثَ أو حذف بيانات موظّف. الملف المرفق: مجلد public. ترجمة -وبتصرّف- لمقال Laravel 5 AngularJS Tutorial لصاحبه Rodrick Kazembe.