После перехода с Firebase Extensions на Function Kit вы будете управлять экземплярами своих наборов функций как стандартными Cloud Functions второго поколения в вашем проекте Firebase . В этом руководстве описано, как устанавливать новые наборы функций непосредственно из npm без миграции существующего расширения, обновлять параметры набора и глобальные опции, обновлять версии пакетов npm по мере выпуска обновлений издателями и откатывать миграцию при необходимости.
Использование набора функций из npm-пакета без миграции.
Если вы не переходите с существующего расширения, использование набора функций состоит из двух частей:
Установка комплекта
Установить набор функций можно с помощью следующей команды командной строки:
firebase functions:kits:install --package <npm-package-name>
Пример решения задачи:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i function-kits/firestore-bigquery-export/source/package.json is unchanged
i function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i functions: Building TypeScript source...
✔ Wrote configuration info to firebase.json
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1
✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project
✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing
# Omitting many more parameters for brevity
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
i functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠ functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.
Изменение глобальных параметров по умолчанию
Чтобы настроить глобальные параметры для вашего экземпляра комплекта, измените файл index.ts , расположенный по адресу function-kits/<your-kit-id>/source/src/index.ts .
Если вы хотите, чтобы значения по умолчанию были общими для всех экземпляров набора, задайте их непосредственно в index.ts . В противном случае создайте параметры, которые будут устанавливаться для каждого экземпляра отдельно, следуя примерам и инструкциям, описанным в index.ts .
Развертывание комплекта
Для развертывания комплекта функций выполните следующую команду:
firebase deploy --only functions:<kit-instance-id>
Пример решения задачи:
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!
Установка и развертывание комплекта выполняет следующие действия:
- Создает
function-kits/firestore-bigquery-export/source, которая содержит исходный код комплекта, включая базовый файлindex.ts, который импортирует и экспортирует пакет комплекта, а также устанавливает параметр, позволяющий выбрать различное местоположение для каждого экземпляра комплекта. - Создает
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>и заполняет его данными конфигурации, введенными для функции. Если в будущих обновлениях будут добавлены новые параметры, запрос на ввод будет отправлен при следующем развертывании. - Создает необходимые ресурсы Google Cloud для запуска этого комплекта, включая учетную запись службы с определенными ролями IAM, функциями, триггерами Eventarc и очередями Cloud Tasks.
Если в одном проекте у вас несколько экземпляров комплекта, вы можете повторить эти команды для создания и развертывания новых экземпляров того же комплекта. Вы также можете развернуть один экземпляр комплекта в нескольких проектах Firebase с различными конфигурациями (например, в тестовом проекте и в производственном проекте). Чтобы узнать больше о расширенных настройках, см. раздел «Расширенные миграции» .
Демонтаж комплекта
Чтобы удалить набор инструментов и все его экземпляры, выполните следующую команду:
firebase functions:kits:uninstall --kit <kit-id>
Это удалит все экземпляры и их конфигурации, а также уберет исходный код комплекта с диска.
Чтобы удалить только один экземпляр набора инструментов, выполните следующую команду:
firebase functions:kits:uninstall --instance <kit-instance-id>
Если у вас установлен только один экземпляр комплекта, это приведет к удалению всего комплекта.
Обновление конфигурации комплекта
Во время установки или первого развертывания вам будет предложено настроить все параметры вашего комплекта (если вы не перенесли конфигурацию из расширения). Эти параметры хранятся в файле .env в каталоге конфигурации вашего экземпляра комплекта. Например, если у вас есть экземпляр комплекта с именем firestore-bigquery-export в проекте my-project , файл .env находится по адресу function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project .
Это выглядит следующим образом:
DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1
Если вы знаете значение конфигурации, которое хотите изменить, вы можете отредактировать его непосредственно в файле .env . Если вы предпочитаете использовать интерактивную командную строку, которая запускается во время установки и развертывания, удалите параметры, которые хотите изменить, из файла .env и повторно разверните экземпляр комплекта. Во время развертывания вам будет предложено ввести эти параметры.
Например, если вы удалите строку COLLECTION_PATH=posts и выполните развертывание, вам будет предложено ввести её во время развертывания:
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:
Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)
Поддержание и обновление комплекта функциональных возможностей.
Издатели могут со временем обновлять свои npm-пакеты для исправления ошибок, добавления новых функций, обновления зависимостей или устранения уязвимостей безопасности. Мы рекомендуем следить за этими обновлениями и устанавливать их, особенно те, которые устраняют уязвимости безопасности.
Команда functions:kits:install создает кодовую базу, которая устанавливает комплект как npm-пакет и экспортирует все его функции для каждого экземпляра вашего комплекта. Чтобы обновить комплект, обновите версию пакета, а затем повторно разверните каждый экземпляр вашего комплекта, чтобы применить изменения.
Определение наличия обновлений в комплекте.
Перейдите в source каталог вашего набора функций по адресу function-kits/<your-kit-id>/source . Из этого source выполните следующую команду, чтобы получить отчет обо всех устаревших пакетах npm, включая ваш набор функций и SDK Cloud Functions :
npm outdated
Если вы уже используете инструмент для выявления зависимостей, требующих обновления, например Dependabot для GitHub, мы рекомендуем интегрировать ваш каталог kit в этот рабочий процесс.
Обновление комплекта
Чтобы обновить комплект и его зависимости до последней версии, не нарушающей обратную совместимость (за исключением обновлений основных версий, которые могут содержать критические изменения), выполните следующую команду:
npm update --save
Если вы хотите обновить только пакет с функциональными компонентами и никакие другие пакеты, передайте имя пакета команде ` npm update :
npm update <package-name> --save
Чтобы обновить пакет до последней основной версии (что может привести к изменениям, нарушающим обратную совместимость), выполните следующую команду:
npm update --save <npm-package-name>@latest
Ознакомьтесь с документацией к пакету и примечаниями к выпуску, чтобы узнать, что изменилось и нужно ли предпринять какие-либо дополнительные шаги до или после развертывания, чтобы предотвратить изменения, нарушающие обратную совместимость.
Развертывание обновленных экземпляров
Команда npm update обновляет только локальный исходный код. Чтобы обновить работающие функции в облаке, выполните их повторное развертывание. Вы можете повторно развернуть все функции в своем проекте, включая все наборы функций, выполнив команду:
firebase deploy --only functions
Отмена миграции
Чтобы отменить миграцию, сначала переустановите расширение. Вы можете использовать файл .env комплекта, чтобы найти значения конфигурации, необходимые во время установки.
После развертывания расширения удалите экземпляр комплекта (если это последний оставшийся экземпляр, то будет удален весь комплект):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Сохранение конфигураций расширений для будущей миграции.
После 31 марта 2027 года вы не сможете получить доступ к существующей конфигурации расширения. Если вы не можете выполнить миграцию до 31 марта 2027 года, мы настоятельно рекомендуем сохранить ваше расширение на случай, если вы решите выполнить миграцию после этой даты.
Получите список идентификаторов экземпляров ваших расширений:
Для получения списка всех экземпляров расширений в вашем проекте Firebase можно использовать команду CLI
ext:list:firebase ext:list --project <project-id>Пример решения задачи:
firebase ext:list --project my-project» firebaselocal ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in ajp-testing: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3 │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export │ ACTIVE │ 0.3.2 │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshootingКоманда
ext:listтакже поддерживает вывод в формате JSON, и если у вас установлена утилита jq , вы можете использовать её для получения списка всех идентификаторов экземпляров проекта:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Пример решения задачи:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Выход:
firestore-bigquery-export-zbrp firestore-bigquery-exportЭкспортируйте конфигурацию для каждого экземпляра:
Для каждого экземпляра вы можете сохранить его конфигурацию на диске, выполнив следующую команду экспорта:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Пример решения задачи:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportВыход:
i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i functions: Saving exported extensions config as a Function Kits .env file i functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control. i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testingНа диске вы найдете экспорт этого экземпляра расширения по адресу, например,
<instance-id>/.env.<project-id>. В этом примере он находится по адресуfirestore-bigquery-export/.env.my-project.Этот процесс можно повторить один раз для каждого экземпляра, и он создаст набор файлов
.envсо всеми конфигурациями экземпляра вашего расширения, которые можно будет повторно использовать позже в рамках миграции.Переместите экспортированные файлы
.envв более подходящее место:Экспортированные файлы
.envиз ваших расширений были помещены непосредственно в ваш проект Firebase, но они не нужны в повседневной работе, если вы не перешли на функциональные наборы. Вы можете переместить их из своего проекта в любое другое подходящее место хранения, пока они вам не понадобятся в будущем, или удалить их.