این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شروع کنید: اولین توابع خود را بنویسید، آزمایش کنید و اجرا کنید

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

یک تابع "افزودن پیام" که نشانی اینترنتی را نشان می دهد که یک مقدار متنی را می پذیرد و آن را در Cloud Firestore می نویسد.
یک تابع "make uppercase" که در Cloud Firestore رایت می کند و متن را به حروف بزرگ تبدیل می کند.

در اینجا کد نمونه کامل حاوی توابع است:

Node.js

// 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-triggered را برای این نمونه انتخاب کرده‌ایم زیرا این محرک‌های پس‌زمینه را می‌توان به‌طور کامل از طریق Firebase Local Emulator Suite آزمایش کرد. این مجموعه ابزار همچنین از Realtime Database ، Cloud Storage ، PubSub، Auth و راه‌اندازهای قابل تماس HTTP پشتیبانی می‌کند. انواع دیگر محرک‌های پس‌زمینه مانند راه‌اندازهای Remote Config و TestLab را می‌توان به صورت تعاملی با استفاده از مجموعه ابزارهایی که در این صفحه توضیح داده نشده است، آزمایش کرد .

بخش‌های بعدی این آموزش به جزئیات مراحل مورد نیاز برای ساخت، آزمایش و استقرار نمونه می‌پردازد.

یک پروژه Firebase ایجاد کنید

در کنسول Firebase ، روی افزودن پروژه کلیک کنید.
- برای افزودن منابع Firebase به پروژه Google Cloud موجود ، نام پروژه آن را وارد کنید یا آن را از منوی کشویی انتخاب کنید.
- برای ایجاد یک پروژه جدید، نام پروژه مورد نظر را وارد کنید. همچنین می توانید به صورت اختیاری شناسه پروژه نمایش داده شده در زیر نام پروژه را ویرایش کنید.
  Firebase یک شناسه منحصر به فرد برای پروژه Firebase شما بر اساس نامی که به آن می‌دهید ایجاد می‌کند. اگر می‌خواهید این شناسه پروژه را ویرایش کنید، باید این کار را هم‌اکنون انجام دهید زیرا پس از تهیه منابع Firebase برای پروژه شما، نمی‌توان آن را تغییر داد. برای آشنایی با نحوه استفاده Firebase از ID پروژه، از Understand Firebase Projects دیدن کنید.
در صورت درخواست، شرایط Firebase را بررسی کرده و بپذیرید.
روی Continue کلیک کنید.
(اختیاری) Google Analytics برای پروژه خود راه اندازی کنید، که به شما امکان می دهد با استفاده از هر یک از محصولات Firebase زیر تجربه ای بهینه داشته باشید:
Firebase Crashlytics
Firebase Cloud Messaging
Firebase In-App Messaging
Firebase Remote Config
شخصی سازی Remote Config
Firebase A/B Testing
یا یک حساب Google Analytics موجود را انتخاب کنید یا یک حساب جدید ایجاد کنید.
اگر حساب جدیدی ایجاد می‌کنید، مکان گزارش Analytics خود را انتخاب کنید، سپس تنظیمات اشتراک‌گذاری داده و شرایط Google Analytics را برای پروژه خود بپذیرید.
همیشه می توانید Google Analytics بعداً در برگه ادغام تنظیمات پروژه خود راه اندازی کنید.
روی ایجاد پروژه (یا افزودن Firebase ، اگر از پروژه Google Cloud موجود استفاده می کنید) کلیک کنید.

Firebase به طور خودکار منابع پروژه Firebase شما را فراهم می کند. پس از تکمیل فرآیند، به صفحه نمای کلی پروژه Firebase خود در کنسول Firebase هدایت خواهید شد.

محیط خود و Firebase CLI را تنظیم کنید

Node.js

برای نوشتن توابع به یک محیط Node.js نیاز دارید و برای استقرار توابع در زمان اجرای Cloud Functions به Firebase CLI نیاز دارید. برای نصب Node.js و npm ، Node Version Manager توصیه می شود.

هنگامی که Node.js و npm را نصب کردید، Firebase CLI را از طریق روش دلخواه خود نصب کنید . برای نصب CLI از طریق npm از:

npm install -g firebase-tools

این دستور firebase در سطح جهانی را نصب می کند. اگر دستور ناموفق باشد، ممکن است لازم باشد مجوزهای npm را تغییر دهید . برای به روز رسانی به آخرین نسخه firebase-tools ، همان دستور را دوباره اجرا کنید.

پایتون

برای نوشتن توابع به یک محیط پایتون نیاز دارید و برای استقرار توابع در زمان اجرا Cloud Functions به Firebase CLI نیاز دارید. توصیه می کنیم از venv برای جداسازی وابستگی ها استفاده کنید. نسخه های 3.10 و 3.11 پایتون پشتیبانی می شوند.

پس از نصب پایتون، Firebase CLI را از طریق روش دلخواه خود نصب کنید .

پروژه خود را راه اندازی کنید

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

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

firebase login اجرا کنید تا از طریق مرورگر وارد شوید و Firebase CLI را احراز هویت کنید.
به فهرست پروژه Firebase خود بروید.
firebase init firestore اجرا کنید. برای این آموزش، می‌توانید مقادیر پیش‌فرض را زمانی که قوانین Firestore و فایل‌های فهرست از شما خواسته می‌شود، بپذیرید. اگر هنوز از Cloud Firestore در این پروژه استفاده نکرده‌اید، باید حالت شروع و موقعیت مکانی را برای Firestore انتخاب کنید، همانطور که در شروع با Cloud Firestore توضیح داده شده است.
firebase init functions اجرا کنید. CLI از شما می خواهد که یک پایگاه کد موجود را انتخاب کنید یا یک کد جدید را مقداردهی اولیه کرده و نامگذاری کنید. هنگامی که تازه شروع کرده اید، یک پایگاه کد واحد در مکان پیش فرض کافی است. بعداً، با گسترش پیاده سازی شما، ممکن است بخواهید توابع را در پایگاه های کد سازماندهی کنید .
CLI این گزینه ها را برای پشتیبانی زبان در اختیار شما قرار می دهد:
- جاوا اسکریپت
- TypeScript
- پایتون
برای این آموزش، جاوا اسکریپت یا پایتون را انتخاب کنید. برای نوشتن در TypeScript، به Write Functions with TypeScript مراجعه کنید.
CLI به شما گزینه ای برای نصب وابستگی ها می دهد. اگر می‌خواهید وابستگی‌ها را به روش دیگری مدیریت کنید، رد کردن آن بی‌خطر است.

پس از تکمیل موفقیت آمیز این دستورات، ساختار پروژه شما به شکل زیر است:

Node.js

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

برای Node.js، فایل package.json ایجاد شده در حین تنظیم اولیه حاوی یک کلید مهم است: "engines": {"node": "18"} . این نسخه Node.js شما را برای نوشتن و استقرار توابع مشخص می کند. می توانید سایر نسخه های پشتیبانی شده را انتخاب کنید .

پایتون

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 را وارد کند. خطوطی مانند زیر را به فایل منبع خود اضافه کنید:

Node.js

// 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 ارائه می دهد.

Firebase CLI به طور خودکار Firebase Admin SDK و Firebase SDK for Cloud Functions را هنگامی که پروژه خود را مقداردهی اولیه می کنید نصب می کند. برای اطلاعات بیشتر در مورد افزودن کتابخانه های شخص ثالث به پروژه خود، به Handle Dependencies مراجعه کنید.

تابع "افزودن پیام" را اضافه کنید

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

Node.js

// 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 "add message" یک مقدار متنی را به نقطه پایانی HTTP ارسال می کند و آن را در پایگاه داده تحت مسیر /messages/:documentId/original وارد می کند.

تابع "make uppercase" را اضافه کنید

برای تابع "make uppercase"، این خطوط را به فایل منبع خود اضافه کنید:

Node.js

// 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 ناهمزمان هستند. تابع callback باید null ، Object یا Promise را برگرداند. اگر چیزی را برنگردانید، زمان عملکرد به پایان می رسد و یک خطا را نشان می دهد و دوباره امتحان می شود. به همگام سازی، همگام سازی، و وعده ها مراجعه کنید.

اجرای توابع خود را شبیه سازی کنید

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

برای شبیه سازی توابع خود:

firebase emulators:start و خروجی را برای URL Emulator Suite UI بررسی کنید. به طور پیش فرض روی localhost:4000 است، اما ممکن است در پورت دیگری در دستگاه شما میزبانی شود. آن URL را در مرورگر خود وارد کنید تا Emulator Suite UI باز شود.
خروجی فرمان firebase emulators:start برای URL تابع HTTP بررسی کنید. شبیه http://localhost:5001/MY_PROJECT/us-central1/addMessage خواهد بود، با این تفاوت که:
1. MY_PROJECT با شناسه پروژه شما جایگزین خواهد شد.
2. پورت ممکن است در دستگاه محلی شما متفاوت باشد.
رشته پرس و جو ?text=uppercaseme را به انتهای URL تابع اضافه کنید. این باید چیزی شبیه به این باشد: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . به صورت اختیاری، می توانید پیام "حرف بزرگ" را به یک پیام سفارشی تغییر دهید.
با باز کردن URL در یک برگه جدید در مرورگر خود، یک پیام جدید ایجاد کنید.
مشاهده اثرات توابع در Emulator Suite UI :
1. در تب Logs ، باید گزارش‌های جدیدی را مشاهده کنید که نشان می‌دهد عملکردهای HTTP شما با موفقیت اجرا شده است:
  i functions: Beginning execution of "addMessage"
  i functions: Beginning execution of "makeUppercase"
2. در برگه Firestore ، باید سندی حاوی پیام اصلی و همچنین نسخه بزرگ پیام خود را مشاهده کنید (اگر در ابتدا "بزرگ" بود، "UPPERCASEME" را خواهید دید).

استقرار توابع در یک محیط تولید

هنگامی که توابع شما مطابق دلخواه در شبیه ساز کار می کنند، می توانید به استقرار، آزمایش و اجرای آنها در محیط تولید ادامه دهید. به خاطر داشته باشید که برای استقرار در تولید، پروژه شما باید در برنامه قیمت گذاری Blaze باشد. به قیمت گذاری Cloud Functions مراجعه کنید.

برای تکمیل آموزش، توابع خود را مستقر کرده و سپس آنها را اجرا کنید.

این دستور را برای استقرار توابع خود اجرا کنید:
```
 firebase deploy --only functions
 
```
پس از اجرای این دستور، Firebase CLI URL را برای هر نقطه پایانی تابع HTTP خروجی می‌دهد. در ترمینال خود، باید یک خط مانند زیر را ببینید:
```
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
```
URL شامل شناسه پروژه شما و همچنین یک منطقه برای تابع HTTP است. اگرچه اکنون نیازی به نگرانی در مورد آن ندارید، برخی از توابع HTTP تولیدی باید مکانی را برای به حداقل رساندن تأخیر شبکه مشخص کنند.
اگر با خطاهای دسترسی مانند «عدم مجوز دسترسی به پروژه» مواجه شدید، پروژه خود را با نام مستعار بررسی کنید.
با استفاده از خروجی URL توسط CLI، یک پارامتر پرس و جو متن اضافه کنید و آن را در یک مرورگر باز کنید:
```
https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
```
این تابع مرورگر را به کنسول Firebase در محل پایگاه داده که رشته متنی در آن ذخیره می‌شود، اجرا و هدایت می‌کند. این رویداد نوشتن، تابع "make uppercase" را فعال می کند، که یک نسخه بزرگ از رشته را می نویسد.

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

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

مراحل بعدی

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

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

در مورد موارد استفاده برای Cloud Functions بخوانید.
آزمایشگاه Cloud Functions را امتحان کنید.
نمونه های کد را در GitHub بررسی و اجرا کنید