Как настроить среду (первое поколение)

Часто для функций требуется дополнительная настройка, например ключи API сторонних сервисов или настраиваемые параметры. В SDK Firebase для Cloud Functions есть встроенная конфигурация среды, которая упрощает хранение и получение таких данных для проекта.

Вы можете выбрать один из следующих вариантов:

  • Параметризованная конфигурация (рекомендуется для большинства сценариев). Это обеспечивает строго типизированную конфигурацию среды с параметрами, которые проверяются во время развертывания, что предотвращает ошибки и упрощает отладку.
  • Конфигурация переменных среды на основе файлов. При таком подходе вы вручную создаете файл dotenv для загрузки переменных среды.

В большинстве случаев рекомендуется использовать параметризованную конфигурацию. Этот подход делает значения конфигурации доступными как во время выполнения, так и во время развертывания, а развертывание блокируется, если все параметры не имеют допустимого значения. И наоборот, конфигурация с переменными среды недоступна во время развертывания.

Параметризованная конфигурация

Cloud Functions for Firebase предоставляет интерфейс для декларативного определения параметров конфигурации в базе кода. Значение этих параметров доступно как во время развертывания функции, при настройке параметров развертывания и среды выполнения, так и во время выполнения. Это означает, что CLI заблокирует развёртывание, если не все параметры имеют допустимое значение.

Чтобы определить параметры в коде, используйте следующую модель:

const functions = require('firebase-functions/v1');
const { defineInt, defineString } = require('firebase-functions/params');

// Define some parameters
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
const welcomeMessage = defineString('WELCOME_MESSAGE');

// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
  (req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

При развертывании функции с параметризованными переменными конфигурации интерфейс командной строки Firebase сначала пытается загрузить их значения из локальных файлов .env. Если в этих файлах нет нужных значений и не задана переменная default, CLI запросит значения во время развертывания, а затем автоматически сохранит их в файле .env с названием .env.<project_ID> в каталоге functions/:

$ firebase deploy
i  functions: preparing codebase default for deployment
? Enter a string value for ENVIRONMENT: prod
i  functions: Writing new parameter values to disk: .env.projectId
…
$ firebase deploy
i  functions: Loaded environment variables from .env.projectId

В зависимости от вашего рабочего процесса разработки может быть полезно добавить сгенерированный файл .env.<project_ID> в систему управления версиями.

Как использовать параметры в глобальной области действия

Во время развертывания код функций загружается и проверяется до того, как параметры получат фактические значения. Это означает, что получение значений параметров в глобальной области видимости приводит к сбою развертывания. Если вы хотите использовать параметр для инициализации глобального значения, используйте обратный вызов инициализации onInit(). Этот обратный вызов выполняется до запуска любых функций в рабочей среде, но не вызывается во время развертывания, поэтому это безопасное место для доступа к значению параметра.

  const { GoogleGenerativeAI } = require('@google/generative-ai');
  const { defineSecret } = require('firebase-functions/params');
  const { onInit } = require('firebase-functions/v1');

  const apiKey = defineSecret('GOOGLE_API_KEY');

  let genAI;
  onInit(() => {
    genAI = new GoogleGenerativeAI(apiKey.value());
  })

Настройка поведения CLI

Параметры можно настроить с помощью объекта Options, который определяет, как CLI будет запрашивать значения. В следующем примере задаются параметры для проверки формата номера телефона, предоставляется простой вариант выбора и автоматически заполняется вариант выбора из проекта Firebase:

const { defineString } = require('firebase-functions/params');

const welcomeMessage = defineString('WELCOME_MESSAGE', {default: 'Hello World',
description: 'The greeting that is returned to the caller of this function'});

const onlyPhoneNumbers = defineString('PHONE_NUMBER', {input: {text:
{validationRegex: /\d{3}-\d{3}-\d{4}/, validationErrorMessage: "Please enter
a phone number in the format XXX-YYY-ZZZZ"}}});

const selectedOption = defineString('PARITY', {input: {select: {options:
[{value: "odd"}, {value: "even"}]}}})

const storageBucket = defineString('BUCKET', {input: {resource: {type:
"storage.googleapis.com/Bucket"}}, description: "This will automatically
populate the selector field with the deploying Cloud Project’s
storage buckets"})

Типы параметров

Параметризованная конфигурация обеспечивает строгую типизацию значений параметров, а также поддерживает секреты из Cloud Secret Manager. Поддерживаются следующие типы:

  • Секрет
  • Строка
  • Логическое значение
  • Целое число
  • Число с плавающей запятой

Информацию о функциях для определения параметров можно найти в справочнике по пространству имен params.

Значения параметров и выражения

Firebase оценивает ваши параметры как во время развертывания, так и во время выполнения вашей функции. Из-за этого при сравнении значений параметров и их использовании для настройки параметров среды выполнения функций нужно соблюдать осторожность.

Чтобы передать параметр в функцию в качестве параметра среды выполнения, передайте его напрямую:

const functions = require('firebase-functions/v1');
const { defineInt} = require('firebase-functions/params');
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');

export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
  (req, res) => {
    //…

Кроме того, если вам нужно сравнить значение с параметром, чтобы выбрать вариант, используйте встроенные компараторы, а не проверку значения:

const functions = require('firebase-functions/v1');
const { defineBool } = require('firebase-functions/params');
const environment = params.defineString(‘ENVIRONMENT’, {default: ‘dev’});

// use built-in comparators
const minInstancesConfig =environment.equals('PRODUCTION').thenElse(10, 1);
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
  (req, res) => {
    //…

К параметрам и выражениям параметров, которые используются только во время выполнения, можно обращаться с помощью функции value:

const functions = require('firebase-functions/v1');
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE');

// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.https.onRequest(
 (req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

Встроенные параметры

В SDK Cloud Functions есть три предопределенных параметра, доступных в подпакете firebase-functions/params:

  • projectID – облачный проект, в котором выполняется функция.
  • databaseURL – URL экземпляра Realtime Database, связанного с функцией (если он включен в проекте Firebase).
  • storageBucket – сегмент Cloud Storage, связанный с функцией (если он включен в проекте Firebase).

Они во всех отношениях работают как пользовательские строковые параметры, за исключением того, что их значения всегда известны интерфейсу командной строки Firebase, поэтому они никогда не запрашиваются при развертывании и не сохраняются в файлах .env.

Параметры секрета

Параметры типа Secret, определенные с помощью defineSecret(), представляют собой строковые параметры, значение которых хранится в Cloud Secret Manager. Вместо того чтобы проверять локальный файл .env и записывать в него новое значение, если оно отсутствует, секретные параметры проверяют наличие в Cloud Secret Manager и в интерактивном режиме запрашивают значение нового секрета во время развертывания.

Определенные таким образом секретные параметры должны быть привязаны к отдельным функциям, которые должны иметь к ним доступ:

const functions = require('firebase-functions/v1');
const { defineSecret } = require('firebase-functions/params');
const discordApiKey = defineSecret('DISCORD_API_KEY');

export const postToDiscord = functions.runWith({ secrets: [discordApiKey] }).https.onRequest(
  (req, res) => {
    const apiKey = discordApiKey.value();
    //…

Переменные среды

Cloud Functions for Firebase поддерживает формат файлов dotenv для загрузки переменных среды, указанных в файле .env, в среду выполнения приложения. После развертывания переменные среды можно прочитать через интерфейс process.env.

Чтобы настроить среду таким образом, создайте в проекте файл .env, добавьте нужные переменные и разверните его:

  1. Создайте файл .env в каталоге functions/:

    # Directory layout:
    #   my-project/
    #     firebase.json
    #     functions/
    #       .env
    #       package.json
    #       index.js
    
  2. Откройте файл .env для редактирования и добавьте нужные ключи. Пример:

    PLANET=Earth
    AUDIENCE=Humans
    
  3. Разверните функции и убедитесь, что переменные среды загружены:

    firebase deploy --only functions
    # ...
    # i functions: Loaded environment variables from .env.
    # ...
    

После развертывания пользовательских переменных среды код функции может получить к ним доступ с помощью синтаксиса process.env:

// Responds with "Hello Earth and Humans"
exports.hello = functions.https.onRequest((request, response) => {
  response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});

Развертывание нескольких наборов переменных среды

Если вам нужен альтернативный набор переменных среды для проектов Firebase (например, для промежуточной и рабочей сред), создайте файл .env.<project or alias> и запишите в него переменные среды, относящиеся к проекту. Переменные среды из файлов .env и .env (если они есть) будут включены во все развернутые функции.

Например, проект может включать следующие три файла, содержащие немного разные значения для разработки и производства:

.env .env.dev .env.prod
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Prod Humans

В зависимости от значений в этих отдельных файлах набор переменных среды, развернутых с вашими функциями, будет различаться в зависимости от вашего целевого проекта:

$ firebase use dev
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.dev.
# Deploys functions with following user-defined environment variables:
#   PLANET=Earth
#   AUDIENCE=Dev Humans

$ firebase use prod
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.prod.
# Deploys functions with following user-defined environment variables:
#   PLANET=Earth
#   AUDIENCE=Prod Humans

Зарезервированные переменные среды

Некоторые ключи переменных среды зарезервированы для внутреннего использования. Не используйте в файлах .env следующие ключи:

  • Все ключи, начинающиеся с X_GOOGLE_
  • Все ключи, начинающиеся с EXT_
  • Все ключи, начинающиеся с FIREBASE_
  • Любая клавиша из следующего списка:
  • CLOUD_RUNTIME_CONFIG
  • ENTRY_POINT
  • GCP_PROJECT
  • GCLOUD_PROJECT
  • GOOGLE_CLOUD_PROJECT
  • FUNCTION_TRIGGER_TYPE
  • FUNCTION_NAME
  • FUNCTION_MEMORY_MB
  • FUNCTION_TIMEOUT_SEC
  • FUNCTION_IDENTITY
  • FUNCTION_REGION
  • FUNCTION_TARGET
  • FUNCTION_SIGNATURE_TYPE
  • K_SERVICE
  • K_REVISION
  • ПОРТ
  • K_CONFIGURATION

Хранение конфиденциальной информации о конфигурации и доступ к ней.

Переменные среды, хранящиеся в файлах .env, можно использовать для настройки функций, но не следует рассматривать их как безопасный способ хранения конфиденциальной информации, такой как учетные данные базы данных или ключи API. Это особенно важно, если вы добавляете файлы .env в систему управления версиями.

Чтобы вы могли хранить конфиденциальную информацию о конфигурации, Cloud Functions for Firebase интегрируется с Google Cloud Secret Manager. Этот зашифрованный сервис надежно хранит значения конфигурации, обеспечивая при этом легкий доступ к ним из ваших функций, когда это необходимо.

Как создать и использовать секрет

Чтобы создать секрет, используйте CLI Firebase.

Чтобы создать и использовать секрет:

  1. В корневом каталоге локального проекта выполните следующую команду:

    firebase functions:secrets:set SECRET_NAME

  2. Введите значение для параметра SECRET_NAME.

    CLI выведет сообщение об успешном выполнении и предупредит, что для вступления изменений в силу необходимо развернуть функции.

  3. Перед развертыванием убедитесь, что код функции позволяет ей получить доступ к секрету с помощью параметра runWith:

    exports.processPayment = functions
      // Make the secret available to this function
      .runWith({ secrets: ["SECRET_NAME"] })
      .onCall((data, context) => {
        const myBillingService = initializeBillingService(
          // reference the secret value
          process.env.SECRET_NAME
        );
        // Process the payment
      });
  4. Развертывание Cloud Functions:

    firebase deploy --only functions

Теперь вы сможете получить к нему доступ, как и к любой другой переменной среды. И наоборот, если другая функция, которая не указывает секрет в runWith, пытается получить доступ к секрету, она получает неопределенное значение:

  exports.anotherEndpoint = functions.https.onRequest((request, response) => {
    response.send(`The secret API key is ${process.env.SECRET_NAME}`);
    // responds with "The secret API key is undefined" because the `runWith` parameter is missing
  });

После развертывания функции у нее будет доступ к секретному значению. Доступ к секрету в качестве переменной среды получат только те функции, в параметре runWith которых он указан. Это позволяет гарантировать, что секретные значения будут доступны только там, где они необходимы, и снижает риск случайной утечки секрета.

Управление секретами

Для управления секретами используйте CLI Firebase. При таком способе управления секретами помните, что некоторые изменения CLI требуют изменения и/или повторного развертывания связанных функций. Таким образом, перестанут работать следующие функции:

  • Каждый раз, когда вы устанавливаете новое значение для секрета, вы должны повторно развернуть все функции, которые ссылаются на этот секрет, чтобы они получили последнее значение.
  • Если вы удалите секрет, убедитесь, что ни одна из развернутых функций не ссылается на него. Функции, использующие удаленное секретное значение, будут завершаться сбоем без уведомления.

Ниже приведено краткое описание команд CLI Firebase для Secret Manager.

# Change the value of an existing secret
firebase functions:secrets:set SECRET_NAME

# View the value of a secret
functions:secrets:access SECRET_NAME

# Destroy a secret
functions:secrets:destroy SECRET_NAME

# View all secret versions and their state
functions:secrets:get SECRET_NAME

# Automatically clean up all secrets that aren't referenced by any of your functions
functions:secrets:prune

Для команд access и destroy можно указать необязательный параметр version, чтобы управлять определенной версией. Пример:

functions:secrets:access SECRET_NAME[@VERSION]

Чтобы получить дополнительную информацию об этих операциях, передайте -h с командой для просмотра справки по CLI.

Как оплачиваются секреты

Secret Manager позволяет бесплатно использовать 6 активных версий секретов. Это значит, что в проекте Firebase можно бесплатно хранить до шести секретов в месяц.

По умолчанию CLI Firebase пытается автоматически уничтожать неиспользуемые версии секретов, когда это уместно, например когда вы развертываете функции с новой версией секрета. Вы также можете удалять неиспользуемые секреты с помощью functions:secrets:destroy и functions:secrets:prune.

Secret Manager позволяет выполнять 10 000 бесплатных операций доступа к секрету в месяц. Экземпляры функций считывают только секреты, указанные в параметре secrets, при каждом холодном запуске. Если у вас много экземпляров функций, считывающих много секретов, ваш проект может превысить это ограничение, и в этом случае с вас будет взиматься плата в размере 0,03 доллара США за 10 000 операций доступа.

Подробнее о ценах на Secret Manager…

Поддержка эмуляторов

Конфигурация среды с dotenv предназначена для взаимодействия с локальным эмулятором Cloud Functions.

При использовании локального эмулятора Cloud Functions вы можете переопределить переменные среды для своего проекта, настроив файл .env.local. Содержимое файла .env.local имеет приоритет над содержимым файла .env и файла .env, относящегося к проекту.

Например, проект может включать три файла с немного разными значениями для разработки и локального тестирования:

.env .env.dev .env.local

PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

При запуске в локальном контексте эмулятор загружает переменные среды, как показано ниже:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Секреты и учетные данные в эмуляторе Cloud Functions

Эмулятор Cloud Functions поддерживает использование секретов для хранения конфиденциальной информации о конфигурации и доступа к ней. По умолчанию эмулятор пытается получить доступ к вашим рабочим секретам, используя учетные данные приложения по умолчанию. В некоторых ситуациях, например в средах непрерывной интеграции, эмулятор может не получить доступ к значениям секретов из-за ограничений разрешений.

Как и в случае с поддержкой переменных среды в эмуляторе Cloud Functions, вы можете переопределить значения секретов, настроив файл .secret.local. Это упрощает локальное тестирование функций, особенно если у вас нет доступа к секретному значению.

Перенос из конфигурации среды выполнения

functions.config API устарел и будет отключен в марте 2027 г. После этой даты развертывания с functions.config будут завершаться ошибкой.

Чтобы избежать сбоев при развертывании, перенесите конфигурацию в Cloud Secret Manager с помощью CLI Firebase. Это наиболее эффективный и безопасный способ переноса конфигурации.

  1. Как экспортировать конфигурацию с помощью интерфейса командной строки Firebase

    Используйте команду config export, чтобы экспортировать существующую конфигурацию среды в новый секрет в Cloud Secret Manager:

    $ firebase functions:config:export
    i  This command retrieves your Runtime Config values (accessed via functions.config())
       and exports them as a Secret Manager secret.
    
    i  Fetching your existing functions.config() from your project...  ✔
       Fetched your existing functions.config().
    
    i  Configuration to be exported:
    ⚠  This may contain sensitive data. Do not share this output.
    
    {
       ...
    }
    
    ✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG
    
    ✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```
    
  2. Обновите код функции, чтобы связать секреты

    Чтобы использовать конфигурацию, хранящуюся в новом секрете в Cloud Secret Manager, используйте API defineJsonSecret в источнике функции. Также убедитесь, что секреты привязаны ко всем функциям, которым они нужны.

    До

    const functions = require("firebase-functions/v1");
    
    exports.myFunction = functions.https.onRequest((req, res) => {
      const apiKey = functions.config().someapi.key;
      // ...
    });
    

    После

    const { onRequest } = require("firebase-functions/v2/https");
    const { defineJsonSecret } = require("firebase-functions/params");
    
    const config = defineJsonSecret("RUNTIME_CONFIG");
    
    exports.myFunction = onRequest(
      // Bind secret to your function
      { secrets: [config] },
      (req, res) => {
        // Access secret values via .value()
        const apiKey = config.value().someapi.key;
        // ...
    });
    
  3. Развертывание функций

    Разверните обновленные функции, чтобы применить изменения и привязать разрешения для секретов.

    firebase deploy --only functions:<your-function-name>
    

Автоматически заполняемые переменные среды

Существуют переменные среды, которые автоматически заполняются в среде выполнения функций и в локально эмулируемых функциях. К ним относятся переменные, заполняемые Google Cloud, а также переменная среды, относящаяся к Firebase:

process.env.FIREBASE_CONFIG: предоставляет следующую информацию о конфигурации проекта Firebase:

{
  databaseURL: 'https://DATABASE_NAME.firebaseio.com',
  storageBucket: 'PROJECT_ID.firebasestorage.app',
  projectId: 'PROJECT_ID'
}

Обратите внимание, что значения в вашей конфигурации Firebase могут отличаться в зависимости от ресурсов, которые вы подготовили в своем проекте.

Эта конфигурация применяется автоматически, когда вы инициализируете Firebase Admin SDK без аргументов. Если вы пишете функции на JavaScript, инициализируйте их следующим образом:

const admin = require('firebase-admin');
admin.initializeApp();

Если вы пишете функции на TypeScript, инициализируйте их следующим образом:

import * as functions from 'firebase-functions/v1';
import * as admin from 'firebase-admin';
import 'firebase-functions/v1';
admin.initializeApp();

Если вам нужно инициализировать Admin SDK с конфигурацией проекта по умолчанию, используя учетные данные сервисного аккаунта, вы можете загрузить учетные данные из файла и добавить их в FIREBASE_CONFIG следующим образом:

serviceAccount = require('./serviceAccount.json');

const adminConfig = JSON.parse(process.env.FIREBASE_CONFIG);
adminConfig.credential = admin.credential.cert(serviceAccount);
admin.initializeApp(adminConfig);