Изменить Remote Config программно

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

Используя REST API Remote Config или Admin SDK, описанные в этом руководстве, вы можете обойти управление шаблоном в консоли Firebase, чтобы напрямую интегрировать изменения Remote Config в свои собственные процессы. Например, с помощью серверных API Remote Config вы можете:

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

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

  

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

• Firebase Remote Config REST API Java Quickstart
• Firebase Remote Config REST API Node.js Quickstart
• Firebase Remote Config REST API Python Quickstart

Измените Remote Config с помощью Firebase Admin SDK.

Admin SDK — это набор серверных библиотек, которые позволяют вам взаимодействовать с Firebase из привилегированных сред. Помимо выполнения обновлений Remote Config, Admin SDK позволяет генерировать и проверять токены аутентификации Firebase, читать и записывать из базы данных реального времени и т. д. Чтобы узнать больше о предварительных требованиях и настройке Admin SDK, см. раздел Добавление Firebase Admin SDK на ваш сервер .

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

Инициализировать SDK и авторизовать запросы API

Когда вы инициализируете Admin SDK без параметров, SDK использует учетные данные приложения Google по умолчанию и считывает параметры из переменной среды FIREBASE_CONFIG . Если содержимое переменной FIREBASE_CONFIG начинается с { , оно будет проанализировано как объект JSON. В противном случае SDK предполагает, что строка является именем файла JSON, содержащего параметры.

Например:

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

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Получить текущий шаблон удаленной конфигурации

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

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

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

Чтобы получить шаблон:

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());

Изменить параметры удаленной конфигурации

Вы можете программно изменять и добавлять параметры и группы параметров Remote Config. Например, в существующую группу параметров с именем «new_menu» можно добавить параметр для управления отображением сезонной информации:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

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

Изменить условия удаленной конфигурации

Вы можете программно изменять и добавлять условия и условные значения Remote Config. Например, чтобы добавить новое условие:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

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

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

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

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

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());
  }
}

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

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

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

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

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

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

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

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

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

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

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());
  }
}

Изменить Remote Config с помощью REST API

В этом разделе описываются основные возможности REST API Remote Config по адресу https://firebaseremoteconfig.googleapis.com . Полную информацию см. в справочнике по API .

Получите токен доступа для аутентификации и авторизации запросов API.

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

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

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

1. В консоли Firebase откройте «Настройки» > «Учетные записи служб» .

2. Нажмите «Создать новый закрытый ключ» , затем подтвердите, нажав «Создать ключ» .

3. Надежно сохраните файл JSON, содержащий ключ.

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

Чтобы установить переменную среды:

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

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

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

Используйте свои учетные данные Firebase вместе с библиотекой Google Auth Library для предпочитаемого языка, чтобы получить недолговечный токен доступа OAuth 2.0:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
Configure.java

По истечении срока действия маркера доступа автоматически вызывается метод обновления маркера для получения обновленного маркера доступа.

Чтобы авторизовать доступ к Remote Config, запросите область https://www.googleapis.com/auth/firebase.remoteconfig .

Изменить шаблон удаленной конфигурации

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

Получить текущий шаблон удаленной конфигурации

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

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

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

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

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

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

При желании вы можете проверить свои обновления перед их публикацией. Проверьте обновления шаблона, добавив к запросу на публикацию параметр URL ?validate_only=true . В ответе код состояния 200 и обновленный etag с суффиксом -0 означает, что ваше обновление было успешно проверено. Любой ответ, отличный от 200, указывает на то, что данные JSON содержат ошибки, которые необходимо исправить перед публикацией.

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

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

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

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

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

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

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

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

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

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

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Изменить условия удаленной настройки

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

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

Приведенные выше модификации сначала определяют набор условий, а затем определяют значения по умолчанию и значения параметров на основе условий ( условные значения ) для каждого параметра. Он также добавляет необязательное описание для каждого элемента; как и комментарии к коду, они предназначены для разработчиков и не отображаются в приложении. ETag также предоставляется для контроля версий.

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

Коды ошибок HTTP

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

После отправки обновлений шаблона перейдите в консоль Firebase, чтобы убедиться, что ваши изменения отображаются должным образом. Это очень важно, потому что порядок условий влияет на то, как они оцениваются (вступает в силу первое условие, которое оценивается true ).

Использование ETag и принудительные обновления

REST API Remote Config использует тег сущности (ETag) для предотвращения условий гонки и перекрывающихся обновлений ресурсов. Чтобы узнать больше о ETag, см. ETag — HTTP .

Для REST API Google рекомендует кэшировать ETag, предоставленный самой последней командой GET , и использовать это значение ETag в заголовке запроса If-Match при выдаче команд PUT . Если ваша команда PUT приводит к коду состояния HTTPS 409, вы должны ввести новую команду GET , чтобы получить новый ETag и шаблон для использования с вашей следующей командой PUT .

Вы можете обойти ETag и защиту, которую он обеспечивает, принудительно обновив шаблон Remote Config следующим образом: If-Match: * Однако этот подход не рекомендуется, поскольку он может привести к потере обновлений вашей Remote Config. шаблон, если несколько клиентов обновляют шаблон Remote Config. Конфликт такого рода может возникнуть с несколькими клиентами, использующими API, или с конфликтующими обновлениями от клиентов API и пользователей консоли Firebase.

Руководство по управлению версиями шаблонов Remote Config см. в разделе Шаблоны и управление версиями Remote Config .