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


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

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

ما تا حدودی توابع جاوا اسکریپت Cloud Firestore و HTTP راه‌اندازی شده را برای این نمونه انتخاب کرده‌ایم زیرا این محرک‌های پس‌زمینه را می‌توان به‌طور کامل از طریق Firebase Local Emulator Suite آزمایش کرد. این مجموعه ابزار همچنین از تریگرهای قابل فراخوانی Realtime Database ، 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 Functions مقداردهی اولیه می‌کنید، یک پروژه خالی حاوی وابستگی‌ها و مقداری حداقل کد نمونه ایجاد می‌کنید و نوع اسکریپت یا جاوا اسکریپت را برای نوشتن توابع انتخاب می‌کنید. برای اهداف این آموزش، همچنین باید Cloud Firestore را مقداردهی اولیه کنید.

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

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

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

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

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

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

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

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

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

  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 UI :

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

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

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

برای تکمیل آموزش، توابع خود را مستقر کنید و سپس 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() راه‌اندازی می‌کند، که یک نسخه بزرگ از رشته را می‌نویسد.

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