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

Шаблон Remote Config — это серверный набор параметров и условий в формате JSON, который вы создали для своего проекта Firebase. Вы можете изменять шаблон и управлять им с помощью консоли Firebase, которая отображает содержимое шаблона в графическом формате на вкладках «Параметры » и «Условия» . Вы также можете использовать REST API удаленной настройки и Admin SDK или интерфейс командной строки 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. Всего существует ограничение в 300 сохраненных версий за весь срок службы, включая сохраненные номера версий для удаленных шаблонов. Если вы публикуете более 300 версий шаблона за время существования проекта, самые ранние версии удаляются, сохраняя максимум 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 из консоли Firebase. Чтобы удалить шаблон Remote Config:

  1. На странице «Параметры удаленной конфигурации» нажмите изменений» .

  2. Переключитесь на шаблон, который хотите удалить, нажмите More , затем выберите «Удалить» .

  3. Когда будет предложено подтвердить удаление, нажмите «Удалить» .

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

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

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

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

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

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

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

  1. Загрузите текущий шаблон конфигурации Remote 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. На вкладке «Параметры удаленной конфигурации» или «Условия» откройте меню и выберите «Загрузить текущий файл конфигурации» .
  2. При появлении запроса нажмите «Загрузить файл конфигурации» , выберите место, где вы хотите сохранить файл, затем нажмите «Сохранить» .

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

firebase remoteconfig:get -o filename

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

Вы можете проверить обновления шаблонов перед их публикацией с помощью Firebase Admin SDK или REST API. Шаблоны также проверяются при попытке публикации из интерфейса командной строки Firebase или консоли 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).

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

После загрузки шаблона, внесения всех необходимых изменений в содержимое 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. При появлении запроса нажмите «Обзор» , найдите и выберите файл удаленной конфигурации, который вы хотите опубликовать, затем нажмите «Выбрать» .
  3. Файл будет проверен, и в случае успеха вы сможете нажать «Опубликовать» , чтобы сделать конфигурацию немедленно доступной для ваших приложений и пользователей.

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

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

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

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

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

  • Если шаблон, который вы планируете опубликовать, содержит условия, основанные на Google Analytics, Google 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 в ваше приложение см. в разделах: