В этом документе описывается, как программно читать и изменять набор параметров и условий в формате 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, содержащего параметры.
Например:
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 Testing не включаются в экспортированные шаблоны.
Чтобы получить шаблон:
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 , 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 Remote Config на https://firebaseremoteconfig.googleapis.com . Полную информацию см. в справочнике по API .
Получите токен доступа для аутентификации и авторизации запросов API.
Проекты Firebase поддерживают учетные записи служб Google, которые вы можете использовать для вызова API-интерфейсов сервера Firebase с вашего сервера приложений или доверенной среды. Если вы разрабатываете код локально или развертываете приложение локально, вы можете использовать учетные данные, полученные через эту учетную запись службы, для авторизации запросов к серверу.
Чтобы аутентифицировать учетную запись службы и разрешить ей доступ к службам Firebase, вам необходимо создать файл закрытого ключа в формате JSON.
Чтобы создать файл закрытого ключа для вашей учетной записи службы:
В консоли Firebase откройте «Настройки» > «Учетные записи служб» .
Нажмите «Создать новый закрытый ключ» , затем подтвердите действие, нажав «Создать ключ» .
Надежно сохраните файл 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 Testing не включаются в экспортированные шаблоны.
Используйте следующие команды:
КУЛЬ
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 , 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 может возникнуть в этих двух ситуациях:
|
| 401 | Произошла ошибка авторизации (токен доступа не был предоставлен или REST API Firebase Remote Config не был добавлен в ваш проект в консоли разработчика Cloud). |
| 403 | Произошла ошибка аутентификации (был предоставлен неправильный токен доступа) |
| 500 | Произошла внутренняя ошибка. Если возникает эта ошибка, отправьте запрос в службу поддержки Firebase. |
Код состояния 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 .