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


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

،


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

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

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

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

یک پروژه 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 نیاز به CLI Firebase دارید. برای نصب Node.js و NPM ، مدیر نسخه گره توصیه می شود.

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

npm install -g firebase-tools

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

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

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

برای شروع پروژه خود:

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

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

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

  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 و ماژول های سرپرست SDK را با استفاده از گره 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 شروع می کند. هر جا که پشتیبانی SDK Admin در دسترس باشد ، همانطور که برای FCM ، Authentication و Firebase Realtime Database وجود دارد ، روشی قدرتمند برای ادغام Firebase با استفاده از Cloud Functions فراهم می کند.

Firebase CLI به طور خودکار هنگام شروع پروژه خود ، ماژول های گره ای را برای توابع ابعاد Firebase و Firebase برای توابع Cloud Functions نصب می کند. برای افزودن کتابخانه های شخص ثالث به پروژه خود ، می توانید 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 است. هرگونه درخواستی به نقطه پایانی منجر به درخواست و پاسخ به سبک 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 ، یک شی یا یک وعده باشد. اگر چیزی را برنگردید ، عملکرد به پایان می رسد ، خطایی را سیگنال می دهد و دوباره انجام می شود. Sync ، Async و وعده ها را ببینید.

از اجرای توابع خود تقلید کنید

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 ، باید سندی را مشاهده کنید که حاوی پیام اصلی شما و همچنین نسخه بالایی پیام شما باشد (اگر در ابتدا "رده" بود ، "رده های فوق العاده" را مشاهده خواهید کرد).

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

هنگامی که کارکردهای شما به صورت دلخواه در شبیه ساز کار می کنند ، می توانید به استقرار ، آزمایش و اجرای آنها در محیط تولید ادامه دهید. به خاطر داشته باشید که برای استقرار به 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 ، می توانید موارد زیر را نیز انجام دهید: