یک افزونه Firebase نصب کنید

شما می‌توانید هر یک از افزونه‌های رسمی Firebase را با استفاده از کنسول Firebase ، رابط خط فرمان Firebase (Firebase CLI ) یا با استفاده از یک SDK خودکار نصب (و مدیریت ) کنید.

حتماً تفاوت‌های موجود در اقدامات پشتیبانی‌شده برای هر روش نصب را بررسی کنید.


نصب با استفاده از SDK تولید شده خودکار، گزینه جدیدی برای نصب و مدیریت افزونه‌ها است. با این گزینه، شما از CLI برای تولید خودکار SDK نود برای یک نسخه افزونه خاص استفاده می‌کنید که می‌توانید آن را به عنوان یک وابستگی معمولی در توابع ابری جاوا اسکریپت یا تایپ اسکریپت خود وارد کنید.

این SDK که به صورت خودکار تولید می‌شود شامل موارد زیر است:

  • رابطی که پارامترهای افزونه و اعلان‌های نوع برای اکثر انواع پارامترهای غیراولیه را نشان می‌دهد.
  • یک تابع سازنده که نمونه‌ای از افزونه را مقداردهی اولیه می‌کند
  • یک کلاس افزونه که شامل تریگرهای Eventarc برای تمام رویدادهای منتشر شده توسط افزونه است.

پس از ایجاد SDK افزونه، تمام پیکربندی افزونه به صورت کد انجام می‌شود.

استفاده از این گزینه نصب می‌تواند مدیریت چندین نمونه افزونه را تا حد زیادی ساده کند، به خصوص در پروژه‌هایی که شامل توابع ابری هستند که خارج از افزونه‌ها تعریف شده‌اند.


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

برای نصب یک افزونه، پروژه شما باید در طرح Blaze (پرداخت در ازای استفاده) باشد. اگرچه نصب افزونه هیچ هزینه‌ای ندارد، اما اگر میزان استفاده شما از سرویس‌های Firebase یا سرویس‌های ابری مانند Cloud Secret Manager بیشتر از سطح رایگان این سرویس‌ها باشد، ممکن است هزینه‌ای برای استفاده از آنها از شما دریافت شود.

قبل از اینکه شروع کنی

  1. اگر هنوز Firebase را به پروژه خود اضافه نکرده‌اید، آن را به پروژه خود اضافه کنید .

  2. اگر هنوز این کار را نکرده‌اید، پروژه خود را به طرح Blaze (پرداخت به ازای استفاده) ارتقا دهید.

  3. آخرین نسخه Firebase CLI را نصب یا به‌روزرسانی کنید.

  4. شناسه پروژه Firebase یا نام مستعار پروژه قبلاً پیکربندی شده خود را یادداشت کنید.

مرحله ۱ : مشاهده اطلاعات دقیق در مورد یک افزونه

این مرحله اختیاری است، اما اکیداً توصیه می‌شود.

قبل از نصب Firebase Extension ، توصیه می‌کنیم اطلاعات دقیق در مورد افزونه، از جمله موارد زیر را بررسی کنید:

  • نحوه کار افزونه، هرگونه کار قبل از نصب و جزئیات مربوط به افزونه
  • اطلاعات شناسایی عمومی و توضیحات
  • اینکه آیا وظایف افزونه به حساب صورتحساب نیاز دارد یا خیر
  • سرویس‌های گوگل (API) و نقش‌های دسترسی مورد نیاز برای عملیات
  • منابع ایجاد شده برای افزونه (مانند توابع)
  • شرح پارامترهای قابل تنظیم توسط کاربر

برای مشاهده اطلاعات دقیق یک افزونه:

  1. مطمئن شوید که محیط خود را تنظیم کرده و یک افزونه انتخاب کرده‌اید .

  2. دستور extension-info را از هر کجای رایانه خود اجرا کنید:

    firebase ext:info publisher-id/extension-id

    آرگومان‌های publisher-id و extension-id الزامی هستند و می‌توانید آن‌ها را در صفحه جزئیات پیش از نصب افزونه پیدا کنید.

مرحله ۲ : نصب افزونه

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

قبل از ادامه، مطمئن شوید که محیط خود را تنظیم کرده و یک افزونه انتخاب کرده‌اید .

مقداردهی اولیه توابع ابری برای فایربیس

اگر در حال شروع یک پروژه جدید هستید یا اگر پروژه شما از قبل از توابع ابری برای فایربیس استفاده نمی‌کند، init functions اجرا کنید:

cd your-project
firebase init functions

TypeScript یا JavaScript را به عنوان زبان توابع خود انتخاب کنید.

اگر پروژه شما از قبل Cloud Functions را مقداردهی اولیه کرده است، مطمئن شوید که از نسخه 5.1.0 یا جدیدتر بسته firebase-functions استفاده می‌کنید:

cd your-project/functions
npm upgrade --save firebase-functions

اگر از ESLint استفاده می‌کنید، ممکن است بخواهید SDK های تولید شده را از پیکربندی خود ( .eslintrc.js ) نیز حذف کنید:

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

ایجاد یک SDK افزونه

از دایرکتوری محلی Firebase خود، دستور ext:sdk:install را اجرا کنید.

firebase ext:sdk:install publisher-id/extension-id@version

برای مثال، برای نصب نسخه ۰.۱.۳۴ افزونه firestore-send-email :

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id و extension-id الزامی هستند و می‌توانید آن‌ها را در صفحه جزئیات پیش از نصب افزونه در extensions.dev پیدا کنید. قسمت @ version اختیاری است؛ اگر آن را حذف کنید، ابزار آخرین نسخه را نصب می‌کند.

دو گزینه وجود دارد که می‌توانید مشخص کنید:

  • --force : تمام موارد زیر را بدون تأیید بیشتر انجام دهید:

    • حتی اگر SDK قبلاً برای همان افزونه و نسخه تولید شده باشد، آن را به صورت خودکار تولید می‌کند.
    • بسته SDK تولید شده خودکار را در پروژه Cloud Functions Node نصب کنید.

  • --codebase : نام کدبیس برای اضافه کردن SDK به آن. اگر مشخص نشود، دستور SDK را به کدبیس پیش‌فرض، functions ، اضافه می‌کند.

این دستور یک بسته Node حاوی SDK که به طور خودکار برای افزونه تولید شده است، ایجاد می‌کند و آن را به یکی از پایگاه‌های کد Cloud Functions پروژه شما اضافه می‌کند. در پایگاه کد پیش‌فرض ( functions )، SDK در مکان زیر ذخیره می‌شود: 

functions/generated/extensions/publisher-id/extension-id/version

پس از تولید SDK، دستور از شما می‌پرسد که آیا می‌خواهید SDK را در پروژه Cloud Functions Node خود نیز نصب کنید. به این سوال پاسخ مثبت دهید.

پیکربندی نمونه‌های افزونه

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

  1. در منبع توابع ابری خود، سازنده را با استفاده از عبارتی که توسط دستور ext:sdk:install چاپ شده است، وارد کنید.

    تایپ اسکریپت

    برای مثال، اگر شما یک SDK برای افزونه firestore-send-email ایجاد کرده باشید، دستور import چیزی شبیه به کد زیر خواهد بود: 

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    اگر افزونه به مقادیر مخفی مانند رمزهای عبور نیاز داشته باشد، به تابع defineSecret از Cloud Functions SDK نیز نیاز دارید: 

    import { defineSecret } from "firebase-functions/params";

    جاوا اسکریپت

    برای مثال، اگر شما یک SDK برای افزونه firestore-send-email ایجاد کرده باشید، عبارت require چیزی شبیه به کد زیر خواهد بود: 

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    اگر افزونه به مقادیر مخفی مانند رمزهای عبور نیاز داشته باشد، به تابع defineSecret از Cloud Functions SDK نیز نیاز دارید: 

    const { defineSecret } = require('firebase-functions/params');

  2. برای هر نمونه‌ای که می‌خواهید پیکربندی کنید، تابع سازنده را فراخوانی کنید و نتیجه را صادر کنید.

    به هر نمونه یک شناسه منحصر به فرد بدهید که فقط شامل حروف کوچک، اعداد و خط فاصله باشد.

    تایپ اسکریپت 

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    جاوا اسکریپت 

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    توجه داشته باشید که مقادیر مخفی باید با استفاده از تابع defineSecret مشخص شوند.

  3. سپس، برای استقرار افزونه‌هایی که پیکربندی کرده‌اید، دستور زیر را اجرا کنید: 

    firebase deploy --only functions --project=projectId-or-alias

    تمام گزینه‌های معمول استقرار توابع ابری اعمال می‌شوند. به عنوان مثال، برای استقرار یک نمونه افزونه از یک پایگاه کد خاص: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

مرحله ۳ : تکمیل تنظیمات پس از نصب

برخی از افزونه‌ها مراحلی دارند که قبل از استفاده باید آنها را انجام دهید یا اختیاری هستند. این دستورالعمل‌ها را در صفحه جزئیات پس از نصب افزونه خود در داشبورد Extensions در کنسول Firebase پیدا کنید (لینک مخصوص داشبورد پس از نصب در ترمینال نمایش داده می‌شود).

همچنین می‌توانید این دستورالعمل‌ها را در فایل POSTINSTALL.md که در دایرکتوری منبع افزونه قرار دارد، پیدا کنید.

ایجاد منابع فایربیس

اگر افزونه را طوری پیکربندی کرده‌اید که از منابع Firebase (مجموعه‌های Cloud Firestore ، مسیرهای Realtime Database ، مخازن Cloud Storage ) که از قبل وجود ندارند استفاده کند، قبل از استفاده از افزونه، آنها را ایجاد کنید.

ایجاد کنترل‌کننده‌های رویداد Eventarc

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

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

تایپ اسکریپت 

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

جاوا اسکریپت 

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

شما باید کنترل‌کننده‌ی رویداد را به همراه نمونه‌ی افزونه صادر کنید.

پس از تعریف یک کنترل‌کننده رویداد، و پس از هر بار که در یکی از آنها تغییراتی ایجاد می‌کنید، هم افزونه و هم کنترل‌کننده را مجدداً مستقر کنید.

نصب چندین نمونه افزونه

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

برای هر نمونه‌ای که می‌خواهید نصب و پیکربندی کنید، یک بار تابع سازنده‌ی SDK خودکار تولید شده را فراخوانی کنید.

مراحل بعدی