本文檔介紹如何以程式設計方式讀取和修改一組 JSON 格式的參數和條件(稱為「遠端設定範本」) 。這允許您在客戶端應用程式可以使用客戶端庫取得的後端進行範本變更。
使用本指南中所述的遠端設定 REST API或管理 SDK ,您可以繞過在 Firebase 控制台中管理模板,直接將遠端設定變更整合到您自己的流程中。例如,使用遠端配置後端 API,您可以:
- 安排遠端配置更新。透過將 API 呼叫與 cron 作業結合使用,您可以定期變更遠端配置值。
- 批次匯入配置值,以便有效地從您自己的專有系統過渡到 Firebase 遠端配置。
將 Remote Config 與 Cloud Functions for Firebase 結合使用,根據伺服器端發生的事件變更應用程式中的值。例如,您可以使用遠端設定來推廣應用程式中的新功能,然後在檢測到有足夠多的人與新功能互動後自動關閉該推廣。
本指南的以下部分介紹了您可以使用遠端設定後端 API 執行的操作。若要查看透過 REST API 執行這些任務的一些程式碼,請參閱下列範例應用程式之一:
- Firebase 遠端設定 REST API Java 快速入門
- Firebase 遠端設定 REST API Node.js 快速入門
- Firebase 遠端設定 REST API Python 快速入門
使用 Firebase 管理 SDK 修改遠端配置
Admin SDK 是一組伺服器庫,可讓您從特權環境與 Firebase 進行互動。除了執行遠端設定更新之外,Admin SDK 還可以產生和驗證 Firebase 身份驗證令牌、從即時資料庫讀取和寫入等。要了解有關 Admin SDK 先決條件和設定的更多信息,請參閱將 Firebase Admin SDK 添加到您的伺服器。
在典型的遠端設定流程中,您可能會取得目前模板,修改某些參數或參數群組和條件,驗證模板,然後發布它。在進行這些 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);
取得目前遠端配置模板
使用遠端配置模板時,請記住它們是有版本的,並且每個版本從創建時間到用更新替換它的時間都有有限的生命週期:90 天,存儲版本總數限制為 300 個。有關詳細信息,請參閱模板和版本控制。
您可以使用後端 API 取得 JSON 格式的遠端設定範本的目前活動版本。
在 A/B 測試實驗中專門作為變體創建的參數和參數值不包含在導出的模板中。
取得範本:
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());
修改遠端配置參數
您可以透過程式設計方式修改和新增遠端配置參數和參數組。例如,對於名為「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 可讓您建立新參數和參數群組,或修改預設值、條件值和描述。在所有情況下,您都必須在修改後明確發布範本。
修改遠端配置條件
您可以透過程式設計方式修改和新增遠端設定條件和條件值。例如,要新增條件:
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 提供了多個條件和比較運算符,您可以使用它們來更改應用程式的行為和外觀。要了解有關條件以及這些條件支援的運算符的更多信息,請參閱條件表達式參考。
驗證遠端配置模板
或者,您可以在發布更新之前驗證更新,如下所示:
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()); } }
此驗證過程會檢查錯誤,例如參數和條件的重複鍵、無效的條件名稱或不存在的條件或格式錯誤的 etag。例如,包含超過允許數量的按鍵(2000)的請求將傳回錯誤訊息Param count too large
。
發布遠端配置模板
檢索模板並使用所需的更新對其進行修改後,您就可以發布它。依照本節所述發布範本會將整個現有配置範本替換為更新的文件,並且為新的活動範本分配比其替換的範本大 1 的版本號。
如有必要,您可以使用REST API回滾到先前的版本。為了降低更新中出現錯誤的風險,您可以在發布之前進行驗證。
遠端配置個人化設定和條件包含在下載的範本中,因此在嘗試發佈到其他項目時,請務必注意以下限制:
個性化設定無法從一個項目匯入到另一個項目。
例如,如果您在專案中啟用了個人化設定並下載並編輯了模板,則可以將其發佈到同一項目,但無法將其發佈到其他項目,除非從模板中刪除個人化設定。
條件可以從一個項目匯入到另一個項目,但請注意,任何特定的條件值(例如應用程式 ID 或受眾)在發布之前都應存在於目標項目中。
例如,如果您有一個遠端設定參數,該參數使用指定平台值
iOS
的條件,則可以將範本發佈到另一個項目,因為任何項目的平台值都是相同的。但是,如果它包含依賴目標專案中不存在的特定應用程式 ID 或使用者受眾的條件,則驗證將失敗。如果您計劃發布的範本包含依賴 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 修改遠端配置
本節介紹https://firebaseremoteconfig.googleapis.com
上的遠端設定 REST API 的主要功能。有關完整詳細信息,請參閱API 參考。
取得存取權杖以對 API 請求進行身份驗證和授權
Firebase 專案支援 Google服務帳戶,您可以使用它從應用程式伺服器或受信任的環境中呼叫 Firebase 伺服器 API。如果您在本機開發程式碼或在本機部署應用程序,則可以使用透過此服務帳戶取得的憑證來授權伺服器請求。
若要對服務帳戶進行驗證並授權其存取 Firebase 服務,您必須產生 JSON 格式的私鑰檔案。
要為您的服務帳戶產生私鑰檔案:
在 Firebase 控制台中,開啟設定 >服務帳戶。
按一下「產生新私鑰」 ,然後按一下「產生金鑰」進行確認。
安全地儲存包含金鑰的 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 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 Web 令牌或 JWT 對請求進行身份驗證。有關更多信息,請參閱JSON Web 令牌。
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
爪哇
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();
}
存取令牌過期後,會自動呼叫令牌刷新方法以檢索更新的存取令牌。
若要授權存取遠端配置,請請求範圍https://www.googleapis.com/auth/firebase.remoteconfig
。
修改遠端配置模板
使用遠端配置模板時,請記住它們是有版本的,並且每個版本從創建時間到用更新替換它的時間都有有限的生命週期:90 天,存儲版本總數限制為 300 個。有關詳細信息,請參閱模板和版本控制。
取得目前遠端配置模板
您可以使用後端 API 取得 JSON 格式的遠端設定範本的目前活動版本。
在 A/B 測試實驗中專門作為變體創建的參數和參數值不包含在導出的模板中。
使用以下命令:
捲曲
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 內容後,您就可以發布它。依照本節所述發布範本會將整個現有配置範本替換為更新的文件,並且為新的活動範本分配比其替換的範本大 1 的版本號。
如有必要,您可以使用REST API回滾到先前的版本。為了降低更新中出現錯誤的風險,您可以在發布之前進行驗證。
遠端配置個人化設定和條件包含在下載的範本中,因此在嘗試發佈到其他項目時,請務必注意以下限制:
個性化設定無法從一個項目匯入到另一個項目。
例如,如果您在專案中啟用了個人化設定並下載並編輯了模板,則可以將其發佈到同一項目,但無法將其發佈到其他項目,除非從模板中刪除個人化設定。
條件可以從一個項目匯入到另一個項目,但請注意,任何特定的條件值(例如應用程式 ID 或受眾)在發布之前都應存在於目標項目中。
例如,如果您有一個遠端設定參數,該參數使用指定平台值
iOS
的條件,則可以將範本發佈到另一個項目,因為任何項目的平台值都是相同的。但是,如果它包含依賴目標專案中不存在的特定應用程式 ID 或使用者受眾的條件,則驗證將失敗。如果您計劃發布的範本包含依賴 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 ,並在下一個PUT
命令的回應標頭中提供更新的 ETag。
修改遠端配置條件
您可以透過程式設計方式修改遠端配置條件和條件值。使用 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 提供了多個條件和比較運算符,您可以使用它們來更改應用程式的行為和外觀。要了解有關條件以及這些條件支援的運算符的更多信息,請參閱條件表達式參考。
HTTP 錯誤代碼
狀態碼 | 意義 |
---|---|
200 | 成功更新 |
400 | 發生驗證錯誤。例如,包含超過允許數量的按鍵(2000)的請求將傳回 400(錯誤請求),並顯示錯誤訊息Param count too large 。此外,此 HTTPS 狀態碼可能會在以下兩種情況下出現:
|
401 | 發生授權錯誤(未提供存取權杖或 Firebase Remote Config REST API 尚未新增至 Cloud Developer Console 中的專案) |
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
指令一起使用。
您可以透過強制更新遠端設定範本來規避 ETag 及其提供的保護,如下所示: If-Match: *
但是,不建議使用此方法,因為它有導致遠端設定更新遺失的風險範本(如果多個客戶端正在更新遠端配置模板)。使用 API 的多個用戶端,或 API 用戶端和 Firebase 控制台使用者的更新衝突時,可能會發生這種衝突。
有關管理遠端配置範本版本的指南,請參閱遠端設定範本和版本控制。