Google is committed to advancing racial equity for Black communities. See how.
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

以編程方式修改遠程配置

本文檔介紹瞭如何以編程方式讀取和修改JSON格式的參數和條件集,稱為“ 遠程配置模板” 。這使您可以在客戶端應用程序可以使用客戶端庫獲取的後端進行模板更改。

使用本指南中描述的Remote Config REST APIAdmin SDK ,您可以繞過Firebase控制台中的模板管理,直接將Remote Config更改集成到您自己的進程中。例如,使用Remote Config後端API,您可以:

  • 安排遠程配置更新 。通過將API調用與cron作業結合使用,可以定期更改Remote Config的值。
  • 批量導入配置值 ,以便從您自己的專有系統高效地過渡到Firebase遠程配置。
  • 將Remote Config與Cloud Functions for Firebase結合使用 ,根據服務器端發生的事件更改應用程序中的值。例如,您可以使用“遠程配置”在應用程序中推廣新功能,然後在檢測到足夠多的人與新功能互動後自動關閉該推廣。

本指南的以下各節描述了可以使用Remote Config後端API進行的操作。要查看一些通過REST API執行這些任務的代碼,請參閱以下示例應用程序之一:

使用Firebase Admin SDK修改遠程配置

Admin SDK是一組服務器庫,可讓您從特權環境中與Firebase進行交互。除了執行對Remote Config的更新之外,Admin SDK還支持生成和驗證Firebase身份驗證令牌,從實時數據庫進行讀寫等等。要了解有關Admin SDK前提條件和設置的更多信息,請參閱將Firebase Admin SDK添加到您的服務器

在典型的Remote Config流中,您可能會獲取當前模板,修改一些參數或參數組和條件,驗證模板,然後發布它。在進行這些API調用之前,必須授權來自SDK的請求。

初始化SDK並授權API請求

當您不使用參數初始化Admin SDK時,SDK將使用Google Application Default Credentials並從FIREBASE_CONFIG環境變量中讀取選項。如果FIREBASE_CONFIG變量的內容以{開頭,它將被解析為JSON對象。否則,SDK會假定該字符串是包含選項的JSON文件的名稱。

例如:

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

獲取當前的遠程配置模板

使用Remote Config模板時,請記住它們是版本化的,並且每個版本從創建之時到您將其替換為更新之時的生命週期都是有限的:90天,總共存儲300個版本。有關更多信息,請參見模板和版本控制

您可以使用後端API以JSON格式獲取Remote Config模板的當前活動版本。獲取模板:

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

修改遠程配置參數

您可以以編程方式修改和添加遠程配置參數和參數組。例如,可以將一個參數添加到名為“ new_menu”的現有參數組中,以控制季節信息的顯示:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

該API允許您創建新的參數和參數組,或修改默認值,條件值和描述。在所有情況下,都必須在進行修改後顯式發布模板。

修改遠程配置條件

您可以以編程方式修改和添加“遠程配置”條件和條件值。例如,要添加新條件:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

在所有情況下,都必須在進行修改後顯式發布模板。

Remote Config後端API提供了幾種條件和比較運算符,您可以使用它們來更改應用程序的行為和外觀。要了解有關條件以及這些條件支持的運算符的更多信息,請參閱條件表達式參考

驗證遠程配置模板

(可選)您可以在發布更新之前對其進行驗證,如下所示:

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

此驗證過程將檢查錯誤,例如參數和條件的重複鍵,無效的條件名稱或不存在的條件或格式錯誤的etag。例如,如果請求包含的密鑰數量超出允許的數量(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的主要功能, https://firebaseremoteconfig.googleapis.comhttps://firebaseremoteconfig.googleapis.com 。有關詳細信息,請參見API參考

獲取訪問令牌以認證和授權API請求

Firebase項目支持Google 服務帳戶 ,您可以使用這些帳戶從應用服務器或受信任的環境中調用Firebase服務器API。如果要在本地開發代碼或在本地部署應用程序,則可以使用通過此服務帳戶獲得的憑據來授權服務器請求。

要驗證服務帳戶並授權其訪問Firebase服務,您必須生成JSON格式的私鑰文件。

為您的服務帳戶生成私鑰文件:

  1. 在Firebase控制台中,打開“設置”>“ 服務帳戶”

  2. 單擊生成新私鑰 ,然後單擊生成密鑰進行確認。

  3. 安全地存儲包含密鑰的JSON文件。

通過服務帳戶進行授權時,有兩種選擇可為您的應用程序提供憑據。您可以設置GOOGLE_APPLICATION_CREDENTIALS環境變量,也可以將路徑顯式傳遞給代碼中的服務帳戶密鑰。第一個選項更安全,強烈建議使用。

設置環境變量:

將環境變量GOOGLE_APPLICATION_CREDENTIALS設置為包含您的服務帳戶密鑰的JSON文件的文件路徑。該變量僅適用於當前的Shell會話,因此,如果您打開一個新的會話,請再次設置該變量。

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憑據與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 Web令牌

蟒蛇

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

訪問令牌過期後,將自動調用令牌刷新方法以檢索更新的訪問令牌。

要授權訪問遠程配置,請請求範圍https://www.googleapis.com/auth/firebase.remoteconfig

修改遠程配置模板

使用Remote Config模板時,請記住它們是版本化的,並且每個版本從創建之日到您用更新替換之時的生命週期都是有限的:90天,總共存儲300個版本。有關更多信息,請參見模板和版本控制

獲取當前的遠程配置模板

您可以使用後端API以JSON格式獲取Remote Config模板的當前活動版本。使用以下命令:

捲曲

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和帶有後綴-0的已更新etag表示您的更新已成功驗證。任何非200響應都表示JSON數據包含在發布之前必須糾正的錯誤。

更新遠程配置模板

檢索模板並用所需的更新修改了JSON內容後,就可以發布它了。如本節所述發布模板,將整個現有配置模板替換為更新的文件,並且為新的活動模板分配的版本號比其替換的模板大一個數字。

如有必要,您可以使用REST API 回滾到以前的版本 。為了減輕更新錯誤的風險,您可以在發布之前進行驗證

捲曲

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 ,用於版本控制。

Remote Config後端API提供了幾種條件和比較運算符,您可以使用它們來更改應用程序的行為和外觀。要了解有關條件和這些條件支持的運算符的更多信息,請參閱條件表達式參考

HTTP錯誤代碼

狀態碼含義
200 成功更新
400 發生驗證錯誤。例如,包含超過允許數量的鍵的請求(2000)將返回400(錯誤請求),並顯示錯誤消息, Param count too large 。此外,此HTTPS狀態代碼可能在以下兩種情況下發生:
  • 由於自上次檢索ETag值以來已更新了一組值和條件,因此發生版本不匹配錯誤。要解決此問題,您應該使用GET命令獲取新模板和ETag值,更新模板,然後使用該模板和新ETag值提交。
  • 在未指定If-Match標頭的情況下發出了PUT命令(更新遠程配置模板請求)。
401 發生授權錯誤(未提供訪問令牌,或者尚未在Cloud Developer Console中將Firebase Remote Config REST API添加到您的項目中)
403 發生驗證錯誤(提供了錯誤的訪問令牌)
500 發生了內部錯誤。如果發生此錯誤,請提交Firebase支持票證

狀態碼200表示遠程配置模板(項目的參數,值和條件)已更新,並且現在可供使用該項目的應用程序使用。其他狀態代碼表示以前存在的“遠程配置”模板仍然有效。

在您向模板提交更新後,轉到Firebase控制台以驗證您的更改是否按預期顯示。這很關鍵,因為條件的順序會影響它們的評估方式(第一個評估為true條件生效)。

ETag的使用和強制更新

遠程配置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的更新。如果多個客戶端正在更新遠程配置模板,則使用該模板。使用API​​的多個客戶端或API客戶端和Firebase控制台用戶的更新衝突可能會發生這種衝突。

有關管理Remote Config模板版本的指導,請參閱Remote Config模板和版本控制