После перехода с Firebase Extensions на набор функций вы управляете экземплярами набора как стандартными Cloud Functions второго поколения в проекте Firebase. В этом руководстве рассказывается, как устанавливать новые наборы функций напрямую из npm без переноса существующего расширения, обновлять параметры наборов и глобальные настройки, обновлять версии пакетов npm по мере выпуска обновлений издателями и при необходимости откатывать перенос.
Как использовать набор функций из пакета npm без переноса
Если вы не переходите с расширения, использование набора функций состоит из двух частей:
Установка комплекта
Вы можете установить набор функций, используя следующую команду CLI:
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.my-project
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, рекомендуем интегрировать каталог наборов в этот рабочий процесс.
Как обновить набор
Чтобы обновить набор и его зависимости до последней версии без критических изменений (исключая основные версии, которые могут содержать критические изменения), выполните следующую команду:
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» firebase ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in my-project: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ 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, но они не нужны для повседневной работы, если вы не перешли на наборы функций. Вы можете переместить их из своего проекта в любое другое подходящее место хранения, пока они не понадобятся вам в будущем, или удалить их.