لبدء استخدام Cloud Functions، جرِّب الاطّلاع على هذا الدليل التوجيهي، والذي يبدأ بمهام الإعداد المطلوبة ويعمل من خلال الإنشاء والاختبار ونشر دالتَين مرتبطتَين، وهما:
- دالة "إضافة رسالة" تعرض عنوان URL يقبل قيمة نصية ويكتبها في Cloud Firestore.
- دالة "make uppercase" التي يتم تفعيلها عند كتابة Cloud Firestore وتحوِّل النص إلى أحرف كبيرة
لقد اخترنا دالات JavaScript التي يتم تشغيلها عبر HTTP وCloud Firestore لهذا الغرض أخذ عيّنة منه جزئيًا لأنّ هذه العوامل المُشغِّلة في الخلفية يمكن اختبارها بدقة من خلال Firebase Local Emulator Suite. تتيح مجموعة الأدوات هذه أيضًا استخدام Realtime Database وPubSub وAuth وHTTP للتشغيل. يمكن اختبار الأنواع الأخرى من مشغّلات الخلفية، مثل مشغّلات Remote Config وTestLab و"إحصاءات Google"، بشكل تفاعلي باستخدام مجموعات أدوات غير описанة في هذه الصفحة.
توضح الأقسام التالية من هذا البرنامج التعليمي الخطوات المطلوبة لإنشاء واختبارها ونشر العينة. إذا كنت تفضل فقط تشغيل التعليمة البرمجية وفحصها، انتقِل إلى مراجعة نموذج الرمز الكامل.
إنشاء مشروع على Firebase
-
في وحدة تحكُّم Firebase، انقر على إضافة مشروع.
-
لإضافة موارد Firebase إلى مشروع Google Cloud حالي، أدخِل اسم المشروع أو حدده من القائمة المنسدلة.
-
لإنشاء مشروع جديد، أدخِل اسم المشروع المطلوب. يمكنك أيضًا اختيار تعديل رقم تعريف المشروع المعروض أسفل اسم المشروع.
-
-
راجِع بنود Firebase واقبلها إذا طُلب منك ذلك.
-
انقر على متابعة.
-
(اختياري) يمكنك إعداد Google Analytics لمشروعك، والتي تمكّنك من للحصول على أفضل تجربة باستخدام أيٍّ من منتجات Firebase التالية:
يمكنك تحديد إما حساب Google Analytics أو إنشاء حساب جديد.
إذا أنشأت حسابًا جديدًا، اختَر الإبلاغ عن موقع جغرافي واحد (Analytics)، ثم قبول إعدادات مشاركة البيانات وبنود Google Analytics لمشروعك.
-
انقر على إنشاء مشروع (أو إضافة 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
، يُرجى إعادة تنفيذ الأمر نفسه.
بدء مشروعك
عند إعداد حزمة تطوير برامج Firebase SDK لنظام التشغيل Cloud Functions، يمكنك إنشاء مشروع فارغ يحتوي على تبعيات وبعض النماذج البسيطة من الرموز البرمجية، ويمكنك اختيار TypeScript أو JavaScript لإنشاء الدوالّ. لأغراض هذه المعلومات برنامج تعليمي، ستحتاج أيضًا إلى تهيئة Cloud Firestore.
لتهيئة مشروعك:
- شغِّل
firebase login
لتسجيل الدخول عبر المتصفح ومصادقة واجهة سطر الأوامر Firebase. - انتقِل إلى دليل مشروع Firebase.
- شغِّل
firebase init firestore
. في هذا الدليل التعليمي، يمكنك قبول الإعدادات الافتراضية عندما يُطلب منك إدخال قواعد Firestore وملفات الفهرس. إذا لم تكن قد استخدمت Cloud Firestore في هذا المشروع حتى الآن، بالإضافة إلى يجب تحديد وضع البدء والموقع الجغرافي لـ Firestore كما هو موضح في بدء استخدام "Cloud Firestore" - تشغيل
firebase init functions
يطلب منك واجهة سطر الأوامر اختيار ملف أو تهيئة قاعدة جديدة وتسميتها. عند البدء للتو، يكفي استخدام قاعدة بيانات واحدة في الموقع التلقائي. ولاحقًا، مع توسيع نطاق التنفيذ، قد تحتاج إلى تنظيم الدوالّ في قواعد البيانات. يمنحك واجهة سطر الأوامر خيارين للحصول على دعم اللغة:
- JavaScript
- TypeScript اطّلِع على كتابة الدوالّ باستخدام TypeScript لمزيد من المعلومات.
في هذا البرنامج التعليمي، اختَر JavaScript.
يوفّر لك 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();
تحمِّل هذه الأسطر وحدتَي 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.` }); });
الدالة addMessage()
هي نقطة نهاية HTTP. يؤدي أي طلب إلى نقطة النهاية
إلى إنشاء كائنَي Request وResponse
بأسلوب 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 }); });
يتم تنفيذ الدالة makeUppercase()
عند الكتابة إلى Cloud Firestore. تشير رسالة الأشكال البيانية
دالة ref.set
ويحدد المستند الذي تريد الاستماع إليه. لأسباب تتعلّق بالأداء، يجب
أن تكون دقيقًا قدر الإمكان.
تحيط الأقواس، مثل {documentId}
، بـ "المَعلمات"، وهي العناصر النائبة
التي تعرض بياناتها المطابقة في دالة "مكالمة إعادة الاتصال".
يُشغِّل Cloud Firestore دالة callback
onCreate()
عند إضافة رسائل جديدة.
الدوال المستندة إلى الأحداث، مثل أحداث Cloud Firestore، هي
غير متزامنة. يجب أن تعرض دالة الاستدعاء إما null
أو Object
أو وعد.
إذا لم تقم بإرجاع أي شيء، تنتهي المهلة المحددة للدالة، مما يشير إلى وجود خطأ،
تمت إعادة المحاولة. اطّلِع على Sync وAsync وPromises.
محاكاة تنفيذ الدوال
يتيح لك IDE Firebase Local Emulator Suite إنشاء التطبيقات واختبارها على جهازك المحلي بدلاً من نشرها على مشروع على Firebase. ننصح بشدة بإجراء الاختبار على الجهاز أثناء التطوير، ويعود السبب في ذلك جزئيًا إلى أنّه يقلل من خطر أخطاء الترميز التي قد تؤدي إلى تحمُّل تكلفة في بيئة الإنتاج (على سبيل المثال، حلقة لا نهائية).
لمحاكاة الدوال:
شغِّل
firebase emulators:start
وتحقَّق من نتائج عنوان URL من Emulator Suite UI. الإعداد التلقائي هو localhost:4000، ولكن قد يتم استضافته على منفذ مختلف على جهازك. أدخِل عنوان URL هذا في المتصفّح لفتح Emulator Suite UIتحقَّق من ناتج الأمر
firebase emulators:start
لعنوان URL لدالة HTTPaddMessage()
. سيبدو مشابهًا لرمزhttp://localhost:5001/MY_PROJECT/us-central1/addMessage
، باستثناء ما يلي:- سيتم استبدال
MY_PROJECT
برقم تعريف مشروعك. - قد يختلف المنفذ على جهازك المحلي.
- سيتم استبدال
أضِف سلسلة طلب البحث
?text=uppercaseme
إلى نهاية عنوان URL للدالة. من المفترض أن يظهر المحتوى بالشكل التالي:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. يمكنك اختياريًا تغيير الرسالة "أحرف كبيرة" إلى نطاق مخصّص .أنشئ رسالة جديدة من خلال فتح عنوان URL في علامة تبويب جديدة في المتصفّح.
يمكنك الاطّلاع على تأثيرات الدوالّ في Emulator Suite UI:
في علامة التبويب السجّلات، من المفترض أن تظهر لك سجلّات جديدة تشير إلى تشغيل الدالتَين
addMessage()
وmakeUppercase()
:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
في علامة التبويب Firestore، من المفترض أن يظهر لك مستند يحتوي على رسالتك الأصلية بالإضافة إلى النسخة بأحرف كبيرة من رسالتك (إذا كانت في الأصل "uppercaseme"، ستظهر لك "UPPERCASEME").
نشر الدوال في بيئة إنتاج
بعد أن تعمل الدوال على النحو المطلوب في المحاكي، يمكنك المتابعة إلى ونشرها واختبارها وتشغيلها في بيئة الإنتاج. ملاحظات يجب أخذها في الاعتبار لنشره في بيئة وقت تشغيل Node.js 14 الموصى بها، يجب أن يكون أن يكون مشتركًا في خطة أسعار Blaze اطّلِع على أسعار Cloud Functions.
لإكمال البرنامج التعليمي، عليك نشر دوالّك ثم تنفيذ addMessage()
لتشغيل makeUppercase()
.
نفِّذ الأمر التالي لنشر الدوال:
firebase deploy --only functions
بعد تنفيذ هذا الأمر، تُخرج واجهة سطر أوامر Firebase عنوان URL لأي نقاط نهاية لوظائف HTTP . في الوحدة الطرفية، من المفترض أن يظهر خط مثل ما يلي:
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
يحتوي عنوان URL على معرّف مشروعك بالإضافة إلى منطقة لوظيفة HTTP . على الرغم من أنه ليس هناك داعٍ للقلق حيال هذا الأمر الآن، إلا أن بعض بروتوكولات HTTP الخاصة بالإنتاج الدوال يجب أن تحدد موقعًا تقليل وقت استجابة الشبكة إلى أدنى حد.
إذا واجهت أخطاء في الوصول مثل "تعذّر تفويض الوصول إلى project"، حاوِل التحقّق من الاسم المعرِّف للمشروع.
باستخدام ناتج عنوان 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 }); });
الخطوات التالية
في هذه الوثائق، يمكنك معرفة المزيد حول كيفية إدارة الدوال في Cloud Functions بالإضافة إلى كيفية لمعالجة جميع أنواع الأحداث المتوافقة مع "Cloud Functions".
للاطّلاع على مزيد من المعلومات عن Cloud Functions، يمكنك أيضًا إجراء ما يلي:
- اطّلِع على حالات استخدام Cloud Functions.
- جرِّب الدرس التطبيقي حول الترميز Cloud Functions.
- مراجعة عيّنات التعليمات البرمجية على GitHub وتشغيلها