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

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

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

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

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

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

مستخدم جديد في Firebase أو Cloud

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

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

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

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

  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 بنود مشروعك.

  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 بنود مشروعك.

  9. انقر على إضافة Firebase.

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

إعداد Node.js وFirebase CLI

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

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

npm install -g firebase-tools

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

إعداد مشروعك

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

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

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

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

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

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

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

    في هذا البرنامج التعليمي، اختَر 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();

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

تثبِّت واجهة سطر الأوامر Firebase تلقائيًا حزمة تطوير البرامج (SDK) الخاصة بـ Firebase وحزمة تطوير البرامج (SDK) الخاصة بـ Firebase لوحدات Node عند إعداد مشروعك.Cloud Functions لإضافة مكتبات تابعة لجهات خارجية إلى مشروعك، يمكنك تعديل 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.` });
});

الدالة 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 });
  });

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

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

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

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

تكون الدوال المستندة إلى الأحداث، مثل أحداث 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.

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

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

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

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

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

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