В этом руководстве рассказывается, как перенести расширения из устаревшей среды Firebase Extensions в функцию, которую пользователи устанавливают и развертывают в собственной базе кода Cloud Functions для Firebase (второе поколение).
Это рекомендуемый способ переноса. Firebase будет поддерживать список расширений с официальными эквивалентами npm. В этом руководстве рассказывается, как создать собственный эквивалент.
В этом руководстве в качестве примера используется расширение Stream Cloud Firestore to BigQuery (firestore-bigquery-export). Каждый раздел заканчивается примером, который показывает, как расширение выглядело до переноса и как оно выглядит после него в виде пакета @firebase-function-kits/firestore-bigquery-export.
Зарегистрируйтесь, чтобы получить больше информации и помощь по переносу расширений
Если у вас есть вопросы о том, как перейти с Firebase Extensions, свяжитесь с нами по адресу firebase-extensions-migrator-support-external@google.com. Мы также будем отправлять в эту группу электронные письма, когда будем обновлять руководство, добавляя в него информацию об упаковке, тестировании и распространении функций второго поколения.
Чтобы присоединиться к этой группе, отправьте сообщение на адрес firebase-extensions-migrator-support-external+subscribe@google.com. В ответ вы получите письмо с запросом на вступление. Вам нужно ответить на это письмо, а не нажимать кнопку "Присоединиться к группе".
Подготовка
Чтобы выполнить перенос, как описано в этом руководстве, вам понадобятся следующие функции Cloud Functions:
Конфигурация с параметрами. Каждый параметр, объявленный в
extension.yaml, становится определенным параметром в коде пакета.Декларативные роли IAM и необходимые API. Каждая роль, объявленная в
extension.yaml, становится вызовомrequiresRole(...), а каждый API – вызовомrequiresAPI(...)в коде пакета. При развертывании CLI Firebase предоставляет объявленные роли управляемому сервисному аккаунту среды выполнения и включает объявленные API от вашего имени.События жизненного цикла для баз кода Cloud Functions. Базы кода Cloud Functions теперь поддерживают события жизненного цикла, аналогичные Firebase Extensions. Объявите настройку во время установки и обновления с помощью хуков жизненного цикла
afterFirstDeploy(...)иafterRedeploy(...). Они заменяютlifecycleEvents, объявленные вextension.yaml.
Перенос источника Firebase Extensions в функцию второго поколения
(Необязательно) Автоматический перенос с помощью навыка агента Firebase
Вы можете автоматизировать шаги 1–8 (инвентаризация ресурсов, обновление триггеров, преобразование параметров и секретов, декларативное управление идентификацией и доступом, хуки жизненного цикла и создание файла README для пакета) с помощью официального навыка ИИ-агента extension-to-functions-codebase.
Установить навык
Если вы или ваш ИИ-помощник разработчика (Gemini в Firebase, Cursor, Claude Code, GitHub Copilot) ещё не установили навык, выполните следующую команду в CLI навыков:
npx skills add firebase/agent-skills --skill extension-to-functions-codebase
После установки навыка в проект ИИ-помощник разработчика автоматически следует правилам переноса и этапам преобразования. Вы можете использовать следующий запрос:
"Please migrate this Firebase Extension into a publishable 2nd Gen Function Kit
package following the instructions in the extension-to-functions-codebase
skill."
1. Как провести инвентаризацию расширения
Начните с инвентаризации вашего расширения: полного списка всего, что расширение объявляет, поставляет и документирует, чтобы каждое поведение имело определенное назначение в функции 2-го поколения и ничего не было потеряно при миграции.
Проверьте каждый из следующих пунктов и запишите, что вы обнаружили:
extension.yaml, в котором объявляются параметры, функции, события, роли IAM, необходимые API, секреты и хуки жизненного цикла.functions/, который содержит код функции, зависимости, конфигурацию сборки, триггеры и функции очереди задач.README.md,PREINSTALL.mdиPOSTINSTALL.md, которые содержат инструкции по настройке, предупреждения и примечания по оплате.scripts/, который содержит утилиты для импорта, заполнения, IAM, восстановления или переноса, а также любые другие инструменты, которые вы поставляете вместе с расширением.
Затем для каждого элемента в extension.yaml решите, куда он будет помещен в пакете npm:
Преобразуйте конфигурацию пользователя в параметры Cloud Functions (шаг 4).
Преобразуйте секреты в секреты Cloud Functions (шаг 4).
Преобразуйте роли IAM в объявления
requiresRole(...)(шаг 6).Преобразуйте необходимые API Google в объявления
requiresAPI(...), где это возможно (шаг 6).Преобразуйте хуки установки и обновления в объявления
afterFirstDeploy(...)иafterRedeploy(...)(шаг 7).Преобразуйте идентификаторы экземпляров из
EXT_INSTANCE_IDвFIREBASE_KIT_INSTANCE_ID(шаг 4).
Пример. Поток Cloud Firestore в BigQuery
При чтении firestore-bigquery-export/extension.yaml и functions/ получается следующий инвентарь:
Место: extension.yaml |
Количество/ценность | Куда отправляются данные |
|---|---|---|
params |
25 (COLLECTION_PATH, DATASET_ID, TABLE_ID, DATASET_LOCATION, VIEW_TYPE, …) |
Cloud Functions params (Шаг 4) |
apis |
bigquery.googleapis.com |
requiresAPI(...) (Шаг 6) |
roles |
bigquery.dataEditor, datastore.user, bigquery.user |
requiresRole(...) (Шаг 6) |
resources |
1 триггер события (fsexportbigquery) + функции очереди задач (initBigQuerySync, setupBigQuerySync) |
Экспортированные функции пакета (шаг 3) |
lifecycleEvents |
onInstall → initBigQuerySync; onUpdate / onConfigure → setupBigQuerySync |
afterFirstDeploy/afterRedeploy (шаг 7) |
| Идентификатор экземпляра | Не используется (нет считываний EXT_INSTANCE_ID) |
Нет данных для переноса |
scripts/ |
import/ (заполнение), gen-schema-view/ |
Остаются скриптами (не рассматриваются в этой статье) |
Анализ. Расширение не объявляет параметры type: secret, поэтому на шаге 4 не нужно переносить секреты. Триггер события уже относится ко второму поколению, а функции очереди задач – к первому (это важно для шага 3).
2. Обновите package.json
Обновите файл package.json расширения. Если вы переносите одно расширение, это может быть корневой каталог package.json. Если вы переносите несколько расширений в одном хранилище, создайте для каждого из них отдельный пакет.
Минимальные версии SDK. Объявите firebase-functions >=
7.4.0 и firebase-admin >=
14.2.0 как зависимости. Объявите свою версию firebase-functions как одноранговую зависимость, чтобы в проекте Cloud Functions ваших пользователей была та же версия SDK, с которой была написана ваша библиотека.
{
"name": "<package-name>",
"version": "1.0.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"exports": {
".": {
"types": "./lib/index.d.ts",
"default": "./lib/index.js"
}
},
"engines": {
"node": "22"
},
"peerDependencies": {
"firebase-functions": "^7.4.0"
},
"dependencies": {
"firebase-functions": "^7.4.0",
"firebase-admin": "^14.2.0"
}
}
Пример. Поток Cloud Firestore в BigQuery
До. Файл functions/package.json расширения является закрытым, содержит идентификатор расширения и объявляет firebase-functions как прямую зависимость:
{
"name": "firestore-bigquery-export",
"main": "lib/index.js",
"private": true,
"dependencies": {
"@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
"firebase-admin": "^14.2.0",
"firebase-functions": "^6.3.2"
}
}
После. Публикуемый пакет: название области видимости, сопоставление exports и firebase-functions перемещено в peerDependencies:
{
"name": "@firebase-function-kits/firestore-bigquery-export",
"version": "0.1.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"exports": {
".": {
"types": "./lib/index.d.ts",
"default": "./lib/index.js"
}
},
"engines": {
"node": "22"
},
"peerDependencies": {
"firebase-functions": "^7.4.0"
},
"dependencies": {
"@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
"firebase-admin": "^14.2.0",
"firebase-functions": "^7.4.0"
}
}
3. Как перейти с функций первого поколения на функции второго поколения
Если ваше расширение по-прежнему экспортирует функции первого поколения, преобразуйте каждый триггер в эквивалент второго поколения. Импортируйте из модулей firebase-functions/... и передайте настройки среды выполнения в параметрах триггера.
Ознакомьтесь с руководством по переходу на Cloud Functions второго поколения. В частности, вы можете минимизировать усилия по переписыванию, используя деструктуризацию исправленных событий второго поколения и избегая переписывания логики вашей функции, поскольку SDK второго поколения предоставляет параметры версии 1 в качестве полей в объекте события, что позволяет вам использовать деструктурированные/именованные параметры и сохранять вашу бизнес-логику без изменений.
До. Первое поколение:
import * as functions from "firebase-functions/v1";
export const sync = functions.firestore
.document("{collectionId}/{documentId}")
.onWrite(async (change, context) => {
await handleWrite(change.before, change.after, context.params);
});
После. 2-е поколение:
import { onDocumentWritten } from "firebase-functions/firestore";
export const syncV2 = onDocumentWritten(
{ document: "{collectionId}/{documentId}" },
async ({ change, context }) =>
await handleWrite(change.before, change.after, context.params)
);
Полный список различий между функциями первого и второго поколений приведен в сравнении версий Cloud Functions.
Существенное различие между функциями 1-го и 2-го поколений заключается в том, что функции 2-го поколения должны быть размещены вместе с ресурсами триггеров. При переходе с расширения, использующего функции первого поколения, на набор, использующий функции второго поколения, пользователям может потребоваться изменить местоположение функций, чтобы соответствовать этому требованию.
Если пользователи выбрали местоположение Cloud Functions, оно может быть нарушено во время переноса, поскольку существующее местоположение сохраняется. Если функции расширения, активируемые событиями, зависели от местоположения функций, предоставленных пользователем, мы рекомендуем добавить в расширение новый параметр, чтобы собирать данные о местоположении триггера события и сопоставлять их с новым местоположением функции.
Пример. Поток Cloud Firestore в BigQuery
defineString("DATABASE_REGION", {
label: "Firestore Instance Location",
description:
"Where is the Firestore database located? You can check your current database location at https://console.cloud.google.com/firestore/databases. The functions in this kit deploy to the Cloud Run region closest to this location.",
input: select({
"Multi-region (Europe - Belgium and Netherlands)": "eur3",
"Multi-region (United States)": "nam5",
"Multi-region (Iowa, North Virginia, and Oklahoma)": "nam7",
"Iowa (us-central1)": "us-central1",
// More locations...
})
});
// Firestore multi-region locations are not Cloud Run regions; deploying a
// function to one hard-fails, so they map to a region inside the multi-region.
const MULTI_REGION_TO_FUNCTION_REGION: Record<string, string> = {
nam5: "us-central1",
nam7: "us-central1",
eur3: "europe-west1",
};
/**
* Maps a Firestore database location to the Cloud Run region the functions
* should deploy to. The lookup is case-insensitive and ignores surrounding
* whitespace, as the CLI's own region handling is. Regional locations pass
* through lowercased; an unset or blank location returns `undefined`, meaning
* the functions declare no region.
*/
export function firestoreLocationToFunctionRegion(
location: string | undefined
): string | undefined {
const normalized = location?.trim().toLowerCase();
if (!normalized) {
return undefined;
}
return MULTI_REGION_TO_FUNCTION_REGION[normalized] ?? normalized;
}
const functionRegion = firestoreLocationToFunctionRegion(
process.env.DATABASE_REGION
);
export const fsexportbigquery = onDocumentWritten(
{
region: functionRegion,
// Other configuration
},
(event) => handleDocumentWrite(event, getHandlerContext())
);
При первом развертывании набора пользователям будет предложено указать DATABASE_REGION, и функции будут развернуты в соответствующем functionRegion, что устранит любые проблемы с местоположением для их функций, активируемых событиями gen2.
4. Преобразование параметров и секретов расширения
Параметры
Каждый параметр, объявленный в extension.yaml, становится параметром Cloud Functions.
Преобразуйте прямое чтение переменных среды:
const collectionPath = process.env.COLLECTION_PATH;
в Cloud Functions параметров:
import { defineString } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";
const collectionPath = defineString("COLLECTION_PATH");
// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
{ document: collectionPath },
async (event) => {
// Call .value() to read the string inside a handler
const path = collectionPath.value();
await handleWrite(path, event);
}
);
Используйте collectionPath.value(), чтобы прочитать строку в обработчике, и collectionPath там, где ожидается плейсхолдер, например в пути триггера функции.
Интерфейс командной строки Firebase обнаруживает параметры и считывает их значения из .env, .env.<projectId> или запрашивает их у пользователей во время развертывания. Сохраните названия параметров, чтобы перенести значения из существующей установки.
Не меняйте названия параметров, объявленных в коде. При переносе расширений существующие значения параметров конечных пользователей сохраняются автоматически, но только если названия не меняются.
Пример. Поток Cloud Firestore в BigQuery
До. Параметр, объявленный в extension.yaml, считывается как необработанная переменная среды в config.ts:
# extension.yaml
- param: COLLECTION_PATH
label: Collection path
type: string
required: true
// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,
После. Один defineString; CLI обнаруживает его и считывает из .env:
// src/config.ts
import { defineString } from "firebase-functions/params";
collectionPath: defineString("COLLECTION_PATH", {
label: "Collection path",
// We now support "nonEmpty: true" to ensure a value other than the empty string
// is entered, analogous to "required: true" in extension.yaml
input: { text: { nonEmpty: true } }
}),
Название параметра не изменилось, поэтому существующий параметр .env продолжает работать.
Идентификатор экземпляра
Расширения считывают идентификатор своего экземпляра из EXT_INSTANCE_ID, внедренного средой выполнения расширений. Наборы функций считывают идентификатор своего экземпляра из FIREBASE_KIT_INSTANCE_ID, который CLI Firebase задает для каждого экземпляра набора в ключе экземпляра в сопоставлении instances в firebase.json. CLI предоставляет его во время обнаружения во время развертывания, в эмуляторе и развернутым функциям.
Идентификатор экземпляра не является параметром, поэтому не объявляйте его с помощью defineString. Префикс FIREBASE_... зарезервирован в файлах .env, поэтому пользователи не смогут задать или переопределить его. Значения, которые вставляет CLI, не видны системе параметров. Прочитайте его непосредственно из среды:
// Before
const instanceId = process.env.EXT_INSTANCE_ID;
// After
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
Переменная будет задана, только если пакет развернут как набор. Если ваш код также развернут как отдельная база кода (см. шаг 9), сделайте его необязательным или настройте быстрый сбой с понятным сообщением, если он отсутствует. Если в вашем расширении идентификатор экземпляра был пользовательским параметром, удалите его, так как теперь это значение принадлежит CLI Firebase.
Пример: удаление пользовательских данных
Расширение Stream Cloud Firestore to BigQuery не считывает идентификатор своего экземпляра, поэтому переносить нечего. Расширение Delete User Data использует его для присвоения названий темам издатель-подписчик.
До. Прочитайте как необработанную переменную среды в config.ts с префиксом ext-, который расширения используют для своих ресурсов:
// functions/src/config.ts
discoveryTopic: `ext-${process.env.EXT_INSTANCE_ID}-discovery`,
deletionTopic: `ext-${process.env.EXT_INSTANCE_ID}-deletion`,
После. Простое чтение process.env из FIREBASE_KIT_INSTANCE_ID, используемое для двух обычных параметров, чтобы пользователи могли переопределять названия тем:
// src/config.ts
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
// Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
// discovery without freezing an empty topic name into the manifest.
discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
default: `kit-${instanceId}-discovery`,
}),
deletionTopicName: defineString("DELETION_TOPIC_NAME", {
default: `kit-${instanceId}-deletion`,
}),
Значения по умолчанию не должны быть пустыми, поскольку привязки триггеров разрешаются во время обнаружения. В манифест развертывания в качестве названия темы будет записано пустое значение по умолчанию. Набор также защищен от запуска вне контекста набора. Если переменная отсутствует, значение по умолчанию на уровне модуля будет равно kit-undefined-discovery, поэтому загрузчик конфигурации завершится с ошибкой:
// ...
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
if (!instanceId) {
throw new Error(
"FIREBASE_KIT_INSTANCE_ID is not set. It is provided automatically to " +
"kit instances by firebase-tools >= 15.32.0; deploy or emulate this " +
"kit with a supported CLI version."
);
}
// ...
Эта проверка выполняется, когда обработчик впервые разрешает свою конфигурацию, поэтому отсутствующая переменная приводит к явной ошибке выполнения, а не к функциям, неявно привязанным к темам kit-undefined-*. Чтобы отклонить само развертывание, выполните проверку на уровне модуля, чтобы она выполнялась во время обнаружения. Поскольку CLI получает идентификатор экземпляра из firebase.json, настраиваемый INSTANCE_ID отсутствует и синхронизировать между несколькими экземплярами нечего.
Секреты
В extension.yaml секреты объявляются с помощью type: secret. Среда выполнения расширений сохраняет и связывает их, чтобы код расширения мог считывать process.env.PARAM_NAME напрямую. В типичной базе кода Cloud Functions вы объявляете и связываете каждый секрет явным образом:
import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";
const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);
После переноса расширения в пакет/набор npm ссылки на секреты управляются в файле .env конечного пользователя. Важно не менять названия секретов, объявленные в коде. Во время переноса секреты конечных пользователей переносятся соответствующим образом.
Пример. Триггерное письмо из Cloud Firestore
До. MAIL_COLLECTION и SMTP_PASSWORD считываются как необработанные переменные среды в config.ts:
# extension.yaml
- param: MAIL_COLLECTION
label: Email documents collection
type: string
default: mail
required: true
- param: SMTP_PASSWORD
label: SMTP password
type: secret
// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,
После. Один defineString и один defineSecret. CLI обнаруживает оба и считывает данные из .env:
import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";
const mailCollection = defineString("MAIL_COLLECTION", {
label: "Email documents collection",
default: "mail"
});
const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });
export const processQueue = onDocumentWritten(
{ document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
async (event) => {
const collection = mailCollection.value();
const password = smtpPassword.value();
// ...
}
);
5. Перенос внутренних вызовов очереди задач
Некоторые расширения ставят задачи в свои очереди задач из кода функции, используя Firebase Admin SDK. Это отличается от получения отправленной задачи (описано в разделах Обновление функций и Преобразование хуков жизненного цикла). В этом случае ваш код является производителем, который вызывает queue.enqueue(...).
В предыдущих версиях Admin SDK расширения должны были передавать собственный идентификатор экземпляра расширения в качестве второго параметра для таргетинга на функцию очереди задач в том же расширении. Начиная с версии firebase-admin 14.2.0, это не требуется и не рекомендуется. Теперь Task Queue API по умолчанию нацелен на очереди задач в том же контексте (например, расширение или набор). Вы можете удалить этот параметр из кода как в расширении, так и в отдельных функциях.
Удаление этого параметра обеспечивает переносимость и прямую совместимость.
Все остальные параметры вызова enqueue, такие как путь к ресурсу locations/<region>/functions/<name>, полезная нагрузка задачи и логика повторных попыток, остаются прежними.
Подробнее о том, как ставить функции в очередь с помощью Cloud Tasks, читайте в документации Cloud Tasks.
До. Расширение первого поколения:
import { getFunctions } from "firebase-admin/functions";
const queue = getFunctions().taskQueue(
`locations/${config.location}/functions/syncBigQuery`,
process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);
После. Расширение второго поколения:
import { getFunctions } from "firebase-admin/functions";
const queue = getFunctions().taskQueue(
`locations/${process.env.FUNCTION_REGION}/functions/syncBigQuery`
);
await queue.enqueue(taskData);
Если вызов enqueue нацелен на базу кода с префиксом, то у обнаруженного имени функции также будет префикс (например, orders-syncBigQuery). Подробнее о том, как проверить и установить экземпляр набора функций для замены и как протестировать набор функций…
6. Объявите необходимые API и роли IAM
Перенесите требования к IAM и API из файла extension.yaml в код:
import { requiresAPI, requiresRole } from "firebase-functions";
requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");
При декларативной безопасности CLI Firebase создает или обновляет управляемый сервисный аккаунт среды выполнения для базы кода и предоставляет ему объединение всех объявленных ролей. Сообщите пользователям, что все функции в базе кода выполняются с этими ролями, если только конечный API не поддерживает более узкую модель.
Пример. Поток Cloud Firestore в BigQuery
До. Объявлено в extension.yaml; среда выполнения расширений включила API и предоставила роли управляемому аккаунту:
apis:
- apiName: bigquery.googleapis.com
roles:
- role: bigquery.dataEditor
- role: datastore.user
- role: bigquery.user
После. Объявлено в коде с помощью requiresAPI и requiresRole:
import { requiresAPI, requiresRole } from "firebase-functions";
requiresAPI(
"bigquery.googleapis.com",
"Needed to write changelog rows and views"
);
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");
Если ваше расширение публикует события Eventarc, вам также нужно настроить необходимые роли и API для публикации событий. Ранее это делалось с помощью расширений, и вам не нужно было вносить изменения в extensions.yaml. Вы можете сделать это условно в своем коде, чтобы комплект запрашивал эти разрешения только при использовании пользовательского канала Eventarc.
if (!!process.env.EVENTARC_CHANNEL) {
requiresRole("roles/eventarc.publisher");
requiresAPI(
"eventarcpublishing.googleapis.com",
"Publishes the extension's custom events to its Eventarc channel."
);
}
7. Как преобразовать хуки жизненного цикла
Если ваше расширение вызывает getExtensions().runtime() (например, setProcessingState или setFatalError), удалите эти вызовы, поскольку они вызывают ошибку при вызове из нормально развернутой функции второго поколения. Теперь статус жизненного цикла определяется afterFirstDeploy и afterRedeploy, где отслеживание этого статуса не используется.
Firebase Extensions может запускать настройку, когда пользователь устанавливает, обновляет или перенастраивает расширение. В пакете npm объявите в коде эквивалентные действия жизненного цикла.
Для однократной настройки:
import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";
export const runInitialSetup = onTaskDispatched(async (request) => {
await initializeResources(request.data);
});
afterFirstDeploy({
task: {
function: "runInitialSetup",
body: {}
}
});
Для обновлений конфигурации или кода:
import { afterRedeploy } from "firebase-functions/lifecycle";
afterRedeploy({
task: {
function: "runInitialSetup",
body: { reconcile: true }
}
});
Сделайте действия жизненного цикла идемпотентными. Если отправка или выполнение не удались, пользователям может потребоваться запустить их вручную:
firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME
Пример. Поток Cloud Firestore в BigQuery
До. lifecycleEvents в extension.yaml, обусловленный средой выполнения расширений:
lifecycleEvents:
onInstall:
function: initBigQuerySync
processingMessage: Configuring BigQuery Sync.
onUpdate:
function: setupBigQuerySync
processingMessage: Configuring BigQuery Sync
onConfigure:
function: setupBigQuerySync
processingMessage: Configuring BigQuery Sync
После. Объявлено в коде; задача предоставляет BigQuery при первом развертывании:
import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";
afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });
Инициализация идемпотентна, поэтому повторный запуск согласовывает набор данных, таблицу и представления.
Пользователи могут запустить его вручную с помощью firebase functions:lifecycle:run afterFirstDeploy
CODEBASE_NAME.
8. Документация для пользователей
Напишите README пакета, в котором объясняется как минимум следующее:
- Значения
.env, необходимые для пакета. - Секреты, необходимые для пакета, и способы переноса существующих значений секретов.
- Роли IAM, которые пакет объявляет с помощью
requiresRole(...). - API Google, которые активирует или требует пакет.
- Обработчики жизненного цикла, объявленные пакетом, и способы их повторного запуска вручную.
- Примечания к платежам.
- Что изменилось по сравнению с исходным расширением.
- Как пакет получает идентификатор экземпляра (
FIREBASE_KIT_INSTANCE_ID, заданный интерфейсом командной строки) и что все функции экземпляра развертываются с префиксомkit-<instanceId>-.
Пример. Поток Cloud Firestore в BigQuery
Пакет README содержит таблицу с конкретными изменениями:
| Проблема | Как расширение | Ваше устройство: @firebase-function-kits/firestore-bigquery-export |
|---|---|---|
| Конфигурация | Параметры расширения | Cloud Functions параметров через .env |
| IAM | Предоставлено расширениями | requiresRole(...), применяется при развертывании |
| Инициализация | Задача жизненного цикла, выполняемая расширениями | afterFirstDeploy из afterRedeploy задачи |
| Названия функций | ext-<instanceId>-fsexportbigquery |
fsexportbigquery (префикс необязателен) |
| Идентификатор экземпляра | EXT_INSTANCE_ID внедрено расширениями |
FIREBASE_KIT_INSTANCE_ID, задано CLI из firebase.json |
9. Тестирование функции второго поколения
Теперь у вас должна быть функция второго поколения, которая при развертывании ведет себя идентично новой установке вашего расширения. Следующий шаг – проверить и исправить все проблемы, случайно возникшие в процессе.
Вызывать setGlobalOptions для настройки глобальных параметров, таких как регион по умолчанию или ЦП, можно только при развертывании набора в качестве отдельной функции второго поколения. Когда ваш набор установлен как пакет npm, пользователи вызывают setGlobalOptions в своем коде-оболочке, чтобы настроить эти параметры. Если это произойдет дважды, они получат предупреждения.
Вы можете защитить этот вызов, проверив переменную среды FIREBASE_KIT_INSTANCE_ID:
import { setGlobalOptions } from "firebase-functions";
if (!process.env.FIREBASE_KIT_INSTANCE_ID) {
setGlobalOptions({
region: "us-east1",
maxInstances: 10,
});
}
Убедитесь, что вы используете firebase-tools >= 15.32.0, и разверните преобразованную функцию второго поколения в тестовом проекте с соответствующими ресурсами, чтобы проверить ее поведение. Если у вас уже есть тестовый проект, созданный для проверки расширения, выполните следующую команду:
firebase deploy --only functions
Заполните форму, указав значения параметров так же, как вы бы сделали это в консоли Firebase для расширения.
Пример. Поток Cloud Firestore в BigQuery
Мы проверяем синхронизацию между 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
Отличия от тестирования расширения:
- Триггер развертывается как
fsexportbigquery(без префикса, как обычная функция второго поколения, а не набор), а неext-<instanceId>-fsexportbigquery. Найдите это название на панели управления и в журналах Cloud Functions. - Теперь ваш код выполняется в Firebase Local Emulator Suite как обычные функции.
Вы можете задать значения параметров для использования в эмуляторе с помощью
.env.local. Вы также можете выполнить модульное тестирование кода с помощью SDKfirebase-functions-test, как описано в статье Модульное тестирование Cloud Functions. - Инициализация больше не управляется средой выполнения расширений. Если после развертывания таблица changelog отсутствует, повторно запустите задачу настройки вручную:
firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME. Задача идемпотентна, поэтому при повторном запуске она согласовывает набор данных, таблицу и представления. - Значения параметров берутся из файла
.env, а не из формы установки, поэтому повторные запускиfirebase deployпосле завершения.envне являются интерактивными.
10. Опубликуйте свой набор функций в npm
После того как вы проверите преобразование расширения в функцию второго поколения, вы можете опубликовать релиз-кандидат в npm для сквозного тестирования, используя одно из следующих руководств:
- Создание и публикация общедоступных пакетов без области действия
- Создание и публикация общедоступных пакетов с ограниченной областью действия
Когда набор будет опубликован в npm, его можно будет установить с помощью команды firebase functions:kits:install. Он будет указан как официальная замена вашего расширения.
Мы настоятельно рекомендуем сначала опубликовать релиз-кандидат. Наборы устанавливаются по названию и версии пакета, поэтому предварительный выпуск позволяет протестировать реальный процесс установки в реестре, не показывая незавершенный пакет пользователям, которые устанавливают его с тегом latest по умолчанию.
Перед публикацией:
- Выберите название пакета. Можно использовать как имена с областью действия, так и без нее (см. руководства выше). Обратите внимание, что пакеты с ограниченной областью действия по умолчанию являются частными, поэтому передайте
--access public. - Построй и проверь, какие корабли.
mainиtypesуказывают на скомпилированные выходные данные (lib/в нашем примере), поэтому этот каталог должен быть включен в опубликованный tar-файл. Используйте белый список.npmignoreилиfilesи проверьте результат с помощьюnpm pack --dry-run. СкриптprepublishOnly, который запускает сборку, предотвращает публикацию устаревших выходных данных.
package.json дополнений, которые делают публикацию безопасной по умолчанию:
{
"files": ["lib", "README.md", "CHANGELOG.md"],
"publishConfig": { "access": "public", "tag": "next" },
"scripts": {
"build": "tsc -b",
"prepublishOnly": "npm run build && npm test"
}
}
Поле "publishConfig": { "tag": "next" } гарантирует, что обычный npm
publish никогда не перезапишет latest.
Создание релиз-кандидата
Например, чтобы увеличить версию локально с 0.0.2-rc.3 до 0.0.2-rc.4 (это фиксирует и помечает тегами в Git, если package.json находится в корне репозитория):
npm version prerelease --preid rc
Чтобы опубликовать релиз-кандидат и зарегистрировать @your-org/your-kit@0.0.2-rc.4 в npm под тегом next:
npm publish
На сайте npm новая версия может появиться через несколько минут. npm view считывает данные непосредственно из реестра:
npm view @your-org/your-kit versions dist-tags
После выполнения шага 11 и шага 12 этого руководства вы можете продвинуть пакет до стабильной версии.
npm version 0.0.2
npm publish --tag latest
npm dist-tag add @your-org/your-kit@0.0.2 next
Примечание о файле npm-shrinkwrap.json. Мы настоятельно рекомендуем включить файл npm-shrinkwrap.json в пакет. Если вы этого не сделаете, при установке CLI будет показывать пользователям предупреждение. Это гарантирует, что пользователи будут использовать именно те зависимости, которые вы протестировали, и помогает защититься от атак на цепочку поставок. Однако shrinkwrap-файл применяется в проектах пользователей дословно, в том числе во время сборки Cloud Functions (npm ci), когда записи, предназначенные только для разработки, могут завершиться сбоем с ошибкой EBADPLATFORM. Возможно, вам потребуется удалить записи "dev": true и devDependencies из опубликованной копии shrinkwrap.
Пример. Поток Cloud Firestore в BigQuery
package.json набора на момент четвертого релиз-кандидата:
{
"name": "@firebase-function-kits/firestore-bigquery-export",
"version": "0.0.2-rc.4",
"repository": {
"type": "git",
"url": "https://github.com/firebase/extensions.git",
"directory": "kits/firestore-bigquery-export"
},
"main": "lib/index.js",
"types": "lib/index.d.ts",
"engines": { "node": "22" },
"scripts": { "build": "tsc -b" }
}
Обратите внимание, что в этом случае набор находится в монорепозитории, поэтому важно включить repository.directory, чтобы ссылка на реестр npm указывала на правильную папку. В файле CHANGELOG.md содержатся примечания к ожидающему выпуску.
11. Тестирование в качестве набора функций
После публикации набора рекомендуем протестировать его с помощью npm.
Убедитесь, что вы используете firebase-tools версии >= 15.32.0, и установите набор:
firebase functions:kits:install --package <your-package-name>@<your-prerelease-version>
При этом ваш пакет будет скачан из npm и настроен в новом каталоге с исходными файлами для вашего набора. Затем вам будет предложено настроить первый экземпляр, как при установке расширений. После установки и настройки пакета на локальном компьютере выполните развертывание, чтобы создать ресурсы в проекте Google Cloud:
firebase deploy --only functions:<your-kit-instance-id>
После установки CLI Firebase выведет похожую команду развертывания с точным идентификатором экземпляра, который вы выбрали во время установки.
Повторно проверьте комплект, следуя инструкциям в шаге 9. Протестируйте функцию второго поколения. Теперь, когда вы выполняете развертывание с помощью наборов, ваши функции имеют префикс и называются kit-<instance-id>-<method-name>. Это позволяет наборам иметь несколько экземпляров, развертывая одну и ту же функцию несколько раз в проекте, каждый из которых имеет уникальное имя.
12. Замена тестового переноса
Вы можете настроить рабочий экземпляр расширения, а затем использовать руководство по переносу данных (с помощью firebase ext:migrate --package или команд CLI для наборов функций), чтобы завершить тестирование набора функций в качестве замены при переносе.
13. Уведомление пользователей и Google об официальной замене расширения
Когда замена будет готова и доступна в виде пакета npm, на который пользователи должны перейти, сообщите об этом пользователям и Google. Обновите файл README.md в хранилище GitHub, где размещено ваше расширение, добавив следующую информацию:
<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="<your-extesion-id>" package="<your-npm-package-name>" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `<your-extension>` is deprecated. Migrate to the [<your-npm-package-name>](<link-to-your-npm-package>) package.
Google сканирует файлы README известных расширений на наличие комментариев, таких как <!--
FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export"
package="@firebase-function-kits/firestore-bigquery-export" -->, и использует их для заполнения официального реестра замен, хранящегося в репозитории firebase-tools как replacements.json.
Вы также можете проверить replacements.json, чтобы узнать, какие README.md будут сканироваться для вашего расширения. Официальный список замен обновляется еженедельно.
Пример. Поток Cloud Firestore в BigQuery
Расширение firestore-bigquery-export
README.md
содержит:
<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `firebase/firestore-bigquery-export` is deprecated. Please migrate to the [`@firebase-function-kits/firestore-bigquery-export`](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export) package.