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

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

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

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

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

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

إعداد Node.js وFirebase CLI

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

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

npm install -g firebase-tools

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

إعداد مشروعك

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

لإعداد مشروعكم، يُرجى اتّباع الخطوات التالية:

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

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

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

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

5. يمنحكم CLI الخيارات التالية لدعم اللغة:

   • JavaScript
   • Python
   • TypeScript يُرجى الاطّلاع على مقالة كتابة الدوال باستخدام TypeScript لمزيد من المعلومات.

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

6. يمنحكم CLI خيار تثبيت التبعيات باستخدام 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 ومدير 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. حيثما يتوفّر دعم مدير SDK، كما هو الحال في FCM وAuthentication وFirebase Realtime Database، يوفّر طريقة فعّالة لدمج Firebase باستخدام Cloud Functions.

يُثبِّت Firebase CLI تلقائيًا وحدتَي Firebase وFirebase SDK لـ 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. تُمرِّر دالة HTTP addMessage() قيمة نصية إلى نقطة نهاية 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، غير متزامنة. يجب أن تعرض دالّة رد الاتصال إما null أو كائنًا، أو عمليّة غير مكتملة. إذا لم تعرضوا أي شيء، تنتهي مهلة الدالة، ما يشير إلى حدوث خطأ، ويتم إعادة محاولة تنفيذها. يُرجى الاطّلاع على مقالة الدوال المتزامنة وغير المتزامنة والوعود.

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

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

لمحاكاة الدوال، يُرجى اتّباع الخطوات التالية:

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

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

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

3. أضيفوا سلسلة طلب البحث ?text=uppercaseme إلى نهاية عنوان URL للدالة. يجب أن يبدو عنوان 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 CLI عنوان URL لأي نقاط نهاية لدوال HTTP. في الوحدة الطرفية، من المفترض أن يظهر لكم سطر مثل ما يلي:

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

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

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

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

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

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

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

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

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

في ما يلي ملف 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