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

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

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

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

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

إنشاء مشروع على 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 و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.

يُثبِّت 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