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

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

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

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

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

ایجاد پروژه Firebase

راه‌اندازی کردن Node.js و واسط خط فرمان Firebase

برای نوشتن توابع به محیط 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، همان فرمان را دوباره اجرا کنید.

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

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

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

1. firebase login را اجرا کنید تا ازطریق مرورگر به سیستم وارد شوید و Firebase CLI را اصالت‌سنجی کنید.

2. به فهرست راهنمای پروژه Firebase بروید.

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

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

5. CLI گزینه‌های زیر را برای پشتیبانی زبان به شما ارائه می‌دهد:

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

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

6. رابط خط فرمان به شما امکان می‌دهد وابستگی‌ها را با 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 شما را برای نوشتن و استقرار توابع مشخص می‌کند. می‌توانید نسخه‌های پشتیبانی‌شده دیگری را انتخاب کنید.

وارد کردن واحدهای لازم و مقداردهی اولیه برنامه

پس‌از تکمیل تکالیف راه‌اندازی، می‌توانید فهرست راهنمای منبع را باز کنید و طبق روشی که در بخش‌های زیر توضیح داده شده است، کد اضافه کنید. برای این نمونه، پروژه‌تان باید بااستفاده از عبارت‌های Node require، Cloud Functions و ماژول‌های Admin SDK را وارد کند. خطوطی مانند خطوط زیر به فایل 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 { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

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

وقتی پروژه‌تان را مقداردهی اولیه می‌کنید، Firebase CLI به‌طور خودکار Firebase و Firebase SDK را برای Cloud Functions Node modules نصب می‌کند. برای افزودن کتابخانه‌های طرف سوم به پروژه‌تان، می‌توانید 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 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

تابع addMessage() یک نقطه پایان HTTP است. هر درخواستی به نقطه پایانی منجر به ارسال اشیاء درخواست و پاسخ به سبک 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، «شیء»، یا Promise برگرداند. اگر چیزی برنگردانید، زمان تابع تمام می‌شود، خطایی را نشان می‌دهد، و دوباره امتحان می‌شود. همگام‌سازی، غیرهمگام‌سازی، و Promises را ببینید.

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

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

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

1. firebase emulators:start را اجرا کنید و برونداد را برای نشانی وب Emulator Suite UI بررسی کنید. به‌طور پیش‌فرض روی localhost:4000 است، اما ممکن است روی درگاه دیگری در دستگاهتان میزبانی شود. آن نشانی وب را در مرورگرتان وارد کنید تا 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. با باز کردن نشانی وب در برگه جدیدی در مرورگرتان، پیام جدیدی ایجاد کنید.

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

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

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

   نشانی وب حاوی شناسه پروژه شما و همچنین منطقه‌ای برای تابع 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 { 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 = 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 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 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 codelab را امتحان کنید.
• مرور و اجرای نمونه کدها در GitHub