| اختيار مسار نقل البيانات: | نقل البيانات إلى حِزم الدوال على npm نقل البيانات إلى حزمة دوال من إنشاءك |
إذا لم ينشئ الناشر حزمة بديلة رسمية يتم توزيعها على npm، سيرشدك هذا الدليل إلى خطوات إنشاء نسخة من إضافته وإعدادها كحزمة وظائف محلية.
التحقّق من القيود المعروفة المفروضة على عملية نقل البيانات
قبل البدء في نقل مثيل إضافة، تحقَّق ممّا إذا كان الإعداد يستخدم أيًا من الميزات التالية التي تتطلّب حلاً بديلاً أو غير متاحة بعد في حِزم الدوال:
- تتطلّب مستودعات Docker المخصّصة ومفاتيح KMS حلاً بديلاً يدويًا لا يتيح Cloud Functions for Firebase استبدال مَعلمات النظام لتكوين مستودع Docker مخصّص أو مفتاح تشفير يديره العميل (مفتاح KMS). إذا كان الإضافة تضبط أيًا من هاتين المَعلمتَين، يُرجى الرجوع إلى الحل البديل في الأسئلة الشائعة.
قبل البدء
عليك إعداد Firebase CLI وإعداد Firebase
مشروع. عند استخدام واجهة سطر الأوامر، تأكَّد من استخدام الإصدار firebase-tools من >= 15.32.0، الذي يتضمّن أوامر نقل البيانات الجديدة وأدوات الوظائف.
الأذونات والأدوار المطلوبة للحساب
استنادًا إلى ما يجب إنشاؤه وضبطه من خلال واجهة سطر الأوامر Firebase أثناء عملية النقل، يجب أن يتضمّن الحساب الذي تستخدمه للمصادقة باستخدام Firebase وGoogle Cloud الأدوار التالية:
roles/firebaseextensions.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreator-
roles/cloudfunctions.admin(إذا كنت بحاجة إلى تنفيذsetIamPermissionsلنقاط النهاية العامة) roles/secretmanager.admin(في حال استخدام الأسرار)roles/serviceusage.serviceUsageAdmin(في حال كنت بحاجة إلى تفعيل واجهات برمجة تطبيقات جديدة)
ننصحك باستخدام حساب سبق أن ثبّت إضافات ونشر وظائف، لأنّه من المحتمل أن تكون معظم هذه الأذونات قد تم منحها مسبقًا. إذا كان حسابك الذي يتم نقل بياناته بحاجة إلى المزيد من الأدوار، اتّبِع Google Cloud تعليمات إدارة الهوية وإمكانية الوصول لإضافتها.
ترقية مثيل الإضافة إلى أحدث إصدار
يجب تحديث الإضافة إلى أحدث إصدار لتقليل الفرق بين نسخة الإضافة وحزمة الاستبدال. إذا لم تتم ترقية الإضافة، قد تحدث تغييرات كبيرة غير متوافقة بين نسخة الإضافة واستبدالها بالحزمة. قد لا يتطابق الإعداد الذي تم تصديره مع ما تتوقّعه الحزمة بسبب تغييرات المَعلمات في الإصدارات المختلفة.
استخدِم أحد الخيارات التالية لتحديث الإضافة، وذلك حسب مكان تثبيتها:
- من وحدة تحكّم Firebase
- من واجهة سطر الأوامر (CLI) في Firebase باستخدام:
firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>
في حال تخطّي هذه الخطوة، ستطلب منك واجهة سطر الأوامر الترقية عند تصدير الإعدادات إذا لم يكن إصدار الإضافة هو الأحدث.
تشعّب الإضافة إلى حزمة الوظائف المحلية
قبل البدء في تحويل إضافة إلى مجموعة أدوات وظائف محلية، تأكَّد من أنّ رمز المصدر للإضافة يقع داخل مشروع Firebase. لإجراء ذلك، استنسِخ مستودع الإضافة من GitHub، وأنشئ دليلاً داخل جذر مشروعك Firebase، وانسخ مجلد functions/ الخاص بالإضافة وملف extension.yaml إليه:
mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.
اتّبِع الخطوات من 1 إلى 8 الواردة في دليل نقل الناشرين لنقل رمز المصدر الخاص بالإضافة إلى دالة من الجيل الثاني. بعد ذلك، اتّبِع الخطوات التالية.
إتاحة دعم حزمة الأدوات المحلية لمنطقة الوظائف التي تم تصديرها والمعلَمات المتقدّمة
في حزمة وظائف محلية، لا تنشئ أداة Firebase CLI ملف index.ts
لإعداد الحزمة وضبطها لاستخدام مَعلمات النظام التي تم نقلها.
لاستخدام منطقة الدالة والمعلَمات المتقدّمة التي تم ضبطها للإضافة، عليك إعداد ملف index.ts لقراءة التنسيق الذي تم تصديره من خلال firebase
ext:export --mode functions إلى ملف متغيّر بيئة.
على وجه التحديد، في ملف index.ts ذي المستوى الأعلى الذي يصدّر الدوال، حدِّد مَعلمة FUNCTION_DEFAULT_REGION واستدعِ setGlobalOptions باستخدام متغيّرات البيئة بالتنسيق EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>، على غرار نموذج index-kit-migration.ts الذي تستخدمه واجهة سطر الأوامر:
import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";
export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
input: { text: { nonEmpty: true } },
description: "Global default region where functions should be deployed. Can be overridden per-function.",
});
setGlobalOptions({
region: regionParam,
memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
: undefined,
vpcConnectorEgressSettings:
process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
: undefined,
vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
: undefined,
minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
: undefined,
ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
// Parses a comma-separated string of key:value pairs into a key-value object
// (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
(acc, curr) => {
const [key, value] = curr.split(":");
const trimmedKey = key?.trim();
const trimmedValue = value?.trim();
if (!trimmedKey || !trimmedValue) {
return acc;
}
acc = acc ?? {};
acc[trimmedKey] = trimmedValue;
return acc;
},
undefined,
)
: undefined,
});
// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";
اختبار حزمة تطوير البرامج قبل نقل البيانات
يتوفّر لديك الآن حزمة وظائف محلية، وعند نشرها، ستتصرّف بشكل مطابق لتثبيت جديد للإضافة. الخطوة التالية هي التحقّق من أي مشاكل تم إدخالها عن طريق الخطأ أثناء عملية النقل وحلّها قبل نقل مثيلات إضافة الإصدار العلني إلى هذا الإصدار.
أولاً، أضِف نسختك المتفرّعة كحزمة محلية، ثم اضبطها، ونفِّذها في مشروع تجريبي. يجب أن تكون حِزم الدوال المحلية داخل مشروع Firebase، لذا إذا كان مستودع الإضافات المستنسخ خارج مشروع Firebase، عليك نقله إلى داخل دليل المشروع. بعد ذلك، شغِّل أمر تثبيت الحزمة التالي لتثبيتها كحزمة محلية:
firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>
يرشدك هذا الأمر إلى كيفية اختيار رقم تعريف مجموعة أدوات ورقم تعريف نسخة اختبارية وإعداد لنسخة الاختبارية الأولى. بعد ذلك، يعدّل الملف firebase.json لتسجيل حزمة محلية تشير إلى الدليل المتفرّع، مع تخزين إعدادات كل مثيل في الملف .env في function-kits/<kit-id>/config-<instance-id>.
انشر حزمة الأدوات المحلية في مشروع تجريبي يتضمّن الموارد المناسبة لاختبار سلوكها. إذا سبق لك إعداد مشروع تجريبي من خلال اختبار الإضافة، نفِّذ الأمر التالي:
firebase deploy --only functions:<kit-instance-id> --project <test-project-id>
مثال: بث Cloud Firestore إلى BigQuery
(firestore-bigquery-export)
التحقّق من مزامنة البيانات من Cloud Firestore إلى BigQuery بشكل تام بين الأطراف:
- في صفحة Cloud Firestore ضمن وحدة تحكّم Firebase، أنشئ المجموعة التي ضبطتها على
COLLECTION_PATH(users) إذا لم تكن موجودة من قبل. - أنشئ مستندًا باسم
bigquery-mirror-testيحتوي على أي حقول بأي قيم. في صفحة BigQuery ضمن وحدة تحكّم Google Cloud، استعلم عن جدول سجلّ التغيير الأولي. يجب أن يحتوي على صف واحد يسجّل عملية إنشاء المستند:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`استعلم عن آخر عرض، والذي من المفترض أن يعرض آخر حدث تغيير للمستند الوحيد المتوفّر (
bigquery-mirror-test):SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`احذف المستند
bigquery-mirror-testفي Cloud Firestore. ويختفي من العرض الأخير، ويتم إلحاق حدثDELETEبجدول سجلّ التغيير الأولي.يمكنك الاطّلاع على السجلّ الكامل لمستند واحد باستخدام:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog` WHERE document_name = "bigquery-mirror-test" ORDER BY timestamp ASC
الاختلافات عن اختبار الإضافة:
- يتم نشر المشغّل على النحو
kit-<kit-instance-id>-fsexportbigquery، وليسext-<instanceId>-fsexportbigquery. ابحث عن هذا الاسم في Cloud Functions لوحة البيانات والسجلات. - يتم تشغيل الرمز في Firebase Local Emulator Suite كدوال عادية. يمكنك ضبط قيم المَعلمات لاستخدامها في المحاكي باستخدام
.env.local. يمكنك أيضًا إجراء اختبارات الوحدة للرمز باستخدام حزمة تطوير البرامج (SDK)firebase-functions-testكما هو موضّح في اختبار الوحدة في Cloud Functions. - لم يعُد توفير الموارد يعتمد على وقت تشغيل الإضافات. إذا كان جدول سجلّ التغيير غير متوفّر بعد النشر، أعِد تنفيذ مهمة الإعداد يدويًا:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. المهمة متكررة، لذا تؤدي إعادة تشغيلها إلى تسوية مجموعة البيانات والجدول وطرق العرض. - تأتي قيم المَعلمات من
.envبدلاً من نموذج التثبيت، لذا لن تكون عمليات إعادة تشغيلfirebase deployتفاعلية بعد اكتمال.env.
(اختياري) تنظيف البيانات بعد الاختبار
إذا أردت إزالة هذه النسخة الاختبارية بعد الانتهاء من الاختبار، عليك إلغاء تثبيتها باتّباع الخطوات التالية:
firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>
يؤدي هذا الإجراء إلى حذف جميع موارد السحابة الإلكترونية التي تم إنشاؤها من خلال نشر الحزمة وإزالة إعدادات مثيلها. إذا كان لديك نسخة واحدة فقط من الحزمة، سيؤدي ذلك أيضًا إلى إزالة إدخال الحزمة من firebase.json. لا يؤدي ذلك إلى حذف دليل رمز المصدر المحلي. عند تثبيت الحزمة لنقل بيانات الإنتاج، يمكنك اختيار رقم تعريف الحزمة مرة أخرى.
نقل البيانات من الإضافات إلى حزمة الأدوات المحلية
بعد اختبار حزمة التطبيق المحلية، يمكنك نقل نسخة التطبيق المنشور.
1. تثبيت مثيل لمجموعة وظائف الاستبدال
ثبِّت حزمة الدوال المحلية، مع تمرير --no-configure لتخطّي عملية الإعداد اليدوي، كي تتمكّن الخطوة التالية من تصدير إعدادات الإضافة الحالية مباشرةً إلى مثيل هذه الحزمة:
firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>
2. ضبط مثيل حزمة الدوال بشكل مطابق للإضافة
عليك تخصيص نسخة حزمة تطوير البرامج هذه باستخدام إعدادات مطابقة للإضافة التي يتم استبدالها. يمكنك تصدير إعدادات مثيل الإضافة إلى ملف .env، الذي يخزّن بيانات إعدادات المَعلمات ومتغيّرات البيئة ومراجع الأسرار لجميع Cloud Functions، بما في ذلك الحِزم. لتصديرها مباشرةً إلى ملف الإعداد الخاص بحزمة تطوير البرامج، نفِّذ ما يلي:
firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>
في نهاية هذه الخطوة، يتم تخزين معلومات الإعداد لهذا الجهاز الظاهري في ملف .env خاص بالمشروع في دليل إعدادات الجهاز الظاهري، مثل:
function-kits/<kit-name>/config-<instance-id>/.env.<project-id>
3- نشر عملية استبدال مجموعة أدوات الاستشعار والتحقّق منها
بعد تثبيت الحزمة وتوفّرها كمجموعة من الدوال، يمكنك نشر بديل الحزمة. تعمل حِزم الدوال مثل الدوال العادية، حيث يعمل كل مثيل من الحزمة كقاعدة رموز منفصلة لتنظيم الدوال. يمكنك اختيار نشر جميع الدوال أو مثيل حزمة معيّن فقط. أثناء نقل مثيل إضافة واحد، لا تنشر سوى مثيل الحزمة هذا.
إذا كانت حزمة الأدوات تستخدم أي مَعلمات جديدة لم تكن متوفّرة في مثيل الإضافة الذي نقلت منه، سيطلب منك واجهة سطر الأوامر Firebase إدخالها في بداية عملية النشر. لا يُتوقّع حدوث ذلك في هذا المثال العملي من إضافة firestore-bigquery-export حديثة، ولكن العديد من الحِزم تطلب مَعلمة جديدة لأي مصدر لتفعيل الأحداث تستخدمه الحزمة. وكجزء من عملية النقل هذه، تستخدم الحِزم المعدَّلة دوال الجيل الثاني، بينما كانت الإضافات تستخدم دوال الجيل الأول. في الجيل الثاني، تقع الدوال بالقرب من مصادر الأحداث الخاصة بها، ويتم إضافتها كمَعلمة إضافية. في التحديثات المستقبلية، إذا تمت إضافة مَعلمات جديدة، سيطلب منك واجهة سطر الأوامر إدخالها عند النشر التالي.
مثال محلول:
firebase deploy --only functions:firestore-bigquery-export --project my-project
الناتج:
=== Deploying to 'my-project'...
i deploying functions
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i functions: ensuring required API bigquery.googleapis.com is enabled...
i functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔ functions: required APIs are enabled
i functions: granting declarative IAM roles to managed service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
✔ functions: successfully granted IAM roles
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔ functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔ Deploy complete!
للتحقّق من أنّ firebase deploy لم يتضمّن أي أخطاء، راجِع سجلّات النشر لمعرفة ما إذا تم تشغيل أي خطافات لدورة الحياة. تستخدم الإضافات الشائعة، مثل Stream Cloud Firestore إلى BigQuery، خطافات مراحل النشاط. في ما يلي مثال على شكل خطاف دورة الحياة عند تشغيله:
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project
تؤكّد رسائل السجلّ هذه ما يلي:
- تم العثور على خطاف دورة حياة وتنفيذه.
- تمت إضافة مهمة إلى قائمة انتظار المهام المرتبطة بخطاف دورة الحياة.
- تم توفير رابط إلى Cloud Logging حتى تتمكّن من التأكّد من أنّ المهمة اكتملت بدون أخطاء.
اتبع رابط السجلّات إلى وحدة تحكّم Google Cloud للتحقّق من عدم وجود أي أخطاء في السجلّات ومن أنّه تمت معالجة حدث قائمة انتظار المهام بنجاح. إذا لم يتم تنفيذ حدث يتم في مراحل النشاط بنجاح، يمكنك إعادة تشغيله من خلال تنفيذ ما يلي:
firebase functions:lifecycle:run <hook-name> <codebase>
إذا كنت بصدد نشر مثيل لحزمة دوال للمرة الأولى، نفِّذ ما يلي:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
إذا أردت في أي وقت أثناء عملية التحقّق إيقاف عملية النقل هذه أو التراجع عنها، يمكنك إلغاء تثبيت الحزمة باتّباع التعليمات الواردة في مقالة إلغاء تثبيت الإضافة.
4. إلغاء تثبيت الإضافة
بعد إثبات ملكية مجموعة الدوال التي تم نشرها، يمكنك إلغاء تثبيت الإضافة حتى لا يتكرّر سلوكها مرة للمجموعة ومرة للإضافة. يمكنك إلغاء تثبيت جميع الإضافات من واجهة سطر الأوامر Firebase بغض النظر عن طريقة تثبيتها، وذلك إذا أضفت العلامة --immediate:
firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate
مثال محلول:
firebase ext:uninstall firestore-bigquery-export --project my-project --immediate
الناتج:
i extensions: uninstalling firestore-bigquery-export...
i extensions: deleting extension instance resources in project my-project...
✔ extensions: successfully uninstalled firestore-bigquery-export
عمليات نقل البيانات المتقدّمة
يمكنك استخدام الإضافات في عدة مشاريع Firebase تريد إدارتها باستخدام قاعدة رموز برمجية واحدة. على سبيل المثال، إذا نشرت البنية الأساسية نفسها في بيئة testing وبيئة production، وكان لكل منهما مثيل documents Cloud Firestore تصدّره إلى BigQuery، قد يكون لديك مثيلان من إضافة firestore-bigquery-export مثبّتَين:
export-documents-testingexport-documents-production
إذا نقلت مثيلَي الإضافة هذين إلى مثيلَي حزمة وظائف في قاعدة رموز برمجية واحدة عند استخدام واجهة سطر الأوامر Firebase ونشرت باستخدام firebase deploy --project testing وfirebase deploy --project production، سيؤدي كل نشر إلى إنشاء مثيلَين في كل من بيئتَي testing وproduction.
بدلاً من ذلك، استبدِل مثيلَي الإضافة بمثيل واحد من حزمة الدوال firestore-bigquery-export تم نشره في مشاريع متعددة، حيث يحتوي كل مشروع على إعداداته الخاصة. يجب أن يبدو دليل الإعدادات الخاص بالمثيل على النحو التالي:
config-export-documents/.env.testing.env.production
يؤدي كل نشر في testing وproduction إلى إنشاء مثيل واحد من حزمة تطوير البرامج مع الإعدادات المقابلة. تنشئ أوامر واجهة سطر الأوامر الحالية عملية الإعداد هذه طالما أنّك تمرّر العلامة --project في كل استدعاء للأمر ext:migrate أو functions:kits:install.
مثال محلول:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔ Wrote function-kits/firestore-bigquery-export/source/package.json
✔ Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔ Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔ Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i functions: Running npm install
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
--kit-instance export-documents --project testing
# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
--kit-instance export-documents --project production
يتوفّر لديك الآن مثيل واحد من الحزمة تم إعداده ليتم نشره في مشروعَي testing وproduction مع الإعدادات الخاصة بكل منهما. إذا أنشأت مثيلاً في المشروع testing ونفّذت الأمر functions:kits:install للحزمة نفسها في المشروع production، سيُطلب منك اختيار إعادة استخدام المثيل الذي تم إعداده للمشروع testing أو تثبيت مثيل ثانٍ.