Google is committed to advancing racial equity for Black communities. See how.
Эта страница была переведа с помощью Cloud Translation API.
Switch to English

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

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

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

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

Например:

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

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

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

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

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

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

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

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: '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',
  });
}

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

Серверные 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);
      });
}

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

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

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

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

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

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

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

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

Linux или macOS

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

Windows

С PowerShell:

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

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

Используйте свои учетные данные Firebase вместе с клиентской библиотекой Google API для предпочитаемого языка, чтобы получить недолговечный токен доступа 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 {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

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

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

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

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

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

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

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

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

Обновите шаблон Remote Config

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

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

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

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

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

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

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

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