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

الجيل الثاني الجيل الأول

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

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

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

ملاحظة: يمكنك محاكاة الدوال في أي مشروع على Firebase، ولكن يمكنك تفعيل هذه الميزة. مع بيئة وقت تشغيل Node.js 14 الموصى بها، سيعمل مشروعك أن يكون ضِمن خطة أسعار Blaze عرض أسعار Cloud Functions

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

إنشاء مشروع Firebase

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

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

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

     تنشئ منصّة Firebase معرّفًا فريدًا لمشروعك على Firebase. بناءً على الاسم الذي تُطلقه عليه. إذا أردت تعديل رقم تعريف المشروع هذا، عليك فعل ذلك الآن حيث لا يمكن تغييره بعد أن يتولى Firebase توفير الموارد مشروعك. زيارة الموقع فهم مشاريع Firebase من أجل ومعرفة كيفية استخدام Firebase لرقم تعريف المشروع.

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

3. انقر على متابعة.

4. (اختياري) يمكنك إعداد "إحصاءات Google" لمشروعك، ما تمكّنك من للحصول على أفضل تجربة باستخدام أيٍّ من منتجات Firebase التالية:

   أداة Firebase Crashlytics المراسلة عبر السحابة الإلكترونية من Firebase

   المراسلة داخل التطبيق من Firebase الإعداد عن بُعد في Firebase

   التخصيص في ميزة "الإعداد عن بُعد" اختبار A/B من Firebase

   يمكنك تحديد إما حساب "إحصاءات Google" أو إنشاء حساب جديد.

   إذا أنشأت حسابًا جديدًا، اختَر موقع إعداد تقارير "إحصاءات Google"، ثم قبول إعدادات مشاركة البيانات وبنود "إحصاءات Google" لمشروعك.

   يمكنك إعداد "إحصاءات Google" في أي وقت لاحقًا في عمليات الدمج علامة التبويب في إعدادات المشروع.

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

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

إعداد Node.js وواجهة سطر الأوامر في Firebase

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

ملاحظة مهمة: الإصدار 14 و16 من Node.js متاح عرض ضبط خيارات بيئة التشغيل لـ معلومات مهمة بشأن الدعم المستمر لهذه الإصدارات من Node.js.

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

npm install -g firebase-tools

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

في كثير من الحالات، تكون الميزات الجديدة وإصلاحات الأخطاء لا تتوفر إلا مع أحدث إصدار من واجهة سطر الأوامر في Firebase حزمة تطوير البرامج (SDK) firebase-functions إنها ممارسة جيدة تحديث واجهة سطر الأوامر لـ Firebase وحزمة تطوير البرامج (SDK) باستخدام هذين الأمرين داخل المجلد functions في مشروع Firebase:

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

إعداد مشروعك

عند إعداد حزمة تطوير البرامج (SDK) لمنصّة Firebase لوظائف السحابة الإلكترونية، يمكنك إنشاء مشروع فارغ. تحتوي على تبعيات وبعض الحد الأدنى من نموذج التعليمات البرمجية، وعليك اختيار إما TypeScript أو JavaScript لإنشاء الدوال. لأغراض هذه المعلومات البرنامج التعليمي، ستحتاج أيضًا إلى تهيئة Cloud Firestore.

لتهيئة مشروعك:

1. شغِّل firebase login لتسجيل الدخول عبر المتصفح ومصادقة واجهة سطر الأوامر في Firebase
2. انتقِل إلى دليل مشروع Firebase.
3. تشغيل firebase init firestore في هذا الدليل التعليمي، يمكنك قبول الإعدادات الافتراضية عندما يُطلب منك إدخال قواعد Firestore وملفات الفهرس. إذا لم تكن قد استخدمت في هذا المشروع حتى الآن، يمكنك أيضًا يجب تحديد وضع البدء والموقع الجغرافي لـ Firestore كما هو موضح في بدء استخدام Cloud Firestore
4. تشغيل firebase init functions يطلب منك واجهة سطر الأوامر اختيار ملف أو تهيئة قاعدة جديدة وتسميتها. عندما تبدأ للتو، يكفي توفُّر قاعدة رموز برمجية واحدة في الموقع الجغرافي التلقائي لاحقًا، ومع توسّع نطاق عملية التنفيذ، قد تريد تنظيم الدوال في قواعد الرموز.

5. يمنحك واجهة سطر الأوامر خيارين للحصول على دعم اللغة:

   • JavaScript
   • نوع النص البرمجي راجِع كتابة الدوال باستخدام 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 وAdmin 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 والمصادقة وقاعدة بيانات Firebase في الوقت الفعلي، فإنها توفر وهي طريقة فعّالة لدمج Firebase باستخدام دوال السحابة.

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

وتكون الدوال التي تعتمد على الأحداث مثل أحداث Cloud Firestore غير متزامن. يجب أن تعرض دالة الاستدعاء إما null أو Object أو وعد. إذا لم تقم بإرجاع أي شيء، تنتهي المهلة المحددة للدالة، مما يشير إلى وجود خطأ، تمت إعادة المحاولة. يمكنك الاطّلاع على القسم المزامنة غير المتزامنة والوعود.

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

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

لمحاكاة الدوال:

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

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:

   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

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

ملاحظة: يخضع نشر الوظائف من واجهة سطر الأوامر في Firebase لحدود المعدّل. اطّلِع على حدود الحصة لنشر واجهة سطر الأوامر في 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 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.

لمعرفة المزيد عن دوال السحابة، يمكنك أيضًا إجراء ما يلي:

• يمكنك الاطّلاع على حالات الاستخدام لوظائف السحابة الإلكترونية.
• يمكنك تجربة الدرس التطبيقي حول ترميز دوال Cloud.
• مراجعة عيّنات التعليمات البرمجية على GitHub وتشغيلها