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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

في ما يلي نموذج الرمز البرمجي الكامل الذي يحتوي على الدوال:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

لمحة عن هذا البرنامج التعليمي

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

توضّح الأقسام التالية من هذا البرنامج التعليمي الخطوات المطلوبة لإنشاء النموذج واختباره ونشره.

إنشاء مشروع على Firebase

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

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

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

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

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

4. (اختياري) يمكنك إعداد Google Analytics لمشروعك، ما يتيح تجربة مثالية باستخدام منتجات Firebase التالية: Firebase A/B Testing وCloud Messaging وCrashlytics وIn-App Messaging وRemote Config (بما في ذلك التخصيص).

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

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

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

إعداد البيئة وFirebase CLI

تهيئة مشروعك

عند إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Firebase من أجل Cloud Functions، يمكنك إنشاء مشروع فارغ يحتوي على التبعيات وبعض الرموز النموذجية البسيطة. إذا كنت تستخدم Node.js، يمكنك اختيار 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
   • TypeScript
   • Python

   في هذا البرنامج التعليمي، اختَر JavaScript أو Python. لإنشاء الدوال في TypeScript، راجِع كتابة الدوال باستخدام TypeScript.

6. توفّر واجهة سطر الأوامر خيارًا لتثبيت التبعيات. يمكنك رفض هذا الطلب بأمان إذا كنت تريد إدارة التبعيات بطريقة أخرى.

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

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

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

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

بعد إكمال مهام الإعداد، يمكنك فتح دليل المصدر والبدء في إضافة الرمز كما هو موضّح في الأقسام التالية. بالنسبة إلى هذا النموذج، يجب أن يستورد مشروعك الوحدتَين Cloud Functions وAdmin SDK. أضِف أسطرًا مثل ما يلي إلى ملف المصدر:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

تعمل هذه الأسطر على تحميل الوحدات المطلوبة وتهيئة مثيل admin للتطبيق يمكن إجراء تغييرات Cloud Firestore عليه. في أي مكان يتوفّر فيه دعم Admin SDK، كما هو الحال مع FCM وAuthentication وFirebase Realtime Database، يوفّر طريقة فعّالة لدمج Firebase باستخدام Cloud Functions.

تثبِّت واجهة سطر الأوامر (CLI) تلقائيًا حزمة تطوير البرامج (SDK) الخاصة بخدمة Firebase Admin وحزمة تطوير البرامج (SDK) الخاصة بوحدات Cloud Functions عند إعداد مشروعك.FirebaseFirebase لمزيد من المعلومات حول إضافة مكتبات تابعة لجهات خارجية إلى مشروعك، يُرجى الاطّلاع على التعامل مع التبعيات.

إضافة وظيفة "إضافة رسالة"

بالنسبة إلى وظيفة "إضافة رسالة"، أضِف الأسطر التالية إلى ملف المصدر:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

وظيفة "إضافة رسالة" هي نقطة نهاية HTTP. يؤدي أي طلب إلى نقطة النهاية إلى تمرير عناصر الطلب والاستجابة إلى معالج الطلب الخاص بمنصتك (onRequest() أو on_request).

تكون دوال HTTP متزامنة (على غرار الدوال القابلة للاستدعاء)، لذا عليك إرسال رد في أسرع وقت ممكن وتأجيل العمل باستخدام Cloud Firestore. تمرِّر دالة HTTP الخاصة بـ "إضافة رسالة" قيمة نصية إلى نقطة نهاية HTTP وتُدرجها في قاعدة البيانات ضمن المسار /messages/:documentId/original.

إضافة الدالة "تحويل النص إلى أحرف كبيرة"

بالنسبة إلى الدالة "make uppercase"، أضِف الأسطر التالية إلى ملف المصدر:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

يتم تنفيذ الدالة "make uppercase" عند كتابة Cloud Firestore، ما يحدد المستند الذي سيتم الاستماع إليه. لأسباب متعلّقة بالأداء، يجب أن تكون محدّدًا قدر الإمكان.

تحيط الأقواس المعقوفة، مثل {documentId}، بـ "المَعلمات"، وهي أحرف بدل تعرض البيانات المطابقة في دالة رد الاتصال. يؤدي Cloud Firestore إلى تفعيل دالة الرجوع عند إضافة رسائل جديدة.

في Node.js، تكون الدوال المستندة إلى الأحداث، مثل أحداث 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. سيبدو مشابهًا لما يلي: 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. يمكنك اختياريًا تغيير الرسالة "uppercaseme" إلى رسالة مخصّصة.

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

5. للاطّلاع على تأثيرات الدوال في Emulator Suite UI، اتّبِع الخطوات التالية:

   1. في علامة التبويب السجلّات، من المفترض أن تظهر سجلّات جديدة تشير إلى أنّ دوال HTTP تم تنفيذها بنجاح:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

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

بعد التأكّد من أنّ الدوال تعمل على النحو المطلوب في المحاكي، يمكنك المتابعة إلى نشرها واختبارها وتشغيلها في بيئة الإنتاج. يُرجى العِلم أنّه يجب أن يكون مشروعك ضمن خطة أسعار Blaze كي تتمكّن من نشره في مرحلة الإنتاج. يمكنك الاطّلاع على أسعار Cloud Functions.

لإكمال البرنامج التعليمي، عليك نشر الدوال ثم تنفيذها.

1. نفِّذ الأمر التالي لنشر الدوال:

    firebase deploy --only functions
    

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

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   يحتوي عنوان URL على معرّف مشروعك بالإضافة إلى منطقة لوظيفة HTTP. على الرغم من أنّه ليس عليك القلق بشأن ذلك الآن، يجب أن تحدّد بعض دوال HTTP الخاصة بالإنتاج موقعًا جغرافيًا لتقليل وقت استجابة الشبكة.

   إذا واجهت أخطاء في الوصول، مثل "يتعذّر منح الإذن بالوصول إلى المشروع"، جرِّب التحقّق من تحديد الأسماء المستعارة للمشروع.

2. باستخدام عنوان URL الذي يعرضه CLI، أضِف مَعلمة طلب بحث نصية، وافتحها في متصفّح:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   يتم تنفيذ الدالة وإعادة توجيه المتصفّح إلى وحدة تحكّم Firebase في موقع قاعدة البيانات حيث يتم تخزين السلسلة النصية. يؤدي حدث الكتابة هذا إلى تشغيل الدالة "make uppercase"، التي تكتب نسخة بأحرف كبيرة من السلسلة.

بعد نشر الدوال وتنفيذها، يمكنك عرض السجلات في وحدة تحكّم Google Cloud. إذا كنت بحاجة إلى حذف دوال في مرحلة التطوير أو الإنتاج، استخدِم واجهة سطر الأوامر Firebase.

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

الخطوات اللاحقة

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

للمزيد من المعلومات عن Cloud Functions، يمكنك أيضًا اتّباع الخطوات التالية:

• حالات استخدام Cloud Functions
• جرِّب الدرس التطبيقي حول الترميز Cloud Functions.
• مراجعة نماذج الرموز البرمجية وتشغيلها على GitHub