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

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

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

ما توابع جاوا اسکریپت Cloud Firestore و HTTP-triggered را برای این نمونه انتخاب کرده‌ایم، زیرا این triggerهای پس‌زمینه را می‌توان به طور کامل از طریق Firebase Local Emulator Suite آزمایش کرد. این مجموعه ابزار همچنین از Realtime Database ، PubSub، Auth و triggerهای قابل فراخوانی HTTP پشتیبانی می‌کند. انواع دیگر triggerهای پس‌زمینه مانند Remote Config ، TestLab و Analytics را می‌توان به صورت تعاملی با استفاده از مجموعه ابزارهایی که در این صفحه توضیح داده نشده‌اند، آزمایش کرد .

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

ایجاد یک پروژه فایربیس

راه‌اندازی Node.js و Firebase CLI

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

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

npm install -g firebase-tools

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

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

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

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

1. برای ورود از طریق مرورگر و تأیید اعتبار رابط خط فرمان Firebase ، firebase login اجرا کنید.

2. به دایرکتوری پروژه Firebase خود بروید.

3. firebase init firestore را اجرا کنید. در این آموزش، می‌توانید مقادیر پیش‌فرض را هنگام درخواست قوانین Firestore و فایل‌های ایندکس بپذیرید. اگر هنوز از Cloud Firestore در این پروژه استفاده نکرده‌اید، باید همانطور که در بخش «شروع با Cloud Firestore توضیح داده شده است، یک حالت شروع و مکان برای Firestore نیز انتخاب کنید.

4. firebase init functions را اجرا کنید. رابط خط فرمان (CLI) از شما می‌خواهد که یک کدبیس موجود را انتخاب کنید یا یک کدبیس جدید را مقداردهی اولیه و نامگذاری کنید. وقتی تازه شروع به کار کرده‌اید، یک کدبیس واحد در مکان پیش‌فرض کافی است. بعداً، با گسترش پیاده‌سازی شما، ممکن است بخواهید توابع را در کدبیس‌ها سازماندهی کنید .

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

   • جاوا اسکریپت
   • پایتون
   • برای اطلاعات بیشتر در مورد TypeScript به بخش نوشتن توابع با TypeScript مراجعه کنید.

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

6. رابط خط فرمان (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();
index.js

این خطوط ماژول‌های firebase-functions و firebase-admin را بارگذاری می‌کنند و یک نمونه برنامه admin را که از طریق آن می‌توان تغییرات Cloud Firestore را انجام داد، مقداردهی اولیه می‌کنند. هر جا که پشتیبانی Admin SDK در دسترس باشد، مانند FCM ، Authentication و Firebase Realtime Database ، روشی قدرتمند برای ادغام Firebase با استفاده از Cloud Functions فراهم می‌کند.

رابط خط فرمان Firebase CLI) به طور خودکار ماژول‌های فایربیس و Firebase SDK for Cloud Functions Node را هنگام راه‌اندازی اولیه پروژه نصب می‌کند. برای افزودن کتابخانه‌های شخص ثالث به پروژه خود، می‌توانید 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.` });
});
index.js

تابع 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 });
  });
index.js

تابع makeUppercase() زمانی اجرا می‌شود که Cloud Firestore در آن نوشته شود. تابع ref.set سندی را که باید به آن گوش داد، تعریف می‌کند. به دلایل عملکردی، باید تا حد امکان دقیق باشید.

براکت‌ها - برای مثال، {documentId} - اطراف "پارامترها" را احاطه می‌کنند، کاراکترهای جایگزین که داده‌های منطبق خود را در فراخوانی برگشتی نمایش می‌دهند.

Cloud Firestore هر زمان که پیام‌های جدید اضافه شوند، فراخوانی onCreate() را فعال می‌کند.

توابع رویدادمحور مانند رویدادهای Cloud Firestore ناهمزمان هستند. تابع فراخوانی باید یا null ، یک Object یا یک Promise را برگرداند. اگر چیزی برنگردانید، تابع منقضی می‌شود، خطا را اعلام می‌کند و دوباره امتحان می‌شود. به بخش همگام‌سازی، ناهمگامی و Promiseها مراجعه کنید.

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

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

برای تقلید از توابع شما:

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

2. خروجی دستور firebase emulators:start را برای یافتن آدرس اینترنتی تابع HTTP addMessage() بررسی کنید. این آدرس مشابه 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. با باز کردن URL در یک برگه جدید در مرورگر خود، یک پیام جدید ایجاد کنید.

5. مشاهده‌ی اثرات توابع در Emulator Suite UI :

   1. در تب Logs ، باید گزارش‌های جدیدی را ببینید که نشان می‌دهند توابع addMessage() و makeUppercase() اجرا شده‌اند:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. در برگه Firestore ، باید سندی را ببینید که حاوی پیام اصلی شما و همچنین نسخه بزرگ شده پیام شما است (اگر در ابتدا "uppercaseme" بوده است، "UPPERCASEME" را خواهید دید).

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

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

برای تکمیل آموزش، توابع خود را مستقر کنید و سپس addMessage() را اجرا کنید تا makeUppercase() فعال شود.

1. برای استقرار توابع خود، این دستور را اجرا کنید:

    firebase deploy --only functions
    

   پس از اجرای این دستور، رابط خط فرمان Firebase ، URL مربوط به هر نقطه پایانی تابع HTTP را نمایش می‌دهد. در ترمینال خود، باید خطی مانند زیر را مشاهده کنید:

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

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

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

2. با استفاده از خروجی آدرس اینترنتی addMessage() توسط CLI، یک پارامتر کوئری متنی اضافه کنید و آن را در مرورگر باز کنید:

   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 });
  });
index.js

مراحل بعدی

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

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

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