Изменить 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 с Cloud Functions for Firebase , изменяя значения в вашем приложении в зависимости от событий, происходящих на стороне сервера. Например, вы можете использовать Remote Config для продвижения новой функции в вашем приложении, а затем автоматически отключить это продвижение, как только обнаружите, что достаточное количество людей взаимодействовало с новой функцией.

  

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

• Firebase Remote Config REST API Краткое руководство по Java
• Firebase Remote Config REST API Node.js Краткое руководство
• Firebase Remote Config REST API Краткое руководство по Python

Измените удаленную конфигурацию с помощью Firebase Admin SDK

Admin SDK — это набор серверных библиотек, которые позволяют вам взаимодействовать с Firebase из привилегированных сред. Помимо выполнения обновлений Remote Config , Admin SDK позволяет генерировать и проверять токены аутентификации Firebase, читать и записывать из Realtime Database и т. д. Дополнительные сведения о необходимых требованиях и настройке 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 Testing не включаются в экспортированные шаблоны.

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

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 .

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

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

При необходимости вы можете использовать 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());
  }
}

Измените удаленную конфигурацию с помощью 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 для предпочитаемого вами языка, чтобы получить недолговечный токен доступа 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

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

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

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

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

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

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

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

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

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

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 .