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

    Диаграмма, показывающая серверную часть Remote Config, взаимодействующую с настраиваемыми инструментами и серверами.

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

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

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

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

Инициализируйте SDK и авторизуйте запросы API.

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

Например:

Node.js

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-тестирования, не включаются в экспортированные шаблоны.

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

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

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

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

Node.js

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. Например, чтобы добавить новое условие:

Node.js

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 предоставляют несколько условий и операторов сравнения, которые можно использовать для изменения поведения и внешнего вида вашего приложения. Дополнительные сведения об условиях и операторах, поддерживаемых для этих условий, см. в справочнике по условным выражениям .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Измените удаленную конфигурацию с помощью REST API.

В этом разделе описаны основные возможности REST API удаленной настройки на 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"

Окна

С PowerShell:

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

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

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

узел.js

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

В этом примере клиентская библиотека Google API проверяет подлинность запроса с помощью веб-токена JSON или JWT. Дополнительные сведения см. в разделе Веб-токены JSON .

Питон

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

Джава

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

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

Чтобы авторизовать доступ к 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

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

Необработанный HTTP-запрос

Host: firebaseremoteconfig.googleapis.com

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

Этот вызов API возвращает следующий JSON вместе с отдельным заголовком, который включает ETag , который вы используете для последующего запроса.

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

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

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

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

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

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

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

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

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

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

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

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

Необработанный HTTP-запрос

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

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

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

Вы можете программно изменить условия и условные значения 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 Успешно обновлено
400 Произошла ошибка проверки. Например, запрос, содержащий больше разрешенного количества ключей (2000), вернет 400 (неверный запрос) с сообщением об ошибке: Param count too large . Кроме того, этот код состояния HTTPS может возникнуть в этих двух ситуациях:
  • Произошла ошибка несоответствия версий, поскольку набор значений и условий был обновлен с момента последнего получения значения ETag. Чтобы решить эту проблему, вам следует использовать команду GET , чтобы получить новый шаблон и значение ETag, обновить шаблон, а затем отправить его, используя этот шаблон и новое значение ETag.
  • Команда PUT (запрос шаблона обновления удаленной конфигурации) была выполнена без указания заголовка If-Match .
401 Произошла ошибка авторизации (токен доступа не был предоставлен или REST API Firebase Remote Config не был добавлен в ваш проект в консоли разработчика Cloud).
403 Произошла ошибка аутентификации (был предоставлен неправильный токен доступа)
500 Возникла внутренняя ошибка. Если возникает эта ошибка, отправьте запрос в службу поддержки Firebase.

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

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

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

REST API удаленной настройки использует тег объекта (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 .