Check out what’s new from Firebase at Google I/O 2022. Learn more

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

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

  • addMessage() که نشانی اینترنتی را نشان می دهد که یک مقدار متن را می پذیرد و آن را در Cloud Firestore می نویسد.
  • makeUppercase() که در Cloud Firestore رایت می کند و متن را به حروف بزرگ تبدیل می کند.

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

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

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

  1. در کنسول Firebase ، روی افزودن پروژه کلیک کنید.

    • برای افزودن منابع Firebase به پروژه Google Cloud موجود ، نام پروژه آن را وارد کرده یا از منوی کشویی انتخاب کنید.

    • برای ایجاد یک پروژه جدید، نام پروژه مورد نظر را وارد کنید. همچنین می توانید به صورت اختیاری شناسه پروژه نمایش داده شده در زیر نام پروژه را ویرایش کنید.

  2. در صورت درخواست، شرایط Firebase را بررسی کرده و بپذیرید.

  3. روی Continue کلیک کنید.

  4. (اختیاری) Google Analytics را برای پروژه خود راه اندازی کنید، که به شما امکان می دهد با استفاده از هر یک از محصولات Firebase زیر تجربه ای بهینه داشته باشید:

    یا یک حساب Google Analytics موجود را انتخاب کنید یا یک حساب جدید ایجاد کنید.

    اگر حساب جدیدی ایجاد می‌کنید، مکان گزارش Analytics خود را انتخاب کنید، سپس تنظیمات اشتراک‌گذاری داده و شرایط Google Analytics را برای پروژه خود بپذیرید.

  5. روی ایجاد پروژه (یا افزودن Firebase ، اگر از پروژه Google Cloud موجود استفاده می‌کنید) کلیک کنید.

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

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

برای نوشتن توابع به یک محیط 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 SDK را برای توابع Cloud مقداردهی اولیه می‌کنید، یک پروژه خالی حاوی وابستگی‌ها و مقداری حداقل کد نمونه ایجاد می‌کنید، و برای نوشتن توابع یا TypeScript یا JavaScript را انتخاب می‌کنید. برای اهداف این آموزش، شما همچنین باید Cloud Firestore را مقداردهی اولیه کنید.

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

  1. firebase login را اجرا کنید تا از طریق مرورگر وارد شوید و ابزار firebase را احراز هویت کنید.
  2. به فهرست پروژه Firebase خود بروید.
  3. firebase init firestore را اجرا کنید. برای این آموزش، می‌توانید مقادیر پیش‌فرض را زمانی که قوانین Firestore و فایل‌های فهرست از شما خواسته می‌شود، بپذیرید. اگر هنوز از Cloud Firestore در این پروژه استفاده نکرده‌اید، باید یک حالت شروع و مکان برای Firestore همانطور که در Get start with Cloud Firestore توضیح داده شده است، انتخاب کنید.
  4. firebase init functions اجرا کنید. این ابزار به شما گزینه ای برای نصب وابستگی ها با npm می دهد. اگر می‌خواهید وابستگی‌ها را به روش دیگری مدیریت کنید، رد کردن آن بی‌خطر است، اگرچه اگر رد کنید، باید قبل از شبیه‌سازی یا استقرار توابع خود، npm install را اجرا کنید.

  5. این ابزار دو گزینه برای پشتیبانی زبان در اختیار شما قرار می دهد:

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

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

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": "10"} . این نسخه 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');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();
index.js

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

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

تابع 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، onWrite() را فعال می کند.

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

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

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

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

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

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

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

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

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

      توابع i: شروع اجرای "addMessage"

      توابع i: شروع اجرای "makeUppercase"

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

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

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

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

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

     firebase deploy --only functions

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

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

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

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

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

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

    این تابع مرورگر را به کنسول Firebase در محل پایگاه داده که رشته متنی در آن ذخیره شده است اجرا و هدایت می کند. این رویداد نوشتن، makeUppercase() را راه‌اندازی می‌کند، که یک نسخه بزرگ از رشته را می‌نویسد.

پس از استقرار و اجرای توابع، می‌توانید گزارش‌ها را در کنسول Firebase برای توابع 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');

// 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، می توانید موارد زیر را نیز انجام دهید:

آموزش تصویری

با تماشای فیلم های آموزشی می توانید درباره عملکردهای ابری بیشتر بدانید. در این ویدیو، راهنمایی دقیق برای شروع کار با توابع ابری، از جمله Node.js و راه اندازی CLI را خواهید دید.