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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

  

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

• Быстрый старт Java для Firebase Remote Config REST API
• Быстрый старт 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 Application Default и считывает параметры из переменной среды 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"

После выполнения вышеуказанных шагов Application Default Credentials (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

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 и принудительные обновления

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

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

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

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