شروع به کار: نوشتن، آزمایش، و استقرار اولین توابع

برای شروع کار با Cloud Functions، این آموزش گام‌به‌گام را دنبال کنید که با وظایف راه‌اندازی الزامی شروع می‌شود و به ایجاد، آزمایش، و استقرار دو تابع مرتبط می‌رسد:

• تابعی برای «افزودن پیام» که نشانی وبی را آشکار می‌کند که مقدار نوشتاری را می‌پذیرد و آن را در 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/https");
const {onDocumentCreated} = require("firebase-functions/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

راه‌اندازی محیط و «واسط خط فرمان Firebase»

پروژه‌تان را مقداردهی اولیه کنید

وقتی کیت توسعه نرم‌افزار Firebase را برای Cloud Functions مقداردهی اولیه می‌کنید، پروژه خالی‌ای ایجاد می‌کنید که حاوی وابستگی‌ها و مقداری کد نمونه حداقلی است. اگر از Node.js استفاده می‌کنید، می‌توانید برای نوشتن توابع، TypeScript یا JavaScript را انتخاب کنید. برای اهداف این آموزش گام‌به‌گام، باید Cloud Firestore را نیز مقداردهی اولیه کنید.

برای مقداردهی اولیه پروژه:

1. برای ورود به سیستم ازطریق مرورگر و اصالت‌سنجی Firebase CLI، firebase login را اجرا کنید.
2. به فهرست پروژه Firebase خود بروید.
3. ‫firebase init firestore را اجرا کنید. برای این آموزش گام‌به‌گام، وقتی از شما خواسته شد مقادیر پیش‌فرض را برای قوانین Firestore و فایل‌های نمایه‌گذاری بپذیرید. اگر هنوز از Cloud Firestore در این پروژه استفاده نکرده‌اید، باید حالت شروع و مکان Firestore را نیز همان‌طور که در شروع به کار با Cloud Firestore توضیح داده شده است انتخاب کنید.
4. ‫firebase init functions را اجرا کنید. «میانای خط فرمان» از شما می‌خواهد پایگاه کد موجودی را انتخاب کنید یا پایگاه کد جدیدی را مقداردهی اولیه و نام‌گذاری کنید. وقتی تازه شروع کرده‌اید، یک پایگاه کد در مکان پیش‌فرض کافی است؛ بعداً، با گسترش پیاده‌سازی‌تان، ممکن است بخواهید کارکردها را در پایگاه‌های کد سازمان‌دهی کنید.

5. «رابط خط فرمان» این گزینه‌ها را برای پشتیبانی از زبان دراختیارتان قرار می‌دهد:

   • جاوا اسکریپت
   • TypeScript
   • پایتون

   برای این آموزش گام‌به‌گام، 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 و واحدهای «کیت توسعه نرم‌افزار سرپرست» را وارد کند. خطوطی مانند خطوط زیر را به فایل منبع خود اضافه کنید:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/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 ارائه می‌دهد.

وقتی پروژه‌تان را مقداردهی اولیه می‌کنید، Firebase CLI به‌طور خودکار ‫Firebase Admin SDK و Firebase SDK را برای Cloud Functions واحد نصب می‌کند. برای اطلاعات بیشتر درباره افزودن کتابخانه‌های طرف سوم به پروژه، مدیریت وابستگی‌ها را ببینید.

افزودن تابع «افزودن پیام»

برای عملکرد «افزودن پیام»، این خطوط را به فایل منبع خود اضافه کنید:

// 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 درج می‌کند.

افزودن تابع «حروف بزرگ»

برای تابع «تبدیل به حروف بزرگ»، این خطوط را به فایل منبع خود اضافه کنید:

// 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

وقتی Cloud Firestore در آن نوشته می‌شود، تابع «حروف بزرگ» اجرا می‌شود و سندی را که باید به آن گوش داده شود تعریف می‌کند. به‌دلایل عملکردی، باید تا حد امکان دقیق باشید.

آکولاد—برای مثال، {documentId}—«پارامترها» و نویسه‌های عام را که داده‌های منطبق خود را در فراخوانی متقابل آشکار می‌کنند دربرمی‌گیرد. هرگاه پیام‌های جدید اضافه شود، Cloud Firestore بازخوان را راه‌اندازی می‌کند.

در Node.js، توابع رویدادمحور مثل رویدادهای Cloud Firestore ناهم‌زمان هستند. تابع فراخوانی متقابل باید null، «شیء»، یا وعده برگرداند. اگر چیزی برنگردانید، عملکرد زمان‌دار می‌شود، خطا را نشان می‌دهد، و دوباره امتحان می‌شود. همگام‌سازی، غیرهمگام‌سازی، و وعده‌ها را ببینید.

شبیه‌سازی اجرای توابع

این Firebase Local Emulator Suite به شما امکان می‌دهد برنامه‌ها را در ماشین محلی خود بسازید و آزمایش کنید، به‌جای اینکه آن‌ها را در پروژه Firebase مستقر کنید. آزمایش محلی درطول توسعه به‌شدت توصیه می‌شود، تا حدی به این دلیل که خطر خطاهای کدنویسی را که می‌تواند به‌طور بالقوه در محیط تولید هزینه ایجاد کند (برای مثال، حلقه بی‌نهایت) کاهش می‌دهد.

برای شبیه‌سازی کردن توابع:

1. ‫firebase emulators:start را اجرا کنید و برونداد را برای نشانی وب Emulator Suite UI بررسی کنید. به‌طور پیش‌فرض روی localhost:4000 تنظیم می‌شود، اما ممکن است در درگاه دیگری در ماشینتان میزبانی شود. آن نشانی وب را در مرورگرتان وارد کنید تا Emulator Suite UI باز شود.

2. برونداد فرمان firebase emulators:start را برای نشانی وب تابع HTTP بررسی کنید. شبیه به http://localhost:5001/MY_PROJECT/us-central1/addMessage خواهد بود، با این تفاوت که:

   1. ‫MY_PROJECT با شناسه پروژه شما جایگزین خواهد شد.
   2. در ماشین محلی شما ممکن است درگاه متفاوت باشد.

3. رشته پُرسمان ?text=uppercaseme را به انتهای نشانی وب تابع اضافه کنید. این باید چیزی شبیه به این باشد: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. به‌صورت اختیاری، می‌توانید پیام «uppercaseme» را به پیام سفارشی تغییر دهید.

4. با باز کردن نشانی وب در زبانه جدید در مرورگرتان، پیام جدیدی ایجاد کنید.

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 CLI نشانی وب را برای هر نقطه پایانی تابع HTTP برونداد می‌کند. در ترمینال خود، باید خطی مانند خط زیر را ببینید:

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

   نشانی وب حاوی شناسه پروژه شما و همچنین منطقه‌ای برای تابع HTTP است. اگرچه اکنون نیازی نیست نگران آن باشید، برخی‌از توابع تولید HTTP باید مکان را برای به‌حداقل رساندن تأخیر شبکه مشخص کنند.

   اگر با خطاهای دسترسی مثل «دسترسی به پروژه مجاز نیست» مواجه شدید، نام مستعار پروژه را بررسی کنید.

2. بااستفاده از برونداد نشانی وب توسط CLI، پارامتر پُرسمان نوشتاری اضافه کنید، و آن را در مرورگر باز کنید:

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

   این تابع اجرا می‌شود و مرورگر را به کنسول Firebase در مکان پایگاه داده‌ای که رشته نوشتاری در آن ذخیره شده است هدایت می‌کند. این رویداد نوشتن تابع «تبدیل به حروف بزرگ» را راه‌اندازی می‌کند که نسخه حروف بزرگ رشته را می‌نویسد.

پس‌از استقرار و اجرای توابع، می‌توانید گزارش‌ها را در Google Cloud کنسول مشاهده کنید. اگر نیاز دارید توابع را حذف کنید در توسعه یا تولید، از Firebase CLI استفاده کنید.

در مرحله تولید، ممکن است بخواهید عملکرد تابع را بهینه‌سازی کنید و با تنظیم حداقل و حداکثر تعداد نمونه‌های درحال اجرا، هزینه‌ها را کنترل کنید. برای اطلاعات بیشتر درباره این گزینه‌های زمان اجرا، کنترل رفتار مقیاس‌بندی را ببینید.

مراحل بعدی

در این مستندات، می‌توانید درباره نحوه مدیریت توابع برای Cloud Functions و همچنین نحوه مدیریت همه انواع رویداد پشتیبانی‌شده توسط Cloud Functions بیشتر بدانید.

برای کسب اطلاعات بیشتر درباره Cloud Functions، می‌توانید کارهای زیر را نیز انجام دهید:

• درباره موارد استفاده از Cloud Functions بخوانید.
• ‫Cloud Functions codelab را امتحان کنید.
• نمونه‌های کد در GitHub را مرور و اجرا کنید