Catch up on highlights from Firebase at Google I/O 2023. Learn more

Шаблоны удаленной конфигурации и управление версиями

Шаблон Remote Config — это серверный набор параметров и условий в формате JSON, которые вы создали для своего проекта Firebase. Вы можете изменять шаблон и управлять им с помощью консоли Firebase, которая отображает содержимое шаблона в графическом формате на вкладках «Параметры » и «Условия» . Вы также можете использовать внутренние API-интерфейсы Remote Config или интерфейс командной строки Firebase для изменения и управления вашей конфигурацией.

Вот пример файла шаблона:

  {
    "conditions": [
      {
        "name": "ios",
        "expression": "device.os == 'ios'"
      }
    ],
    "parameters": {
      "welcome_message": {
        "defaultValue": {
          "value": "Welcome to this sample app"
        },
        "conditionalValues": {
          "ios": {
            "value": "Welcome to this sample iOS app"
          }
        }
      },
      "welcome_message_caps": {
        "defaultValue": {
          "value": "false"
        }
      },
      "header_text": {
        "defaultValue": {
          "useInAppDefault": true
        }
      }
    },
    "version": {
      "versionNumber": "28",
      "updateTime": "2020-05-14T18:39:38.994Z",
      "updateUser": {
        "email": "user@google.com"
      },
      "updateOrigin": "CONSOLE",
      "updateType": "INCREMENTAL_UPDATE"
    }
  }

Каждый раз, когда вы обновляете параметры, Remote Config создает новый шаблон Remote Config с новой версией и сохраняет предыдущий шаблон как версию, которую вы можете получить или вернуться к ней по мере необходимости. Номера версий последовательно увеличиваются от начального значения, сохраненного Remote Config. Все шаблоны включают поле version , как показано, содержащее метаданные об этой конкретной версии.

С помощью консоли Firebase, интерфейса командной строки Firebase или внутренних API-интерфейсов Remote Config вы можете выполнять следующие задачи управления версиями:

  • Список всех сохраненных версий шаблона
  • Получить конкретную версию
  • Откат к определенной версии

При управлении шаблонами Remote Config помните о пороге истечения срока действия: Срок действия текущего активного шаблона Remote Config, используемого вашим приложением, не истекает; однако, если его заменить обновлением, предыдущая версия будет храниться только в течение 90 дней, после чего срок ее действия истечет, и ее нельзя будет получить. Существует также общий лимит в 300 сохраненных версий. Если вы хотите сохранить или вернуться к шаблону за пределами этих ограничений, сохраните его вручную.

Управление версиями шаблона Remote Config

В этом разделе описывается, как управлять версиями вашего шаблона Remote Config. Дополнительные сведения о программном создании, изменении и сохранении шаблонов см. в разделе Программное изменение Remote Config .

Список всех сохраненных версий шаблона Remote Config

Вы можете получить список всех сохраненных версий шаблона Remote Config. Например:

Node.js

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Джава

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

ОТДЫХ

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:listVersions

Консоль Firebase

На вкладке «Параметры» выберите значок «часы», отображаемый в правом верхнем углу. Откроется страница истории изменений со списком всех сохраненных версий шаблона в меню списка справа.

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

Интерфейс командной строки Firebase

firebase remoteconfig:versions:list

Используйте параметр --limit , чтобы ограничить количество возвращаемых версий. Передайте «0», чтобы получить все версии.

Список шаблонов включает метаданные для всех сохраненных версий, включая время обновления, пользователя, который его сделал, и было ли оно сделано через консоль или REST API. Вот пример элемента версии:

{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]

Получить определенную версию шаблона Remote Config

Вы можете получить любую конкретную сохраненную версию шаблона Remote Config. Например:

Node.js

Передайте getTemplate() без каких-либо аргументов, чтобы получить последнюю версию шаблона, или для получения конкретной версии используйте getTemplateAtVersion() .

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Джава

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

ОТДЫХ

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

Параметр URL ?version_number допустим только для операций GET ; вы не можете использовать его для указания номеров версий для обновлений. Аналогичный запрос на получение без параметра ?version_number извлечет текущий активный шаблон.

Консоль Firebase

По умолчанию в области сведений на вкладке История изменений отображается текущий активный шаблон. Чтобы просмотреть сведения о другой версии в списке, выберите ее в правом меню.

Вы можете просмотреть подробные различия между текущей выбранной версией и любой другой сохраненной версией, наведя указатель мыши на контекстное меню любой невыбранной версии и выбрав Сравнить с выбранной версией.

Интерфейс командной строки Firebase

firebase remoteconfig:get -v VERSION_NUMBER

При желании вы можете записать вывод в указанный файл с помощью -o, FILENAME .

Откат к определенной сохраненной версии шаблона Remote Config

Вы можете вернуться к любой сохраненной версии шаблона. Например:

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Джава

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

ОТДЫХ

Чтобы выполнить откат к сохраненному шаблону Remote Config, отправьте HTTP-запрос POST с помощью пользовательского метода :rollback и в тексте запроса укажите конкретную применяемую версию. Например:

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

Ответ содержит содержимое текущего активного сохраненного шаблона с метаданными его новой версии.

Консоль Firebase

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

Интерфейс командной строки Firebase

firebase remoteconfig:rollback -v VERSION_NUMBER

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

Загрузите и опубликуйте шаблоны Remote Config

Загрузите и опубликуйте шаблоны Remote Config, чтобы интегрировать их в свои системы управления версиями и сборки, автоматизировать обновления конфигурации и синхронизировать параметры и значения в нескольких проектах.

Вы можете скачать текущий активный шаблон Remote Config программно или из консоли Firebase. Затем вы можете обновить экспортированный файл JSON и опубликовать его в том же проекте или опубликовать в новом или существующем проекте.

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

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

Параметры и значения параметров, созданные специально как варианты эксперимента A/B-тестирования, не включаются в экспортируемые шаблоны.

Чтобы экспортировать и импортировать шаблоны Remote Config:

  1. Загрузите текущий шаблон Remote Config Config .
  2. Проверьте шаблон Remote Config .
  3. Опубликуйте шаблон Remote Config .

Загрузите текущий шаблон удаленной конфигурации

Вы можете загрузить текущий и активный шаблон Remote Config программно или с помощью консоли Firebase.

Используйте следующие команды для загрузки активного шаблона Remote Config в формате JSON:

Node.js

function getTemplate() {
  var config = admin.remoteConfig();
  config.getTemplate()
      .then(function (template) {
        console.log('ETag from server: ' + template.etag);
        var templateStr = JSON.stringify(template);
        fs.writeFileSync('config.json', templateStr);
      })
      .catch(function (err) {
        console.error('Unable to get template');
        console.error(err);
      });
}

Джава

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

ОТДЫХ

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Эта команда выводит полезные данные JSON в один файл, а заголовки (включая ETag) — в отдельный файл headers .

Консоль Firebase

  1. На вкладке Remote Config Parameters или Conditions откройте меню и выберите Download current config file .
  2. При появлении запроса нажмите «Загрузить файл конфигурации» , выберите место, где вы хотите сохранить файл, затем нажмите «Сохранить» .

Интерфейс командной строки Firebase

firebase remoteconfig:get -o filename

Проверка шаблона удаленной конфигурации

Вы можете проверить обновления шаблона перед их публикацией с помощью Firebase Admin SDK или REST API. Шаблоны также проверяются при попытке публикации из Firebase CLI или консоли Firebase.

Процесс проверки шаблона проверяет наличие ошибок, таких как повторяющиеся ключи для параметров и условий, недопустимые имена условий или несуществующие условия, а также неправильный формат ETag. Например, запрос, содержащий больше разрешенного количества ключей (2000), вернет сообщение об ошибке Param count too large .

Node.js

function validateTemplate(template) {
  admin.remoteConfig().validateTemplate(template)
      .then(function (validatedTemplate) {
        // The template is valid and safe to use.
        console.log('Template was valid and safe to use');
      })
      .catch(function (err) {
        console.error('Template is invalid and cannot be published');
        console.error(err);
      });
}

Джава

try {
  Template validatedTemplate = FirebaseRemoteConfig.getInstance()
          .validateTemplateAsync(template).get();
  System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Template is invalid and cannot be published");
    System.out.println(rcError.getMessage());
  }
}

ОТДЫХ

Проверьте обновления шаблона, добавив параметр URL ?validate_only=true к вашему запросу на публикацию:

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig?validate_only=true -d @filename

Если ваш шаблон был успешно проверен, команда curl возвращает отправленный вами шаблон JSON, а в сохраненном файле headers вы найдете статус HTTP/2 200 и обновленный ETag с суффиксом -0 . Если ваш шаблон не был проверен, вы получите ошибку проверки в ответе JSON, а ваш файл headers будет содержать ответ, отличный от 200 (и без ETag).

Публикация шаблона Remote Config

После загрузки шаблона, внесения необходимых изменений в содержимое JSON и его проверки вы можете опубликовать его в проекте.

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

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

Используйте следующие команды для публикации шаблона:

Node.js

function publishTemplate() {
  var config = admin.remoteConfig();
  var template = config.createTemplateFromJSON(
      fs.readFileSync('config.json', 'UTF8'));
  config.publishTemplate(template)
      .then(function (updatedTemplate) {
        console.log('Template has been published');
        console.log('ETag from server: ' + updatedTemplate.etag);
      })
      .catch(function (err) {
        console.error('Unable to publish template.');
        console.error(err);
      });
}

Джава

try {
  Template publishedTemplate = FirebaseRemoteConfig.getInstance()
          .publishTemplateAsync(template).get();
  System.out.println("Template has been published");
  // See the ETag of the published template.
  System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Unable to publish template.");
    System.out.println(rcError.getMessage());
  }
}

ОТДЫХ

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

Для этой команды curl вы можете указать содержимое, используя символ «@», за которым следует имя файла.

Консоль Firebase

  1. На вкладке «Параметры или условия удаленной конфигурации» откройте меню и выберите «Опубликовать из файла» .
  2. При появлении запроса нажмите «Обзор» , перейдите к файлу Remote Config, который вы хотите опубликовать, и выберите его, а затем нажмите «Выбрать» .
  3. Файл будет проверен, и в случае успеха вы сможете нажать «Опубликовать» , чтобы сделать конфигурацию немедленно доступной для ваших приложений и пользователей.

Персонализация и условия Remote Config включены в загруженные шаблоны, поэтому важно помнить о следующих ограничениях при попытке публикации в другом проекте:

  • Персонализации нельзя импортировать из проекта в проект.

    Например, если в вашем проекте включены персонализации и вы загружаете и редактируете шаблон, вы можете опубликовать его в том же проекте, но не можете опубликовать его в другом проекте, пока не удалите персонализации из шаблона.

  • Условия можно импортировать из проекта в проект, но обратите внимание, что любые определенные условные значения (например, идентификаторы приложений или аудитории) должны существовать в целевом проекте перед публикацией.

    Например, если у вас есть параметр Remote Config, в котором используется условие, задающее значение платформы iOS , шаблон можно опубликовать в другом проекте, поскольку значения платформы одинаковы для всех проектов. Однако, если он содержит условие, которое зависит от определенного идентификатора приложения или аудитории пользователей, не существующих в целевом проекте, проверка завершится ошибкой.

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

Скачать шаблон удаленной конфигурации по умолчанию

Поскольку ваше приложение не всегда может быть подключено к Интернету, вам следует настроить значения по умолчанию для клиентского приложения для всех параметров Remote Config. Вам также следует периодически синхронизировать значения по умолчанию клиента приложения и значения параметров по умолчанию серверной части Remote Config, поскольку они могут меняться со временем.

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

Вы можете загрузить эти файлы в формате XML для приложений Android, в формате списка свойств (plist) для приложений iOS и в формате JSON для веб-приложений.

Мы рекомендуем периодически загружать Remote Config по умолчанию перед выпуском любого нового приложения, чтобы обеспечить синхронизацию вашего приложения и серверной части Remote Config.

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

ОТДЫХ

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Используйте XML , PLIST или JSON в качестве значения format , в зависимости от того, какой формат файла вы хотите загрузить.

Консоль Firebase

  1. На вкладке «Параметры» откройте меню и выберите «Загрузить значения по умолчанию» .
  2. При появлении запроса щелкните переключатель, соответствующий формату файла, который вы хотите загрузить, а затем щелкните Загрузить файл .

Дополнительные сведения об импорте значений Remote Config по умолчанию в ваше приложение см. в следующих статьях: