Catch up on highlights from Firebase at Google I/O 2023. Learn more

ابدأ: اكتب واختبر وانشر وظائفك الأولى


لبدء استخدام وظائف السحابة ، حاول العمل من خلال هذا البرنامج التعليمي ، الذي يبدأ بمهام الإعداد المطلوبة ويعمل من خلال إنشاء واختبار ونشر وظيفتين مرتبطتين:

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

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

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

أنشئ مشروع Firebase

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

    • لإضافة موارد Firebase إلى مشروع Google Cloud موجود ، أدخل اسم المشروع أو حدده من القائمة المنسدلة.

    • لإنشاء مشروع جديد ، أدخل اسم المشروع المطلوب. يمكنك أيضًا تعديل معرّف المشروع المعروض أسفل اسم المشروع اختياريًا.

  2. راجع شروط Firebase واقبلها ، إذا طُلب منك ذلك.

  3. انقر فوق متابعة .

  4. (اختياري) قم بإعداد Google Analytics لمشروعك ، مما يتيح لك الحصول على تجربة مثالية باستخدام أي من منتجات Firebase التالية:

    حدد إما حساب Google Analytics موجود أو لإنشاء حساب جديد.

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

  5. انقر على إنشاء مشروع (أو إضافة Firebase ، إذا كنت تستخدم مشروع Google Cloud موجودًا).

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

قم بإعداد Node.js و Firebase CLI

ستحتاج إلى بيئة Node.js لكتابة الوظائف ، وستحتاج إلى Firebase CLI لنشر الوظائف في وقت تشغيل وظائف السحابة. لتثبيت Node.js و npm ، يوصى بـ Node Version Manager .

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

npm install -g firebase-tools

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

ابدأ مشروعك

عند تهيئة Firebase SDK لوظائف السحابة ، فإنك تنشئ مشروعًا فارغًا يحتوي على بعض التبعيات وبعض نماذج التعليمات البرمجية ، وتختار 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 .

  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 الخاص بك لكتابة الوظائف ونشرها. يمكنك تحديد إصدارات أخرى مدعومة .

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

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

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

// 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 والمصادقة وقاعدة بيانات Firebase Realtime ، فإنه يوفر طريقة قوية لدمج Firebase باستخدام وظائف السحابة.

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

محاكاة تنفيذ المهام الخاصة بك

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

لمحاكاة وظائفك:

  1. تشغيل firebase emulators:start وتحقق من إخراج عنوان URL الخاص بواجهة مستخدم Emulator Suite. يتم تعيينه افتراضيًا على المضيف المحلي: 4000 ، ولكن يمكن استضافته على منفذ مختلف على جهازك. أدخل عنوان URL هذا في متصفحك لفتح واجهة مستخدم Emulator Suite.

  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 . اختياريًا ، يمكنك تغيير الرسالة "الكبيرة" إلى رسالة مخصصة.

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

  5. عرض تأثيرات الوظائف في Emulator Suite UI:

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

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

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

لإكمال البرنامج التعليمي ، انشر وظائفك ثم نفّذ 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");

// 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

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

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

لمعرفة المزيد حول وظائف السحابة ، يمكنك أيضًا القيام بما يلي: