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


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

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

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

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

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

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

بعد تثبيت Node.js وnpm، تثبيت واجهة سطر الأوامر 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.

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

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

تشير رسالة الأشكال البيانية 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 يمكنك اختياريًا تغيير الرسالة "أحرف كبيرة" إلى نطاق مخصّص .

  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 عرض أسعار "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 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، يمكنك أيضًا إجراء ما يلي: