以编程方式修改 Remote Config

本文档介绍如何以编程方式读取和修改一组 JSON 格式的参数和条件（称为 Remote Config 模板）。这样，您就可以在后端更改模板，而客户端应用可以使用客户端库获取更改。

借助此指南中所述的 Remote Config REST API 或 Admin SDK，您可以直接将 Remote Config 更改集成到您自己的流程中，而不必在 Firebase 控制台中管理模板。例如，使用 Remote Config 后端 API，您可以：

• 安排 Remote Config 更新。将 API 调用与 Cron 作业结合使用，您可以定期更改 Remote Config 的值。
• 批量导入配置值，从而高效地从您自己的专有系统过渡到 Firebase Remote Config。

• 将 Remote Config 与 Cloud Functions for Firebase 搭配使用，根据服务器端发生的事件更改应用中的值。例如，您可以使用 Remote Config 在应用中推广某项新功能，然后在检测到有足够多的用户与这项新功能进行交互后，自动关停该推广。

  

本指南的以下部分介绍了使用 Remote Config 后端 API 可以执行的操作。如需参考通过 REST API 执行这些任务的代码，请参阅以下示例应用：

• Firebase Remote Config REST API Java 快速入门
• Firebase Remote Config REST API Node.js 快速入门
• Firebase Remote Config REST API Python 快速入门

使用 Firebase Admin SDK 修改 Remote Config

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 文件的名称。

例如：

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 模板

使用 Remote Config 模板时，请注意以下几点：这些模板受版本控制，每个版本的有效期均为 90 天（从创建之日起到使用更新版本将其替换为止），并且存储的版本总数不能超过 300 个。如需了解详情，请参阅模板和版本控制。

您可以使用后端 API 获取 JSON 格式 Remote Config 模板的当前活跃版本。

专门作为 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 参数

您可以通过编程方式修改和添加 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 条件

您可以通过编程方式修改和添加 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));

在任何情况下，您都必须在修改后明确发布模板。

Remote Config 后端 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());
  }
}

此验证过程会检查错误，例如重复的参数和条件键、无效的条件名称、不存在的条件或格式错误的 ETag。例如，如果请求包含的键数超过允许的数量（2000 个），则会返回错误消息 Param count too large。

发布 Remote Config 模板

检索到模板并按您期望的更新对其进行修改后，就可以发布该模板了。按照本部分中的说明发布模板，将整个现有配置模板替换为更新的文件，系统会为新的活跃模板分配一个版本号，该版本号会比其要替换的模板大一个数字。

如有必要，可以使用 REST API 回滚到先前版本。 为减少更新出错的风险，您可以在发布之前先进行验证。

下载的模板中包含 Remote Config 个性化设置和条件，因此在尝试将模板发布到其他项目中时，务必注意以下限制：

• 无法在不同的项目之间导入个性化设置。

  例如，如果您在项目中启用了个性化功能，之后下载并修改了一个模板，那么您可以将该模板发布到同一项目中，但不能将其发布到其他项目中，除非您删除该模板中的个性化设置。

• 您可以在不同的项目之间导入条件，但请注意，对于任何特定的条件值（如应用 ID 或受众群体），在发布之前，它们必须已事先存在于目标项目中。

  例如，如果您的 Remote Config 参数使用了指定平台值 iOS 的条件，那么您可以将模板发布到其他项目，因为所有项目的平台值都是相同的。但是，如果其中包含的条件依赖于目标项目中不存在的特定条件值（如某个特定应用 ID 或某一特定受众群体），则验证将失败。

• 如果您计划发布的模板包含依赖于 Google Analytics（分析）的条件，则必须在目标项目中启用 Google 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 修改 Remote Config

本部分介绍 https://firebaseremoteconfig.googleapis.com 中 Remote Config REST API 的主要功能。 如需了解完整详情，请参阅 API 参考文档。

获取访问令牌以对 API 请求进行身份验证和授权

Firebase 项目支持 Google 服务帐号，您可以使用这些帐号从应用服务器或受信任环境调用 Firebase 服务器 API。如果您是在本地编写代码，或是在本地部署您的应用，则可以使用通过此服务帐号获取的凭据来对服务器请求进行授权。

如需对服务帐号进行身份验证并授予其访问 Firebase 服务的权限，您必须生成 JSON 格式的私钥文件。

如需为您的服务帐号生成私钥文件，请执行以下操作：

1. 在 Firebase 控制台中，打开设置 > 服务帐号。

2. 点击生成新的私钥，然后点击生成密钥进行确认。

3. 妥善存储包含密钥的 JSON 文件。

通过服务帐号进行授权时，有两种方式可为您的应用提供凭据。您可以设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，也可以在代码中明确传递服务帐号密钥的路径。第一种方式更为安全，因此强烈推荐使用此方式。

如需设置环境变量，请执行以下操作：

将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务帐号密钥的 JSON 文件的路径：此变量仅适用于当前的 Shell 会话，因此请在开始新的会话时重新设置该变量。

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

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

完成上述步骤后，应用默认凭据 (ADC) 能够隐式确定您的凭据，如此您便能在非 Google 环境中测试或运行时使用服务帐号凭据。

将您的 Firebase 凭据与适用于您的偏好语言的 Google API 客户端库结合使用，以检索短期有效的 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

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

在您的访问令牌到期后，系统会自动调用令牌刷新方法以检索更新的访问令牌。

如需授予访问 Remote Config 的权限，应请求 https://www.googleapis.com/auth/firebase.remoteconfig 范围。

修改 Remote Config 模板

使用 Remote Config 模板时，请注意以下几点：这些模板受版本控制，每个版本的有效期均为 90 天（从创建之日起到使用更新版本将其替换为止），并且存储的版本总数不能超过 300 个。如需了解详情，请参阅模板和版本控制。

获取当前的 Remote Config 模板

您可以使用后端 API 获取 JSON 格式 Remote Config 模板的当前活跃版本。

专门作为 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

验证 Remote Config 模板

您也可以选择在发布更新前先对其进行验证。 将网址参数 ?validate_only=true 附加到您的发布请求，来验证模板更新。 如果响应中包含状态代码 200 以及后缀为 -0 的更新后的 ETag，则表示您的更新已成功通过验证。如果响应中的状态代码不是 200，则表示 JSON 数据包含错误，您必须在发布前进行更正。

更新 Remote Config 模板

检索模板并按您期望的更新修改 JSON 内容后，就可以发布该模板了。按照本部分中的说明发布模板，将整个现有配置模板替换为更新的文件，系统会为新的活跃模板分配一个版本号，该版本号会比其要替换的模板大一个数字。

如有必要，可以使用 REST API 回滚到先前版本。 为减少更新出错的风险，您可以在发布之前先进行验证。

下载的模板中包含 Remote Config 个性化设置和条件，因此在尝试将模板发布到其他项目中时，务必注意以下限制：

• 无法在不同的项目之间导入个性化设置。

  例如，如果您在项目中启用了个性化功能，之后下载并修改了一个模板，那么您可以将该模板发布到同一项目中，但不能将其发布到其他项目中，除非您删除该模板中的个性化设置。

• 您可以在不同的项目之间导入条件，但请注意，对于任何特定的条件值（如应用 ID 或受众群体），在发布之前，它们必须已事先存在于目标项目中。

  例如，如果您的 Remote Config 参数使用了指定平台值 iOS 的条件，那么您可以将模板发布到其他项目，因为所有项目的平台值都是相同的。但是，如果其中包含的条件依赖于目标项目中不存在的特定条件值（如某个特定应用 ID 或某一特定受众群体），则验证将失败。

• 如果您计划发布的模板包含依赖于 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

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 条件

您可以通过编程方式修改 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。

Remote Config 后端 API 提供了多个条件和比较运算符，可供您更改应用的行为和外观。如需详细了解条件以及这些条件支持的运算符，请参阅条件表达式参考文档。

HTTP 错误代码

如果看到状态代码 200，则意味着 Remote Config 模板（项目的参数、值和条件）已更新，现已可用于使用此项目的应用。如果看到其他状态代码，则意味着以前存在的 Remote Config 模板仍然有效。

在您提交对模板的更新后，请转到 Firebase 控制台，以验证您所做的更改是否按预期显示。这一步至关重要，因为条件的排序会影响它们的求值方式（第一个求值为 true 的条件会生效）。

ETag 用法和强制更新

Remote Config REST API 使用了实体标记 (ETag) 来避免竞态条件和对资源的重叠更新。如需详细了解 ETag，请参阅 ETag - HTTP。

针对 REST API，Google 建议您缓存最新 GET 命令提供的 ETag，并在发出 PUT 命令时在 If-Match 请求标头中使用该 ETag 值。如果您的 PUT 命令导致出现 HTTPS 状态代码 409，您应该用新的 GET 命令来获取新的 ETag 和模板，供下一个 PUT 命令使用。

通过强制 Remote Config 模板按如下方式进行更新，您可以不使用 ETag 及其提供的保护：If-Match: *。但是，我们不建议使用此方法，因为如果有多个客户端正在更新 Remote Config 模板，此方法可能会导致对 Remote Config 模板的更新丢失。如果多个客户端都在使用 API，或者来自 API 客户端和 Firebase 控制台用户的更新存在冲突，都可能造成这种冲突。

如需管理 Remote Config 模板版本的指导，请参阅 Remote Config 模板和版本控制。