البدء: كتابة الدوال الأولى واختبارها ونشرها

الجيل الثاني الجيل الأول

لبدء استخدام Cloud Functions، جرِّب تنفيذ هذا البرنامج التعليمي الذي يبدأ بمهام الإعداد المطلوبة ويشرح كيفية إنشاء واختبار ونشر وظيفتَين مرتبطتَين:

• دالة "إضافة رسالة" تعرض عنوان URL يقبل قيمة نصية ويكتبها في Cloud Firestore.
• دالة "تحويل إلى أحرف كبيرة" يتم تشغيلها عند Cloud Firestore الكتابة وتحويل النص إلى أحرف كبيرة

لقد اخترنا Cloud Firestore ودوال JavaScript التي يتم تشغيلها عبر HTTP لهذا النموذج، ويعود السبب جزئيًا إلى أنّه يمكن اختبار مشغّلات الخلفية هذه بشكل كامل من خلال Firebase Local Emulator Suite. تتيح مجموعة الأدوات هذه أيضًا استخدام Realtime Database وPubSub وAuth ومشغّلات HTTP القابلة للاستدعاء. يمكن اختبار الأنواع الأخرى من المشغّلات التي تعمل في الخلفية، مثل Remote Config وTestLab ومشغّلات "إحصاءات Google"، بشكل تفاعلي باستخدام مجموعات الأدوات غير الموضّحة في هذه الصفحة.

ملاحظة: يمكنك محاكاة الدوال في أي مشروع على Firebase، ولكن لنشرها في بيئة وقت التشغيل Node.js 14، يجب أن يكون مشروعك ضمن خطة التسعير Blaze. يمكنك الاطّلاع على Cloud Functions الأسعار.

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

إنشاء مشروع على Firebase

مستخدم جديد لمنصة Firebase أو Cloud

اتّبِع الخطوات التالية إذا كنت جديدًا على Firebase أو Google Cloud.
يمكنك أيضًا اتّباع هذه الخطوات إذا أردت إنشاء مشروع Firebase جديد تمامًا (وGoogle Cloud المشروع الأساسي).

1. سجِّل الدخول إلى وحدة تحكّم Firebase.
2. انقر على الزر لإنشاء مشروع جديد في Firebase.

3. في حقل النص، أدخِل اسم مشروع.

   إذا كنت جزءًا من Google Cloud مؤسسة، يمكنك اختياريًا تحديد المجلد الذي تريد إنشاء مشروعك فيه.

   يُستخدَم اسم مشروعك كاسم معروض في واجهات Firebase، وتنشئ Firebase تلقائيًا رقم تعريف فريدًا للمشروع استنادًا إلى اسم المشروع هذا. يُرجى العِلم أنّه يمكنك اختياريًا النقر على رمز التعديل الآن لضبط رقم تعريف المشروع المفضّل، ولكن لا يمكنك تغيير رقم التعريف هذا بعد إنشاء المشروع. تعرَّف على كيفية استخدام Firebase لرقم تعريف المشروع.
4. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
5. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase")، والتي يمكن أن تساعدك في بدء الاستخدام وتسهيل عملية التطوير.

6. (اختياري) يمكنك إعداد Google Analytics لمشروعك، ما يتيح تجربة مثالية باستخدام منتجات Firebase التالية: Firebase A/B Testing وCloud Messaging وCrashlytics وIn-App Messaging وRemote Config (بما في ذلك التخصيص).

   اختَر حسابًا حاليًا Google Analytics أو أنشِئ حسابًا جديدًا. إذا أنشأت حسابًا جديدًا، اختَر Analytics الموقع الجغرافي لإعداد التقارير، ثم اقبل إعدادات مشاركة البيانات وبنود Google Analytics مشروعك.

   يمكنك إعداد Google Analytics لاحقًا في علامة التبويب عمليات الدمج ضمن إعدادات المشروع.
7. انقر على إنشاء مشروع.

تنشئ Firebase مشروعك وتوفّر بعض الموارد الأولية وتفعِّل واجهات برمجة التطبيقات المهمة. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروعك على Firebase في Firebase.

مشروع حالي على السحابة الإلكترونية

اتّبِع الخطوات التالية إذا كنت تريد بدء استخدام Firebase مع Google Cloud مشروع حالي. مزيد من المعلومات حول"إضافة Firebase" إلى مشروع Google Cloud حالي

1. سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام الحساب الذي يتيح لك الوصول إلى مشروع Google Cloud الحالي.
2. انقر على الزر لإنشاء مشروع جديد في Firebase.
3. في أسفل الصفحة، انقر على إضافة Firebase إلى مشروع Google Cloud.
4. في حقل النص، ابدأ بإدخال اسم المشروع الخاص بالمشروع الحالي، ثم اختَر المشروع من القائمة المعروضة.
5. انقر على فتح مشروع.
6. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
7. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase")، والتي يمكن أن تساعدك في بدء الاستخدام وتسهيل عملية التطوير.

8. (اختياري) يمكنك إعداد Google Analytics لمشروعك، ما يتيح تجربة مثالية باستخدام منتجات Firebase التالية: Firebase A/B Testing وCloud Messaging وCrashlytics وIn-App Messaging وRemote Config (بما في ذلك التخصيص).

   اختَر حسابًا حاليًا Google Analytics أو أنشِئ حسابًا جديدًا. إذا أنشأت حسابًا جديدًا، اختَر Analytics الموقع الجغرافي لإعداد التقارير، ثم اقبل إعدادات مشاركة البيانات وبنود Google Analytics مشروعك.

   يمكنك إعداد Google Analytics لاحقًا في علامة التبويب عمليات الدمج ضمن إعدادات المشروع.
9. انقر على إضافة Firebase.

تضيف Firebase إلى مشروعك الحالي. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروعك على Firebase في Firebase.

إعداد Node.js وFirebase CLI

ستحتاج إلى بيئة Node.js لكتابة الدوال، وستحتاج إلى واجهة سطر الأوامر Firebase لنشر الدوال في وقت التشغيل Cloud Functions. لتثبيت Node.js وnpm، ننصحك باستخدام Node Version Manager.

ملاحظة مهمة: يتوافق هذا الإصدار مع الإصدارَين 14 و16 من Node.js. راجِع مقالة ضبط خيارات وقت التشغيل للحصول على معلومات مهمة بشأن استمرار توفير الدعم لهذه الإصدارات من Node.js.

بعد تثبيت Node.js وnpm، ثبِّت Firebase CLI باستخدام الطريقة التي تفضّلها. لتثبيت واجهة سطر الأوامر من خلال npm، استخدِم ما يلي:

npm install -g firebase-tools

يؤدي ذلك إلى تثبيت أمر firebase المتاح على مستوى العالم. إذا تعذّر تنفيذ الأمر، قد تحتاج إلى تغيير أذونات npm. للتحديث إلى أحدث إصدار من firebase-tools، أعِد تنفيذ الأمر نفسه.

في كثير من الحالات، لا تتوفّر الميزات الجديدة وإصلاحات الأخطاء إلا مع أحدث إصدار من واجهة سطر الأوامر (CLI) في Firebase وfirebase-functions SDK. من الممارسات الجيدة أن يتم تحديث كلّ من Firebase CLI وحزمة SDK بشكل متكرّر باستخدام الأوامر التالية داخل المجلد functions لمشروعك على Firebase:

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

تهيئة مشروعك

عند إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Firebase لنظام التشغيل Cloud Functions، يمكنك إنشاء مشروع فارغ يحتوي على التبعيات وبعض نماذج الرموز البرمجية البسيطة، ويمكنك اختيار TypeScript أو JavaScript لإنشاء الدوال. لأغراض هذا البرنامج التعليمي، عليك أيضًا تهيئة Cloud Firestore.

لبدء مشروعك، اتّبِع الخطوات التالية:

1. نفِّذ الأمر firebase login لتسجيل الدخول عبر المتصفح والمصادقة على واجهة سطر الأوامر Firebase.

   ملاحظة: إذا كنت تستخدم جهازًا لا يمكن الوصول إلى المضيف المحلي فيه، أضِف العلامة --no-localhost.

2. انتقِل إلى دليل مشروعك على Firebase.

3. نفِّذ الأمر firebase init firestore. في هذا البرنامج التعليمي، يمكنك قبول القيم التلقائية عند مطالبتك بقواعد Firestore وملفات الفهرس. إذا لم يسبق لك استخدام Cloud Firestore في هذا المشروع، عليك أيضًا اختيار وضع وموقع جغرافي لبدء استخدام Firestore كما هو موضّح في بدء استخدام Cloud Firestore.

4. نفِّذ الأمر firebase init functions. سيطلب منك واجهة سطر الأوامر اختيار قاعدة رموز برمجية حالية أو إنشاء قاعدة رموز برمجية جديدة وتسميتها. عندما تكون في بداية استخدامك، سيكون رمز أساسي واحد في الموقع التلقائي كافيًا، ولكن عندما يتوسّع استخدامك، قد تحتاج إلى تنظيم الدوال في رموز أساسية.

5. تمنحك واجهة سطر الأوامر الخيارات التالية لدعم اللغة:

   • JavaScript
   • Python
   • ‫TypeScript اطّلِع على كتابة الدوال باستخدام TypeScript لمزيد من المعلومات.

   في هذا البرنامج التعليمي، اختَر JavaScript.

6. توفّر لك واجهة سطر الأوامر خيارًا لتثبيت التبعيات باستخدام npm. يمكنك رفض ذلك إذا أردت إدارة التبعيات بطريقة أخرى، ولكن في حال الرفض، عليك تنفيذ الأمر npm install قبل محاكاة وظائفك أو نشرها.

بعد اكتمال تنفيذ هذه الأوامر بنجاح، سيصبح شكل بنية مشروعك كما يلي:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

يحتوي ملف package.json الذي تم إنشاؤه أثناء عملية الإعداد على مفتاح مهم هو "engines": {"node": "16"}. يحدّد هذا الخيار إصدار Node.js الذي ستستخدمه لكتابة الدوال ونشرها. يمكنك اختيار إصدارات أخرى متوافقة.

استيراد الوحدات المطلوبة وتهيئة تطبيق

بعد إكمال مهام الإعداد، يمكنك فتح دليل المصدر وبدء إضافة الرمز البرمجي كما هو موضّح في الأقسام التالية. بالنسبة إلى هذا النموذج، يجب أن يستورد مشروعك وحدتَي Cloud Functions وAdmin SDK باستخدام عبارات Node require. أضِف أسطرًا مثل ما يلي إلى ملف index.js:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

تعمل هذه الأسطر على تحميل الوحدتَين firebase-functions وfirebase-admin، وتهيئة مثيل تطبيق admin يمكن من خلاله إجراء تغييرات Cloud Firestore. في أي مكان يتوفّر فيه دعم Admin SDK، كما هو الحال مع FCM وAuthentication وFirebase Realtime Database، يوفّر طريقة فعّالة لدمج Firebase باستخدام Cloud Functions.

تثبِّت واجهة سطر الأوامر (CLI) Firebase تلقائيًا حزمة تطوير البرامج (SDK) الخاصة ببرنامج Firebase وحزمة Firebase لوحدات Cloud Functions Node عند بدء مشروعك. لإضافة مكتبات تابعة لجهات خارجية إلى مشروعك، يمكنك تعديل package.json وتشغيل npm install. لمزيد من المعلومات، راجِع مقالة التعامل مع التبعيات.

إضافة الدالة addMessage()

بالنسبة إلى الدالة addMessage()، أضِف الأسطر التالية إلى index.js:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

الدالة addMessage() هي نقطة نهاية HTTP. يؤدي أي طلب إلى نقطة النهاية إلى تمرير كائنَي الطلب والاستجابة بنمط ExpressJS إلى وظيفة رد الاتصال onRequest().

تكون دوال HTTP متزامنة (على غرار الدوال القابلة للاستدعاء)، لذا عليك إرسال رد في أسرع وقت ممكن وتأجيل العمل باستخدام Cloud Firestore. تمرِّر دالة addMessage() HTTP قيمة نصية إلى نقطة نهاية HTTP وتُدرجها في قاعدة البيانات ضمن المسار /messages/:documentId/original.

إضافة الدالة makeUppercase()

بالنسبة إلى الدالة makeUppercase()، أضِف الأسطر التالية إلى index.js:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

يتم تنفيذ الدالة makeUppercase() عند كتابة Cloud Firestore. تحدّد الدالة ref.set المستند الذي سيتم الاستماع إليه. لأسباب متعلّقة بالأداء، يجب أن تكون محدّدًا قدر الإمكان.

تحيط الأقواس المعقوفة، مثل {documentId}، بـ "المَعلمات"، وهي أحرف بدل تعرض البيانات المطابقة في دالة رد الاتصال.

يؤدي Cloud Firestore إلى تفعيل onCreate() كلما تمت إضافة رسائل جديدة.

تنبيه: احرص على تجنُّب أي حالة يؤدي فيها ناتج الدالة إلى إعادة تشغيلها، ما يؤدي إلى إنشاء حلقة لا نهائية، مثل دالة يتم تشغيلها من خلال عمليات كتابة في مستند Cloud Firestore معيّن وتنتهي بالكتابة في المسار نفسه. احرِص أيضًا على كتابة الدوال بطريقة متكررة،

أي أن تؤدي إلى النتيجة نفسها إذا تم تنفيذها عدة مرات لحدث واحد.

تكون الدوال المستندة إلى الأحداث، مثل أحداث Cloud Firestore، غير متزامنة. يجب أن تعرض دالة رد الاتصال إما null أو Object أو Promise. إذا لم تعرض أي بيانات، ستنتهي مهلة الدالة، ما يشير إلى حدوث خطأ، وستتم إعادة المحاولة. اطّلِع على المزامنة وغير المتزامنة والوعود.

محاكاة تنفيذ الدوال

تتيح لك Firebase Local Emulator Suite إنشاء التطبيقات واختبارها على جهازك المحلي بدلاً من نشرها في مشروع على Firebase. ننصح بشدة بإجراء اختبارات محلية أثناء عملية التطوير، وذلك جزئيًا لأنّها تقلّل من خطر حدوث أخطاء في الترميز قد تؤدي إلى تحمّل تكلفة في بيئة الإنتاج (مثل حلقة لا نهائية).

لمحاكاة الدوال، اتّبِع الخطوات التالية:

1. نفِّذ firebase emulators:start وتحقّق من الناتج بحثًا عن عنوان URL الخاص بـ Emulator Suite UI. يكون العنوان التلقائي هو localhost:4000، ولكن قد تتم استضافته على منفذ مختلف على جهازك. أدخِل عنوان URL هذا في المتصفّح لفتح Emulator Suite UI.

2. تحقَّق من ناتج الأمر firebase emulators:start للحصول على عنوان URL لدالة HTTP addMessage(). سيبدو مشابهًا لما يلي: http://localhost:5001/MY_PROJECT/us-central1/addMessage، باستثناء ما يلي:

   1. سيتم استبدال MY_PROJECT برقم تعريف مشروعك.
   2. قد يختلف المنفذ على جهازك المحلي.

3. أضِف سلسلة طلب البحث ?text=uppercaseme إلى نهاية عنوان URL للدالة. من المفترض أن يظهر بالشكل التالي: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. يمكنك اختياريًا تغيير الرسالة "uppercaseme" إلى رسالة مخصّصة.

4. أنشئ رسالة جديدة من خلال فتح عنوان URL في علامة تبويب جديدة في المتصفّح.

5. للاطّلاع على تأثيرات الدوال في Emulator Suite UI، اتّبِع الخطوات التالية:

   1. في علامة التبويب السجلات، يجب أن تظهر سجلات جديدة تشير إلى أنّ الدالتَين addMessage() وmakeUppercase() تم تنفيذهما:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. في علامة التبويب Firestore، من المفترض أن يظهر لك مستند يحتوي على رسالتك الأصلية بالإضافة إلى نسخة من رسالتك بأحرف كبيرة (إذا كانت الرسالة الأصلية هي "uppercaseme"، سيظهر لك "UPPERCASEME").

نشر الدوال في بيئة إنتاج

بعد التأكّد من أنّ الدوال تعمل على النحو المطلوب في المحاكي، يمكنك المتابعة إلى نشرها واختبارها وتشغيلها في بيئة الإنتاج. يُرجى العِلم أنّه لنشر مشروعك في بيئة وقت التشغيل Node.js 14، يجب أن يكون مشروعك ضمن خطة أسعار Blaze. يمكنك الاطّلاع على أسعار Cloud Functions.

لإكمال البرنامج التعليمي، عليك نشر الدوال ثم تنفيذ addMessage() لتشغيل makeUppercase().

1. نفِّذ الأمر التالي لنشر الدوال:

    firebase deploy --only functions
    

   بعد تشغيل هذا الأمر، تعرض واجهة سطر الأوامر Firebase عنوان URL لأي نقاط نهاية لوظائف HTTP. في الوحدة الطرفية، من المفترض أن يظهر لك سطر على النحو التالي:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

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

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

2. باستخدام عنوان URL addMessage() الذي تعرضه واجهة سطر الأوامر، أضِف مَعلمة طلب بحث نصية، وافتحها في المتصفّح:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   يتم تنفيذ الدالة وإعادة توجيه المتصفّح إلى وحدة تحكّم Firebase في موقع قاعدة البيانات حيث يتم تخزين السلسلة النصية. يؤدي حدث الكتابة هذا إلى تفعيل makeUppercase()، الذي يكتب نسخة من السلسلة بأحرف كبيرة.

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

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

ملاحظة: يخضع نشر الدوال من واجهة سطر الأوامر Firebase لحدود المعدّل. اطّلِع على حدود الحصة المتاحة لنشر واجهة سطر الأوامر Firebase.

مراجعة نموذج الرمز الكامل

في ما يلي functions/index.js المكتمل الذي يتضمّن الدالتَين addMessage() وmakeUppercase(). تتيح لك هذه الدوال تمرير مَعلمة إلى نقطة نهاية HTTP تكتب قيمة في Cloud Firestore، ثم تحوّلها عن طريق تحويل جميع الأحرف في السلسلة إلى أحرف كبيرة.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

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

في هذه المستندات، يمكنك التعرّف على مزيد من المعلومات حول كيفية إدارة الدوال في Cloud Functions، بالإضافة إلى كيفية التعامل مع جميع أنواع الأحداث المتوافقة مع Cloud Functions.

للمزيد من المعلومات عن Cloud Functions، يمكنك أيضًا اتّباع الخطوات التالية:

• حالات استخدام Cloud Functions
• جرِّب الدرس التطبيقي حول الترميز Cloud Functions.
• مراجعة نماذج الرموز البرمجية وتشغيلها على GitHub