Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

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

  • addMessage() ، الذي يعرض عنوان URL يقبل قيمة نصية addMessage() في Cloud Firestore.
  • makeUppercase() ، الذي يتم makeUppercase() على Cloud Firestore الكتابة وتحويل النص إلى أحرف كبيرة.

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

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

أنشئ مشروع Firebase

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

    إذا كان لديك مشروع Google Cloud Platform (GCP) حالي ، يمكنك تحديد المشروع من القائمة المنسدلة لإضافة موارد Firebase إلى هذا المشروع.

  2. (اختياري) إذا كنت تقوم بإنشاء مشروع جديد ، يمكنك تعديل معرّف المشروع .

    يعيّن Firebase تلقائيًا معرّفًا فريدًا لمشروع Firebase الخاص بك. تفضل بزيارة فهم مشاريع Firebase للتعرف على كيفية استخدام Firebase لمعرف المشروع.

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

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

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

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

يوفر 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 login الدخول عبر المتصفح ومصادقة أداة Firebase.
  2. انتقل إلى دليل مشروع Firebase.
  3. قم بتشغيل firebase init firestore . بالنسبة لهذا البرنامج التعليمي ، يمكنك قبول القيم الافتراضية عند مطالبتك بقواعد Firestore وملفات الفهرس. إذا لم تكن قد استخدمت Cloud Firestore في هذا المشروع حتى الآن ، فستحتاج أيضًا إلى تحديد وضع البدء والموقع لـ Firestore كما هو موضح في بدء استخدام Cloud Firestore .
  4. قم بتشغيل firebase init functions . تمنحك الأداة خيارًا لتثبيت التبعيات باستخدام npm. من الآمن npm install إذا كنت تريد إدارة التبعيات بطريقة أخرى ، على الرغم من أنك إذا npm install فستحتاج إلى تشغيل npm install قبل محاكاة npm install أو نشرها.
  5. تمنحك الأداة خيارين لدعم اللغة:

    بالنسبة لهذا البرنامج التعليمي ، حدد JavaScript .

بعد اكتمال هذه الأوامر بنجاح ، سيبدو هيكل مشروعك كما يلي:

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

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

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

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

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

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

يقوم Firebase CLI تلقائيًا بتثبيت Firebase و Firebase SDK لوحدات عقدة وظائف السحابة عند بدء مشروعك. لإضافة مكتبات npm install لجهات خارجية إلى مشروعك ، يمكنك تعديل package.json وتشغيل npm install . لمزيد من المعلومات ، راجع التعامل مع التبعيات .

أضف وظيفة addMessage()

بالنسبة addMessage() ، أضف هذه الأسطر إلى index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

وظيفة addMessage() هي نقطة نهاية HTTP. ينتج عن أي طلب لنقطة النهاية كائنات طلب واستجابة على نمط ExpressJS تم تمريرها إلى رد الاتصال onRequest() .

وظائف HTTP متزامنة (تشبه الوظائف القابلة للاستدعاء ) ، لذا يجب عليك إرسال استجابة في أسرع وقت ممكن وتأجيل العمل باستخدام Cloud Firestore. addMessage() وظيفة 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

يتم تنفيذ وظيفة makeUppercase() عندما تتم الكتابة إلى Cloud Firestore. تحدد وظيفة ref.set المستند الذي سيتم الاستماع إليه. لأسباب تتعلق بالأداء ، يجب أن تكون محددًا قدر الإمكان.

الأقواس — على سبيل المثال ، {documentId} —إحاطة "المعلمات" ، وأحرف البدل التي تعرض البيانات المتطابقة في رد الاتصال.

يقوم Cloud Firestore بتشغيل رد الاتصال onWrite() كلما تمت كتابة البيانات أو تحديثها في المستند المحدد.

الوظائف التي تعتمد على الأحداث مثل أحداث 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 : http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . اختياريًا ، يمكنك تغيير الرسالة "uppercaseme" إلى رسالة مخصصة.

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

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

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

      وظائف i: بدء تنفيذ "addMessage"

      وظائف i: بدء تنفيذ "makeUppercase"

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

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

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

لإكمال البرنامج التعليمي ، addMessage() ثم قم بتنفيذ 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 ، أضف معلمة استعلام نصي وافتحه في المستعرض:

    رقم 9202735

    تقوم الوظيفة بتنفيذ وإعادة توجيه المتصفح إلى وحدة تحكم Firebase في موقع قاعدة البيانات حيث يتم تخزين السلسلة النصية. مشغلات حدث الكتابة هذه makeUppercase() ، والتي تكتب نسخة كبيرة من السلسلة.

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

مراجعة كود عينة كاملة

فيما يلي functions/index.js المكتملة functions/index.js التي تحتوي على الدالتين addMessage() و makeUppercase() . تسمح لك هذه الوظائف بتمرير معلمة إلى نقطة نهاية HTTP تكتب قيمة إلى Cloud Firestore ، ثم تقوم بتحويلها عن طريق الأحرف الكبيرة في السلسلة.

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

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

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

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

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

فيديو تعليمي

يمكنك معرفة المزيد حول وظائف السحابة من خلال مشاهدة دروس الفيديو. في هذا الفيديو ، ستجد إرشادات تفصيلية حول بدء استخدام وظائف السحابة ، بما في ذلك إعداد Node.js و CLI.