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

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

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

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

The following sections of this tutorial detail the steps required to build, test, and deploy the sample. إذا كنت تفضّل تشغيل الرمز وفحصه، انتقِل إلى مراجعة الرمز النموذجي الكامل.

إنشاء مشروع Firebase

إعداد Node.js وFirebase CLI

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

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

npm install -g firebase-tools

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

إعداد مشروعك

عند إعداد حزمة تطوير البرامج (SDK) لـ "Firebase" في "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. تطلب منك واجهة سطر الأوامر اختيار قاعدة رموز برمجية حالية أو إعداد قاعدة جديدة وتسميتها. عند البدء، تكون قاعدة رموز برمجية واحدة في الموقع الجغرافي التلقائي كافية، ولكن مع توسّع عملية التنفيذ، قد تحتاج إلى تنظيم الدوال في قواعد الرموز البرمجية.

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 و"مدير 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 { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

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

تثبِّت واجهة سطر الأوامر في Firebase تلقائيًا حزمة تطوير البرامج (SDK) لكل من Firebase و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 getFirestore()
    .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. يؤدي أي طلب إلى نقطة النهاية إلى تمرير كائنَي Request وResponse بأسلوب 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. ويكون الإعداد التلقائي هو 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 { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
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 getFirestore()
    .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 وتشغيلها