سوالات متداول در مورد منسوخ شدن افزونه‌های فایربیس

چرا Firebase Extensions منسوخ می‌کنیم؟

با توجه به تغییرات و منسوخ شدن‌های آتی در زیرساخت Google Cloud ، سرویس مدیریت‌شده‌ی Firebase Extensions را متوقف خواهیم کرد.

آیا افزونه‌های مستقر شده‌ی موجود پس از ۳۱ مارس ۲۰۲۷ از کار خواهند افتاد؟

خیر. افزونه‌های از پیش مستقر شده مستقیماً روی زیرساخت استاندارد Google Cloud (مانند Cloud Functions ، Eventarc ، Cloud Run و Cloud Tasks ) اجرا می‌شوند و به طور نامحدود به اجرا ادامه خواهند داد.

با این حال، پس از ۳۱ مارس ۲۰۲۷، شما تمام توانایی‌های خود را برای به‌روزرسانی، پیکربندی مجدد یا حذف نصب این افزونه‌ها از طریق کنسول Firebase یا CLI از دست خواهید داد. همچنین، شما توانایی دانلود پیکربندی‌های افزونه‌های موجود خود را برای کمک به مهاجرت به یک کیت تابع از دست خواهید داد. اکیداً توصیه می‌کنیم تا ۳۱ مارس ۲۰۲۷، پیکربندی افزونه را منتقل یا صادر کنید.

اگر کاربر هیچ کاری نکند چه اتفاقی می‌افتد؟

اگر کاربری هیچ اقدامی انجام ندهد، توابع مستقر شده فعلی او به عنوان دارایی‌های استاندارد به کار خود ادامه خواهند داد. با این حال، پس از ۳۱ مارس ۲۰۲۷:

1. آنها نمی‌توانند پارامترهای پیکربندی را تغییر دهند یا متغیرهای محیطی را به‌روزرسانی کنند.
2. آنها نمی‌توانند رفع اشکال، وصله‌های امنیتی یا ارتقاء وابستگی‌ها را اعمال کنند.
3. آنها نمی‌توانند پیکربندی افزونه را دانلود کنند تا به طور یکسان به پیکربندی یک کیت تابع جایگزین کمک کنند.
4. اکثر افزونه‌ها در حال حاضر بر روی SDK قدیمی Cloud Functions v1 ساخته شده‌اند که به runtimeهای قدیمی Node.js وابسته است. هنگامی که این runtimeهای قدیمی به طور کامل توسط Google Cloud از رده خارج شوند، ممکن است اجرای توابع متوقف شود یا غیرفعال شود. به پشتیبانی Runtime مراجعه کنید.

آیا چیزی جایگزین افزونه‌های فایربیس می‌شود؟

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

با این حال، این به هر ناشر افزونه بستگی دارد که آیا می‌خواهد یک جایگزین رسمی برای کیت تابع در npm منتشر کند یا خیر. از آنجایی که افزونه‌ها متن‌باز هستند، اگر ناشر نخواهد یک جایگزین رسمی ایجاد کند، هر توسعه‌دهنده‌ای می‌تواند آن را منشعب کند تا یک جایگزین غیررسمی با Cloud Functions با استفاده از APIهای نسل دوم ما در Node SDK ایجاد کند.

ناشرانی که مایل به جایگزینی هستند باید دستورالعمل‌های موجود در راهنمای مهاجرت ناشران را دنبال کنند.

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

من به عنوان کاربر افزونه چه کاری باید انجام دهم؟

اگر از افزونه‌ها استفاده می‌کنید و دیگر از افزونه‌های نصب‌شده خود استفاده نمی‌کنید، قبل از ۳۱ مارس ۲۰۲۷ آنها را حذف نصب کنید .

پس از غیرفعال‌سازی، دکمه «حذف» در کنسول Firebase و دستورات CLI مربوطه حذف خواهند شد. شما باید تمام منابع مرتبط با Google Cloud ، از جمله Cloud Functions منفرد، اسرار Secret Manager ، صف‌های Cloud Tasks و حساب‌های سرویس IAM سفارشی را با استفاده از کنسول Google Cloud به صورت دستی حذف کنید.

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

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

من به عنوان ناشر افزونه چه کاری باید انجام دهم؟

ما شما را تشویق می‌کنیم که افزونه‌های منتشر شده خود را به کیت‌های تابع منتشر شده در npm منتقل کنید. می‌توانید با انتقال افزونه خود به توابع نسل دوم شروع کنید، که پیش‌نیاز ایجاد یک کیت تابع است. این شامل بسته‌بندی منطق افزونه شما با استفاده از Cloud Functions v2 SDK است. ما Cloud Functions v2 SDK را با پشتیبانی از ویژگی‌هایی مانند امنیت اعلانی و رویدادهای چرخه عمر به‌روزرسانی کرده‌ایم. اکنون می‌توانید کد افزونه موجود خود را با حداقل تغییرات در منطق اصلی کسب‌وکار خود به یک تابع نسل دوم منتقل کنید. این توابع را می‌توان با استفاده از یک بسته npm منتشر کرد. برای جزئیات بیشتر، به راهنمای مهاجرت ما برای ناشران مراجعه کنید.

اگر سوالات دیگری داشته باشم چه؟

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

ناشرانی که در مورد نحوه مهاجرت Firebase Extensions سؤالی دارند، می‌توانند از راهنمای مهاجرت ما برای ناشران استفاده کنند. این راهنما شامل دستورالعمل‌هایی در مورد چگونگی مطلع ماندن از به‌روزرسانی‌ها و دریافت کمک در ارائه جایگزینی برای افزونه‌های منتشر شده شما است.

مسیرهای اصلی مهاجرت موجود چیست؟

از سپتامبر ۲۰۲۶، Firebase رسماً از دو مسیر مهاجرت اصلی پشتیبانی می‌کند:

1. مهاجرت به یک تابع مشترک NPM ("کیت تابع") : برای Stream Firestore به BigQuery و هر کیت تابع دیگری که در npm در دسترس قرار می‌گیرد، توصیه می‌شود. منطق اصلی به عنوان یک کتابخانه استاندارد NPM با استفاده از Cloud Functions v2 SDK بسته‌بندی شده است. کاربران یک پایگاه کد استاندارد Cloud Functions را مقداردهی اولیه می‌کنند، بسته را نصب می‌کنند، توابع را دوباره صادر می‌کنند و آنها را به طور مستقل با استفاده از CLI مستقر می‌کنند.
2. Fork و Self-Manage : برای تمام افزونه‌هایی که کیت تابعی در npm ندارند، توصیه می‌شود. کاربران کد منبع افزونه متن‌باز را کپی یا Fork می‌کنند، تریگرها را با استفاده از مهارت‌های مهاجرت هوش مصنوعی با بهترین تلاش یا راهنماهای دستی به توابع استاندارد Firebase v2 تبدیل می‌کنند و مالکیت کامل پایگاه کد و نگهداری مداوم آن را بر عهده می‌گیرند.

کدام افزونه‌ها به کیت‌های تابعی منتقل می‌شوند؟

افزونه‌ی Stream Firestore to BigQuery به یک کیت تابع که به صورت بسته‌ی npm @firebase-function-kits/firestore-bigquery-export در دسترس است، منتقل شده است.

چرا این مهاجرت نیاز به ارتقا از Cloud Functions نسخه ۱ به نسخه ۲ دارد؟

پشتیبانی از استاندارد Cloud Functions v1 با زمان اجرای Node.js 22 به پایان می‌رسد. برای جلوگیری از "مهاجرت مضاعف" که در آن توسعه‌دهندگان از Firebase Extensions مهاجرت می‌کنند و مجبور می‌شوند پس از پایان زمان‌های اجرای قدیمی، دوباره به صورت دستی کد را بازنویسی کنند، Firebase اکیداً توصیه می‌کند که تمام توابع منتقل شده را بلافاصله در طول این انتقال به SDK v2 ارتقا دهید و این برای کیت‌های تابع الزامی است.

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

آیا مهاجرت به Cloud Functions خودمدیریت‌شده، صورتحساب مشتری را تغییر خواهد داد؟

به‌طورکلی، خیر. افزونه‌های مستقرشده، از قبل برای منابع زیربنایی Google Cloud که مصرف می‌کنند، مانند فراخوانی Cloud Functions ، Cloud Storage یا ذخیره‌سازی و کوئری‌های BigQuery ، از مشتریان هزینه دریافت می‌کنند. با این حال، در طول دوره مهاجرت، اگر مشتریان هم Firebase Extensions و هم تابع جایگزین تازه مستقرشده خود را به‌طور موازی اجرا کنند تا انتقال امن تضمین شود، ممکن است هزینه اضافی موقت و کمی متحمل شوند.

نحوه‌ی پرداخت صورتحساب برای حساب‌های Mandiant یا سایر حساب‌های سازمانی تخصصی چگونه است؟

این منسوخ شدن، تغییری در سطح پلتفرم است که بر همه پروژه‌های Firebase و Google Cloud تأثیر می‌گذارد. ترتیبات استاندارد صورتحساب و اشتراک تحت تأثیر قرار نمی‌گیرند. اگر مشتریان به دلیل خرابی منسوخ شدن، درخواست اعتبار SLA کنند یا با استثنائات پیچیده صورتحساب مواجه شوند، پرونده را مستقیماً از طریق کانال‌های پشتیبانی صورتحساب عادی پیگیری کنید.

خطر از دست رفتن داده‌ها یا از کار افتادن سرویس در طول مهاجرت چقدر است؟

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

• اختلال در تریگر : اگر تریگرهای قدیمی قبل از فعال شدن تریگرهای جدید حذف شوند، شکافی ایجاد می‌شود که در آن رویدادها (مثلاً نوشتن سند Cloud Firestore ) از دست رفته و برای همیشه از بین می‌روند. توصیه می‌کنیم قبل از حذف افزونه، کیت جایگزین را مستقر کرده و آن را اعتبارسنجی کنید تا از هرگونه از دست رفتن داده‌ها جلوگیری شود.
• شکاف‌های مجوز : اگر کدبیس تازه پیاده‌سازی‌شده فاقد مجوزهای لازم IAM باشد، عملیاتی مانند نوشتن در BigQuery بی‌صدا با شکست مواجه می‌شوند یا در زمان اجرا از کار می‌افتند. ما امنیت اعلانی را برای توابع اضافه کرده‌ایم، بنابراین اولین استقرار کیت که توسط حسابی انجام می‌شود که می‌تواند پرس‌وجو کند و نقش‌ها را تنظیم کند و یک حساب سرویس ایجاد کند، باید این مشکل را کاهش دهد.

چگونه از دست رفتن داده‌ها برای افزونه حیاتی Cloud Firestore -to- BigQuery Export جلوگیری کنیم؟

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

1. کیت تابع جایگزین را در حالی که افزونه هنوز نصب و در حال اجرا است، مستقر کنید. چند دقیقه صبر کنید تا Eventarc به طور کامل آماده شود.
2. یک سند آزمایشی در مجموعه Cloud Firestore تحت نظارت بنویسید و تأیید کنید که تابع خودمدیریت‌شده جدید با موفقیت یک ردیف مربوطه را در جدول گزارش تغییرات BigQuery (با شناسه رویداد جدید) می‌نویسد.
3. پس از تأیید عملکرد استقرار جدید، فوراً افزونه قدیمی را حذف یا غیرفعال کنید تا رفتار نوشتن مضاعف خاتمه یابد.
4. پنجره همپوشانی را تا حد امکان کوتاه نگه دارید تا هزینه پردازش تکراری هر نوشتن و احتمال وجود ردیف‌های تکراری در گزارش تغییرات خام BigQuery به حداقل برسد.
5. در بیشتر موارد، جدول خام تغییرات ( *_raw_changelog ) با استفاده از insertID موارد تکراری را حذف می‌کند و حتی در مواردی که ردیف‌های تکراری در گزارش تغییرات دریافت می‌کنید، آخرین نمای جدول ( *_raw_latest ) صحیح خواهد بود.

اطلاعات بیشتر در مورد انتقال این افزونه به طور خاص و نحوه بازیابی اطلاعات از دست رفته در فایل README.md کیت به تفصیل آمده است.

اگر مرحله آماده‌سازی چرخه حیات با شکست مواجه شود، چه کاری باید انجام دهم؟

تحت سرویس مدیریت‌شده، وظایف راه‌اندازی (مانند ایجاد مجموعه داده‌ها، جداول و نماهای BigQuery ) به طور خودکار انجام می‌شدند. تحت مدل NPM خودمدیریت‌شده، این وظایف با استفاده از یک تابع صف وظایف چرخه عمر فعال می‌شوند؛ برای مثال، در firestore-bigquery-export این مورد initBigQuerySync نامیده می‌شود.

اگر این مرحله با شکست مواجه شد یا به طور خودکار اجرا نشد:

1. تأیید کنید که به حساب سرویس زمان اجرای Cloud Functions نقش‌های IAM مورد نیاز اعطا شده است. به عنوان مثال، برای firestore-bigquery-export این موارد شامل موارد زیر است:

   • برای ایجاد منابع و درج ردیف‌ها: roles/bigquery.dataEditor
   • برای اجرای کارها و ساخت نماها: roles/bigquery.user
   • برای قرار دادن وظیفه تأمین، roles/cloudtasks.enqueuer را وارد کنید.

2. تأیید کنید که فراخواننده مجوزهای roles/cloudtasks.enqueuer را دارد.

3. دستور مقداردهی اولیه چرخه عمر را با استفاده از رابط خط فرمان (CLI) به صورت دستی دوباره اجرا کنید:

   firebase functions:lifecycle:run afterInstall KIT_INSTANCE_ID
   

4. برای تشخیص هرگونه خطای مجوز یا پیکربندی، گزارش‌های Cloud Logging را هم برای عملکرد تریگر و هم برای اجرای صف وظایف بررسی کنید.

اعتبارنامه‌های Secret Manager چگونه منتقل می‌شوند؟

در مدل مدیریت‌شده، منابع Secret Manager به‌طور خودکار به نمونه‌های افزونه متصل می‌شدند. وقتی از دستورات ext:migrate یا ext:export --mode functions برای خروجی گرفتن از پیکربندی افزونه‌های خود به یک کیت تابع استفاده می‌کنید، ما افزونه‌ها را از مدیریت این رازها باز می‌داریم تا پس از حذف افزونه، آنها در پروژه شما باقی بمانند. اگر می‌خواهید این رازها را در آینده حذف کنید، باید این کار را به‌صورت دستی در کنسول Google Cloud انجام دهید.

اگر کاربری بخواهد چندین نمونه از یک افزونه‌ی منتقل‌شده را اجرا کند، چه می‌شود؟

ما کیت‌های تابع را به عنوان راهی برای پشتیبانی از چندین نمونه از یک تابع، مشابه نحوه داشتن چندین نسخه از یک افزونه، معرفی کردیم. هر کیت یک شناسه نمونه کیت منحصر به فرد دریافت می‌کند که مشابه یک پایگاه کد است و می‌تواند به جای پایگاه‌های کد در دستورات CLI استفاده شود. هنگام استقرار، تمام توابع در یک نمونه کیت با پیشوند kit-<instance-id>- شروع می‌شوند تا اطمینان حاصل شود که هر تابع یک نام منحصر به فرد دارد، مشابه پیشوند ext-<extension-instance-id>- در افزونه‌ها. برای کسب اطلاعات بیشتر در مورد نحوه استفاده از کیت‌های تابع به عنوان بخشی از مهاجرت، به راهنمای مهاجرت کاربر ما مراجعه کنید.

نصب کیت از npm استفاده می‌کند؛ اگر بخواهم از Yarn یا یک مدیر بسته سازگار با Node استفاده کنم، چه می‌شود؟

ما در حال حاضر برنامه‌ای برای پشتیبانی از Yarn یا سایر ابزارهای مدیریت بسته نداریم. نصب کیت با اجرای مستقیم دستورات npm هنگام تنظیم کد منبع کیت در اولین نصب انجام می‌شود.

به عنوان یک جایگزین، می‌توانید یک دایرکتوری منبع ایجاد کنید، بسته npm کیت را خودتان نصب کنید و آن را با ساخت‌ها و صادرات مناسب تنظیم کنید. به الگوهای index-kit TypeScript ما در firebase-tools مراجعه کنید یا به عنوان مثال به یک کیت نصب شده با npm نگاه کنید. پس از انجام این کار، می‌توانید آن را مانند یک کیت محلی با استفاده از --directory به جای --package نصب کنید. از این به بعد، باید کیت را با دایرکتوری یا شناسه شناسایی کنید، اما می‌توانید از دستورات کیت برای اضافه کردن و حذف نمونه‌ها استفاده کنید.

افزونه‌ی من از مخزن داکر یا پارامترهای سیستم پیشرفته‌ی کلید KMS استفاده می‌کند؛ چگونه می‌توانم این را در کیت‌های تابع پیکربندی کنم؟

در حال حاضر، ما از پیکربندی مخزن داکر یا کلید KMS در Cloud Functions برای Firebase پشتیبانی نمی‌کنیم. اگر از افزونه‌ای با این پارامترهای سیستمی پیکربندی شده مهاجرت می‌کنید و می‌خواهید این قابلیت را حفظ کنید، می‌توانید پارامترها را با استفاده از gcloud CLI به توابع کیت جدید خود اعمال کنید.

پیش‌نیازها

1. کیت تابع خود را ابتدا با پیروی از راهنماهای مهاجرت مستقر کنید تا توابع در Google Cloud وجود داشته باشند.

2. متغیرهای محیطی خود را در ترمینال خود تعریف کنید:

   export PROJECT_ID="YOUR_PROJECT_ID"
   export FUNCTION_REGION="YOUR_REGION"          # e.g. us-east1
   export KIT_NAME="YOUR_KIT_NAME"                # e.g. firestore-bigquery-export
   export SOURCE_DIR="YOUR_KIT_SOURCE_DIR"       # e.g. "./function-kits/${KIT_NAME}/source"
   export REPO_NAME="YOUR_DOCKER_REPO_NAME"
   export KEY_RING="YOUR_KMS_KEY_RING"
   export KEY_NAME="YOUR_KMS_KEY_NAME"
   
   # Retrieve Project Number automatically
   export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
   

3. .gcloudignore را از قبل در ریشه منبع کیت ایجاد کنید تا فایل‌های کامپایل شده توسط .gitignore نادیده گرفته نشوند:

   cat << 'EOF' > "${SOURCE_DIR}/.gcloudignore"
   .gcloudignore
   .git
   .gitignore
   
   node_modules
   #!include:.gitignore
   !lib/**
   EOF
   

4. مجوزهای مورد نیاز IAM را اعطا کنید:

   • برای کلیدهای KMS (دسترسی رمزگشایی را به نمایندگان سرویس اعطا می‌کند):

     for SERVICE_ACCOUNT in \
       "service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcf-admin-robot.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcp-sa-artifactregistry.iam.gserviceaccount.com"
     do
       gcloud kms keys add-iam-policy-binding "$KEY_NAME" \
         --keyring="$KEY_RING" \
         --location="$FUNCTION_REGION" \
         --project="$PROJECT_ID" \
         --member="serviceAccount:${SERVICE_ACCOUNT}" \
         --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"
     done
     

   • برای Artifact Registry (دسترسی نوشتن به Cloud Build و دسترسی خواندن به Cloud Run را اعطا می‌کند):

     # Grant the Cloud Build / Compute Service Account permission to write images to the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
       --role="roles/artifactregistry.writer"
     
     # Grant Cloud Run permission to pull images from the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       --role="roles/artifactregistry.reader"
     

اعمال تنظیمات با استفاده از gcloud CLI

gcloud functions deploy برای هر تابع در کیت خود اجرا کنید:

gcloud functions deploy FUNCTION_NAME \
  --project="$PROJECT_ID" \
  --region="$FUNCTION_REGION" \
  --source="./function-kits/${KIT_NAME}/source" \
  --docker-repository="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/repositories/${REPO_NAME}" \
  --kms-key="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME}"

توجه داشته باشید که این راهکار تحت شرایط زیر با شکست مواجه می‌شود:

1. نمونه‌های جدید کیت : اضافه کردن یک نمونه در firebase.json یک منبع جدید Cloud Functions v2 ایجاد می‌کند که به طور پیش‌فرض روی کلیدهای مدیریت‌شده توسط گوگل و gcf-artifacts تنظیم شده است. برای هر نمونه جدید باید gcloud اجرا کنید.
2. بازآفرینی تابع : تغییر نوع تریگر (برای مثال، از HTTPS به تریگر Cloud Firestore )، تغییر نقطه ورود یا تغییر نام باعث می‌شود که Firebase CLI تابع قدیمی را حذف کرده و یک تابع جدید ایجاد کند. تابع جدید این تنظیمات را تا زمانی که دوباره gcloud اجرا کنید، از دست می‌دهد.
3. تغییر پیکربندی : رابط خط فرمان Firebase وضعیت مخزن KMS یا داکر را در firebase functions:list یا لاگ‌های diff نمایش نمی‌دهد، که این امر حسابرسی زیرساخت را دشوار می‌کند.

تأیید موفقیت

برای تأیید اعمال مخزن و کلید رمزگذاری، دستور زیر را اجرا کنید:

gcloud functions describe FUNCTION_NAME \
  --region="$FUNCTION_REGION" \
  --project="$PROJECT_ID" \
  --format="yaml(state, buildConfig.dockerRepository, kmsKeyName)"