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

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

اطمینان حاصل کنید که تفاوت در اقدامات پشتیبانی شده برای هر روش نصب را بررسی کنید.


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

این SDK که به طور خودکار تولید می شود شامل:

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

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

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


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

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

قبل از شروع

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

  2. اگر قبلاً این کار را نکرده اید، پروژه خود را به طرح Blaze (پرداخت در حین انجام کار) ارتقا دهید.

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

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

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

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

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

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

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

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

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

    firebase ext:info publisher-id/extension-id

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

مرحله 2 : یک افزونه نصب کنید

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

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

توابع Cloud را برای Firebase راه اندازی کنید

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

cd your-project
firebase init functions

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

اگر پروژه شما قبلاً دارای توابع Cloud اولیه شده است، مطمئن شوید که از نسخه 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

به عنوان مثال، برای نصب نسخه 0.1.34 پسوند 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 ایجاد می کند که به طور خودکار برای برنامه افزودنی تولید می شود و آن را به یکی از پایگاه های کد توابع ابری پروژه شما اضافه می کند. در پایگاه کد پیش‌فرض ( functions )، SDK در مکان زیر ذخیره می‌شود: 

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

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

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

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

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

    TypeScriptجاوا اسکریپت

    به عنوان مثال، اگر یک 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. برای هر نمونه ای که می خواهید پیکربندی کنید، تابع سازنده را فراخوانی کرده و نتیجه را صادر کنید.

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

    TypeScript جاوا اسکریپت 
    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

مرحله 3 : راه اندازی پس از نصب را کامل کنید

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

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

منابع Firebase را ایجاد کنید

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

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

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

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

TypeScript جاوا اسکریپت 
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 خود تولید شده را یک بار فراخوانی کنید.

مراحل بعدی