Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

Программное изменение Remote Config

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

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

  • Планирование удаленного обновления конфигурации. Используя вызовы API в сочетании с заданием cron, вы можете изменять значения Remote Config по регулярному расписанию.
  • Значения импорта конфигурации Batch с целью перехода к эффективно от вашей собственной патентованной системы к Firebase Remote Config.
  • Использование Удаленная настройка с облачных функций для Firebase, изменяя значения в вашем приложении на основе событий , которые происходят на стороне сервера. Например, вы можете использовать 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 переменной окружения. Если содержание 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 сохраненных версий. См шаблонов и Versioning для получения дополнительной информации.

Вы можете использовать серверные API-интерфейсы, чтобы получить текущую активную версию шаблона 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());

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

Вы можете программно изменять и добавлять параметры и группы параметров 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 для отката к предыдущей версии . Чтобы снизить риск возникновения ошибок в обновлении, вы можете проверить перед публикацией .

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

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

Linux или macOS

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 вместе с Auth библиотекой Google для предпочитаемого языка , чтобы получить кратковременный доступ OAuth 2.0 лексем:

node.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 веб - маркеры .

Python

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

Джава

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

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

Для того, чтобы разрешить доступ к дистанционному Config, запросить объем https://www.googleapis.com/auth/firebase.remoteconfig .

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

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

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

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

cURL

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 , который используется для последующего запроса.

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

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

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

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

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

cURL

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

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

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

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

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

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

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

Для руководства по управлению удаленными версиями шаблонов Config см Удаленные шаблоны Config и управление версиями .