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


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

  • وظيفة "إضافة رسالة" تعرض عنوان 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 لنشر الوظائف في وقت تشغيل Cloud Functions. لتثبيت Node.js و npm ، يوصى باستخدام Node Version Manager .

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

npm install -g firebase-tools

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

تهيئة مشروعك

عندما تقوم بتهيئة Firebase SDK for 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 .

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

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

  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 بإخراج عنوان 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 . إذا كنت بحاجة إلى حذف وظائف في التطوير أو الإنتاج، فاستخدم 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.

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