Remote Config REST API

本文档介绍如何使用 Remote Config REST API 读取和修改一组 JSON 格式的参数和条件(称为远程配置模板)。这样您就可以以编程方式管理该模板,并在后端更改模板(客户端应用可以使用客户端库获取这些更改)。

借助此 API,您可以绕过在远程配置控制台中管理模板这种方式,直接将远程配置更改整合到您自己的流程中。例如,使用 Remote Config REST API,您可以执行以下操作:

  • 安排远程配置更新。通过将 REST API 与 Cron 作业结合使用,您可以定期更改远程配置的值。
  • 批量导入配置值,从而高效地从您自己的专有系统过渡到 Firebase 远程配置。
  • 自动创建版本历史记录。每当您通过 API 发布对远程配置所做的新更改时,系统会将现有配置保存到本地文件或 Cloud Firestore 之类的数据库中。
  • 将远程配置与 Cloud Functions for Firebase 搭配使用,并根据服务器端发生的事件更改应用中的值。例如,您可以使用远程配置在应用中宣传某项新功能,然后在检测到有足够多的用户与这项新功能发生互动后,自动终止该宣传活动。

开始使用 Remote Config REST API

此部分中的步骤介绍了如何使用 API 获取和修改远程配置模板。在实际修改模板之前,请务必创建一个配置模板的备份副本,以便在必要时能够使用此副本来还原该模板(第 3 步介绍了如何执行此操作)。使用此 API 进行的每项 HTTP PUT 操作都会完全替换掉应用的现有配置模板,即使您只更改了模板中的一个参数或条件,也是如此。

开始之前:启用 Remote Config REST API

在使用 Remote Config REST API 之前,您必须按照以下步骤在 Google API 控制台中启用它:

  1. 在 Google API 控制台中打开 Firebase Remote Config API 页面
  2. 出现提示时,选择您的 Firebase 项目(每个 Firebase 项目在 Google API 控制台中都有一个对应的项目)。
  3. 点击 Firebase Remote Config API 页面上的启用

第 1 步:在 Firebase 控制台中设置值

通常,您首先需要在 Firebase 控制台中设置值。在本指南中,假设您已经设置了 iOSAndroid 版远程配置快速入门示例应用。对于此应用,您只需在 Firebase 控制台中添加以下两个参数即可:

参数键 默认值 说明
welcome_message Welcome to this sample app 可改用其他欢迎消息。
welcome_message_caps false 若设为 true,显示的欢迎消息全部为大写。

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

每个 Firebase 项目都有一个默认的服务帐号。您可以使用此帐号从您的应用服务器或受信任环境调用 Firebase 服务器 API。如果您要使用其他服务帐号,请确保帐号拥有修改者或所有者权限。

要对服务帐号进行身份验证并授权其访问 Firebase 服务,您必须生成 JSON 格式的私钥文件,并使用此密钥来检索在短时间内有效的 OAuth 2.0 令牌。获得有效令牌后,您可以根据各种 Firebase 服务(如远程配置或 FCM)的要求将其添加到服务器请求中。

为您的服务帐号生成私钥文件:

  1. 在 Firebase 控制台中,打开设置 > 服务帐号
  2. 点击生成新的私钥,然后点击生成密钥进行确认。
  3. 妥善存储包含密钥的 JSON 文件。您将需要此文件才能完成下一步操作。

检索访问令牌:

要检索令牌,您可以使用与您偏好的编程语言对应的 Google API 客户端库,并按如下所示参考私钥 JSON 文件:

node.js

function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

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

Java

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 API 请求授权,请务必指定此范围:

 var SCOPES = [
   "https://www.googleapis.com/auth/firebase.remoteconfig"
 ];

第 3 步:使用 API 从远程配置服务获取 JSON

接下来,您可以使用 API 获取 JSON 格式的远程配置模板。您可以使用以下命令来执行此操作(请将 <my-project-id> 替换为您自己的项目 ID,后者可在 Firebase 控制台的“设置”窗格中找到):

curl 命令:

curl --compressed -i -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: /

此 API 调用会返回以下 JSON,以及一个单独的标头(其中包含用于后续请求的 ETag)。以下示例展示了返回的 JSON:

{
  "parameters": [{
    "key": "welcome_message",
    "value_options": [{
      "value": "Welcome to this sample app"
    }]
   }, {
    "key": "welcome_message_caps",
    "value_options": [{
      "value": "false"
    }]
  }]
}

第 4 步:为 JSON 数据添加条件

接下来,添加一些条件和条件值,以便示例应用:

  • 向 10% 的用户显示一条稍有不同的消息(添加单词“new”)。
  • 针对美国或英国的用户显示全部为大写的消息。

要以这些方式扩展 JSON,请创建一个包含以下内容的文件:

{
  "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."
    }
  }
}

上面显示的 JSON 首先定义了一组条件,然后为每个参数定义了默认值和基于条件的参数值(“条件值”)。它还为每个元素添加了说明(可选);像代码注释一样,这些是供开发者使用的,并不显示在应用中。另外,为便于版本控制,它还在一个单独的标头中提供了一个 ETag

Remote Config REST API 提供了多个条件和比较运算符,可供您更改应用的行为和外观。要详细了解条件以及这些条件支持的运算符,请参阅参考文档

第 5 步:发布 JSON 数据以在远程配置服务中替换数据

创建用以更新远程配置模板的 JSON 文件后,您便可以发布该文件了,方法是将上述 JSON 添加到下面的命令中,并使用在第 4 步中创建的文件的内容进行替换。如上所述,此操作会将整个现有配置模板替换为更新的文件。

对于 curl 命令,您使用“@”字符(后跟文件名)即可指定相应的内容。

curl 命令:

curl --compressed -i -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

原始 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
JSON_HERE

由于这是一个写入请求,因此该命令将修改 ETag,并将在下一个 PUT 命令的响应标头中提供更新后的 ETag。

此 API 调用会生成下表中所示的某个状态代码:

状态代码 含义
200 已成功更新
400 发生验证错误。例如,如果某个请求包含的键数超过允许的数量(2000 个),则会返回 400(请求错误)错误,并显示错误消息 Param count too large
401 发生授权错误(未提供访问令牌;或者 Firebase Remote Config REST API 尚未添加到您在 Cloud Developer Console 中的项目)
403 发生身份验证错误(提供的访问令牌有误)
409 在以下两种情况下,您会收到此 HTTP 状态代码:
  • 由于值和条件自您上次检索 ETag 值后发生了更新,因此导致发生版本不匹配错误。要解决此错误,您应该使用 GET 命令获取最新的模板和 ETag 值,更新该模板,然后使用该模板和最新 ETag 值进行提交。
  • 在未指定 If-Match 标头的情况下执行了 PUT 命令(更新远程配置模板请求)。
500 发生内部错误。如果发生此错误,请提交 Firebase 支持服务单据

如果看到状态代码 200,则意味着远程配置模板(项目的参数、值和条件)已更新,现已可用于使用此项目的应用。如果看到其他状态代码,则意味着以前存在的远程配置模板仍然有效。

在您提交对模板的更新后,请转到 Firebase 控制台,以验证您所做的更改是否符合预期。这一步至关重要,因为条件的排列顺序会影响它们的求值方式(求值结果为 true 的第一个条件会生效)。

ETag 用法和强制更新

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

Google 建议您按规范使用 ETag,来避免竞态条件和对资源的重叠更新。这意味着您可以缓存最新 GET 命令提供的 ETag,并在发出 PUT 命令时在 If-Match 请求标头中使用该 ETag 值。如果您的 PUT 命令导致出现 HTTPS 状态代码 409,您应该发出新的 GET 命令来获取新的 ETag 和模板,供您的下一个 PUT 命令使用。

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

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面