التطوير على الجهاز باستخدام Cloud Functions لـ Node.js باستخدام Visual Studio Code

1. نظرة عامة

Google Cloud Functions هي منصّة حوسبة بدون خادم تستنِد إلى الأحداث. تتيح لك Cloud Functions كتابة رمزك البرمجي بدون القلق بشأن توفير الموارد أو التوسّع في المعالجة لتلبية المتطلبات المتغيّرة.

يتم تنفيذ وظائف Cloud مكتوبة بلغة JavaScript في بيئة Node.js على Google Cloud Platform. يمكنك تشغيل Cloud Function في أي وقت تشغيل عادي لـ Node.js لتفعيل إمكانية النقل والاختبار على الجهاز.

جولة إرشادية

في هذا الدليل التعليمي حول الرموز البرمجية، ستنشئ دالة Cloud Function لـ Node.js تُبلغك ما إذا كانت درجة الحرارة المحدّدة مقبولة أو مرتفعة جدًا. ستنشئ دالة Cloud Function وتختبرها وتصحِّح أخطاءها باستخدام Visual Studio Code على جهازك المحلي. أخيرًا، عليك نشر الدالة على Google Cloud Platform.

ما ستتعرّف عليه

  • إطار عمل Functions لنظام التشغيل Node.js
  • أنشئ دالة HTTP Cloud Function واختبرَها محليًا.
  • تصحيح أخطاء دالة HTTP من جهازك المحلي
  • يمكنك نشر دالة HTTP من جهازك المحلي.

2. الإعداد والمتطلبات

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

التكلفة

على الرغم من أنّ هذا الدليل التعليمي للترميز لا يتطلّب سوى طلب واحد لإحدى وظائف Cloud Functions المنشورة، يجب الرجوع إلى معلومات أسعار واجهة برمجة تطبيقات Cloud Functions لفهم آلية عمل الفوترة.

على الرغم من أنّه يمكن استخدام العديد من واجهات برمجة تطبيقات Google بدون رسوم، إلا أنّ استخدام Google Cloud Platform (أي منتجاتها وواجهات برمجة التطبيقات) ليس مجانيًا. ستحتاج إلى حساب فوترة نشط لاستخدام Cloud Functions. يُرجى العِلم أنّ بعض منتجات Google Cloud Platform (GCP) تتضمّن "المستوى المجاني دائمًا" الذي يجب تجاوزه لكي يتم تحصيل رسوم منك. لأغراض ورشة رموز البرامج، يتم احتساب كلّ طلب تشغيل لوظائف Cloud ضمن هذه الفئة المجانية. طالما أنّك تلتزم بالحدود القصوى بشكل إجمالي (خلال كل شهر)، لن يتم تحصيل أي رسوم منك.

3- تثبيت إطار عمل Functions لنظام التشغيل Node.js

إطار عمل Functions لـ Node.js هو إطار عمل مفتوح المصدر لوظائف FaaS (Function as a Service) لكتابة وظائف Node.js قابلة للنقل، وهو يوفّره لك فريق Google Cloud Functions.

يتيح لك إطار عمل Functions Framework كتابة دوال خفيفة الوزن يتم تشغيلها في العديد من البيئات المختلفة، بما في ذلك:

  • Google Cloud Functions
  • جهاز التطوير المحلي
  • Cloud Run وCloud Run على GKE
  • البيئات المستندة إلى Knative

أنشئ تطبيقًا جديدًا باستخدام node.js.

npm init

أثناء قبول الإعدادات التلقائية، احرص على استخدام index.js كنقطة دخول لتطبيقك.

ثبِّت الآن إطار عمل Functions لنظام التشغيل Node.js.

npm install @google-cloud/functions-framework

افتح package.json. تأكَّد من أنّ إطار عمل الدوالّ مُدرَج كعنصر تابع كما هو موضّح في المثال أدناه.

"dependencies": {
   "@google-cloud/functions-framework": "^1.7.1"
 }

تم الآن تثبيت إطار عمل Functions بنجاح. أنت الآن جاهز لإنشاء دالة Cloud.

4. إنشاء دالة HTTP Cloud Function واختبارها محليًا

إنشاء دالة Cloud Function على الجهاز

في هذا القسم، ستُنشئ دالة HTTP وتُجري اختبارًا لها تستجيب لطلبات HTTP.

أنشئ ملفًا جديدًا باسم index.js في الدليل نفسه الذي يتضمّن ملف package.json.

أضِف ما يلي:

exports.validateTemperature = async (req, res) => {
 try {
   if (req.body.temp < 100) {
     res.status(200).send("Temperature OK");
   } else {
     res.status(200).send("Too hot");
   }
 } catch (error) {
   //return an error
   console.log("got error: ", error);
   res.status(500).send(error);
 }
};

يمكنك الآن اختبار الدالة.

اختبار الدالة في Visual Studio Code

من هذه النقطة فصاعدًا، يستخدم هذا الدرس التطبيقي حول الترميز وحدة التحكّم المدمجة في Visual Studio Code.

في Visual Studio Code، افتح نافذة وحدة طرفية.

نفِّذ الأمر التالي:

node node_modules/@google-cloud/functions-framework --target=validateTemperature

يشغِّل هذا الأمر خادمًا محليًا جاهزًا لاستدعاء الدالة validateTemperature عندما يتلقّى الخادم طلب HTTP.

من المفترض أن يظهر لك الإخراج التالي في نافذة وحدة التحكّم:

Serving function...
Function: validateTemperature
URL: http://localhost:8080/

أنشئ نافذة وحدة طرفية ثانية في VS Code بالنقر على رمز الإضافة New Terminal في لوحة نافذة Terminal. ستبدِّل بين نافذتَي الطرفَين: الأولى لعرض الدالة والثانية لاستدعاء الدالة باستخدام curl.

bceb65f366d837ae.png

يمكنك التبديل بين نوافذ المحطة الطرفية باستخدام القائمة المنسدلة. إذا كانت نافذة طرفية تؤدي حاليًا وظيفة، تشير القائمة المنسدلة إليها باسم node. وبخلاف ذلك، تتم الإشارة إلى zsh (أو إلى بيئة Shell التي تستخدمها).

في نافذة الوحدة الطرفية الثانية، نفِّذ الأمر التالي لإرسال حمولة درجة حرارة تبلغ 50 إلى الخادم المحلي الذي يعرض الدالة validateTemperature.

curl -X POST http://localhost:8080 -H "Content-Type:application/json"  -d '{"temp":"50"}'

من المفترض أن يصلك الردّ التالي من دالة السحابة الإلكترونية:

Temperature OK

في نافذة الوحدة الطرفية الثانية، اختبِر الدالة مرة أخرى من خلال إرسال حمولة درجة حرارة "مرتفعة جدًا" كما هو موضّح أدناه:

curl -X POST http://localhost:8080 -H "Content-Type:application/json"  -d '{"temp":"120"}'

من المفترض أن يصلك الردّ التالي من دالة السحابة الإلكترونية:

Too hot

أخيرًا، اختبِر الدالة من خلال استدعائها باستخدام حمولة غير متوفّرة.

curl -X POST http://localhost:8080

من المفترض أن يصلك الردّ التالي من دالة السحابة الإلكترونية:

Too hot

من المفترض ألا تعرِض الدالة القيمة "حار جدًا" في حال عدم تقديم درجة حرارة. إذا رصدت خطأً في الرمز

احرص على إيقاف تشغيل الدالة من خلال الضغط على Ctrl + C في نافذة المحطة الطرفية الأولى التي تعرض الدالة.

5- تصحيح أخطاء وظيفة HTTP من جهازك المحلي

افتح لوحة الأوامر في Visual Studio Code. إذا كنت تستخدم جهاز Mac، استخدِم Cmd + Shift + P. إذا كنت تستخدم نظام التشغيل Windows، استخدِم Ctrl + Shift + P..

اكتب auto attach في لوحة الأوامر واختَر العنصر الأول في القائمة.

601e542b4ec9f6f9.png

في هذا الدليل التعليمي حول الرموز البرمجية، اختَر Only With Flag كما هو موضّح في الصورة أدناه:

b9e6b762d150e62b.png

أعِد الآن تحميل نافذة المحطة الطرفية التي استخدمتها في VS Code لعرض دالتك من خلال تمرير مؤشر الماوس فوق رمز التحذير الذي يظهر في أقصى يسار الشاشة.

انقر على Relaunch Terminal.

37b61e3fb546fc76.png

من نافذة وحدة التحكّم التي تمت إعادة تحميلها، أعِد تشغيل إطار عمل الدوال لعرض الدالة باستخدام الأمر التالي:

node --inspect node_modules/.bin/functions-framework --target=validateTemperature

حيث تُطلب من Node.js الاستماع إلى عميل تصحيح الأخطاء باستخدام العلامة --inspect. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Node حول تصحيح الأخطاء.

يُرجى العِلم أنّك تستخدِم node_modules/.bin/functions-framework بدلاً من node_modules/@google-cloud/functions-framework. يجب استخدام ملف التشغيل القابل للربط التسلسلي تلقائيًا في ‎ /node_modules/.bin لاستخدام وضع الفحص.

من المفترض أن يظهر لك هذه المرة شريط حالة برتقالي في VS Code يشير إلى أنّه تم إرفاق أداة تصحيح الأخطاء.

اضبط نقطة توقّف في السطر 3 من خلال النقر داخل الهامش على يمين رقم السطر.

2fbb4d5916e1dbfa.png

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

846e6c5993cc87f9.png

في نافذة الوحدة الطرفية الثانية، يمكنك الوصول إلى نقطة التوقف عن طريق تنفيذ الأمر curl التالي.

curl -X POST http://localhost:8080

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

206c7ed1eb189e90.png

مرِّر مؤشر الماوس فوق متغيّر temp للتأكّد من أنّ محتوياته هي undefined، لأنّ الطلب لم يقدّم بيانات أساسية لدرجة الحرارة.

97979025f4bf2842.png

انقر على رمز التخطّي لتنفيذ العبارة التالية.

ستلاحظ أنّ العبارة الحالية تقفز إلى جزء else من عبارة if.

cf0e8ce7e0388f98.png

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

انقر على الزر "قطع الاتصال" (Disconnect) لقطع الاتصال بينك وبين مصحِّح الأخطاء.

1070d059775ad769.png

في نافذة المحطة الطرفية الأولى، أوقِف عرض الدالة من خلال الضغط على Ctrl + C.

عدِّل الدالة لإضافة عبارة if لطرح استثناء إذا كانت درجة الحرارة غير محدّدة كما هو موضّح أدناه:

exports.validateTemperature = async (req, res) => {

 try {

   // add this if statement below line #2
   if (!req.body.temp) {
     throw "Temperature is undefined";
   }

 ...

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

node node_modules/@google-cloud/functions-framework --target=validateTemperature

تأكَّد من ظهور استثناء من خلال تنفيذ الأمر التالي في نافذة الوحدة الطرفية الثانية:

curl -X POST http://localhost:8080

من المفترض أن يظهر لك الناتج التالي من طلبك:

Temperature is undefined

في نافذة المحطة الطرفية الأولى، سيظهر لك أيضًا الخطأ الذي سجّلته دالتك.

Serving function...
Function: validateTemperature
URL: http://localhost:8080/
got error:  Temperature is undefined

يمكنك الآن إيقاف تشغيل الدالة من خلال الضغط على Ctrl ‏+ C في نافذة الوحدة الطرفية الأولى.

6- نشر دالة HTTP من جهازك المحلي إلى Google Cloud

بعد إنشاء دالة Cloud Function واختبارها وتصحيح أخطاءها على جهازك المحلي، تكون مستعدًا لنشرها على Google Cloud.

تأكَّد من استخدام المشروع الذي أنشأته في الخطوة 2 على الجهاز من خلال تنفيذ الأمر التالي:

gcloud config get-value project

إذا لم يكن المشروع الذي حدّدته في الخطوة 2 هو الإعداد النشط، نفِّذ الأمر التالي:

gcloud config set project <project-name-created-step-2>

في أي نافذة وحدة طرفية، نفِّذ الأمر التالي:

gcloud functions deploy validateTemperature --trigger-http --runtime nodejs12 --allow-unauthenticated

حيث يتم شرح المَعلمات على النحو التالي:

  • deploy validateTemperature: الأمر الفرعي gcloud لنشر إحدى وظائف Cloud التي تحمل الاسم validateTemperature مع نقطة دخول باسم validateTemperature
  • ‫--trigger-http: نوع الحدث المشغِّل
  • --runtime nodejs12: وقت التشغيل المستهدَف لهذه الدالة
  • ‫--allow-unauthenticated - السماح بالوصول العلني إلى دالة الاتصال

سيُطلب منك تفعيل واجهات برمجة تطبيقات Cloud Functions. اكتب y لتفعيل واجهات برمجة التطبيقات.

API [cloudfunctions.googleapis.com] not enabled on project 
[1057316433766]. Would you like to enable and retry (this will take a 
few minutes)? (y/N)? y

بعد اكتمال عملية النشر، سيظهر لك ما يلي في الإخراج:

Deploying function (may take a while - up to 2 minutes)...done. 
availableMemoryMb: 256
buildId: <your-build-id>
entryPoint: validateTemperature
httpsTrigger:
  url: https://<your-region-and-project>.cloudfunctions.net/validateTemperature
...

في نافذة المحطة الطرفية، استخدِم curl للاتصال بنقطة النهاية العامة هذه.

curl -X POST https://<your-region-and-project>.cloudfunctions.net/validateTemperature -H "Content-Type:application/json"  -d '{"temp":"50"}'

وتأكَّد من نشر وظيفة السحابة الإلكترونية بنجاح من خلال التحقّق من الاستجابة المناسبة.

Temperature OK

7- تَنظيم

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

لحذف Cloud Function، انتقِل إلى Cloud Function Cloud Console على الرابط https://console.cloud.google.com/functions/ وتأكَّد من أنّ المشروع الذي أنشأته في الخطوة 2 هو المشروع المحدّد حاليًا.

اختَر دالة validateTemperature التي تم نشرها في الخطوة 6. بعد ذلك، اضغط على "حذف".

4dada486485a935a.png

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager واختيار المشروع الذي أنشأته في الخطوة 2 ثم اختيار "حذف". في حال حذف المشروع، عليك تغيير المشاريع في حزمة Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.

8. تهانينا!

تهانينا على إكمال ورشة رموز البرامج. يمكنك الاطّلاع على مزيد من المعلومات عن كيفية توافق Cloud Functions مع وقت تشغيل Node.js وآلية عمل تصحيح الأخطاء المحلي مع Cloud Functions.

المواضيع التي تناولناها

  • إطار عمل Functions لنظام التشغيل Node.js
  • أنشئ دالة HTTP Cloud Function واختبرَها محليًا.
  • تصحيح أخطاء دالة HTTP من جهازك المحلي
  • يمكنك نشر دالة HTTP من جهازك المحلي.