透過程式輔助方式修改遠端設定

本文件說明如何透過程式讀取 並修改 JSON 格式的參數和條件組合 (稱為 遠端設定範本。這樣一來， 您就能輕鬆變更範本 供用戶端應用程式透過用戶端程式庫擷取。

使用 Remote Config REST API 或 您可以透過本指南說明的 Admin SDK 在 Firebase 控制台中管理範本 遠端設定變更到您自己的程序。舉例來說 遠端設定後端 API 可讓您：

• 安排遠端設定更新時間。將 API 呼叫與 Cron 工作搭配使用，即可定期變更遠端設定值。
• 批次匯入設定值，以便有效率地從自有系統轉換至 Firebase 遠端設定。

• 搭配使用遠端設定與 Cloud Functions for Firebase，根據在伺服器端發生的事件變更應用程式中的值。例如，您可以使用遠端設定來宣傳應用程式中的新功能，等偵測到與新功能互動的人數達到一定人數後，即自動關閉該促銷活動。

  

本指南的以下章節說明您可以使用哪些作業 遠端設定後端 API如要查看執行這些元件的程式碼 或是透過 REST API 讀取工作，查看下列其中一個範例應用程式：

• Firebase 遠端設定 REST API Java 快速入門導覽課程
• Firebase 遠端設定 REST API Node.js 快速入門導覽課程
• Firebase 遠端設定 REST API Python 快速入門導覽課程

使用 Firebase Admin 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();

Java

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

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

提示： 您也可以直接從這裡下載目前的遠端設定範本： 也可前往 Firebase 控制台瞭解詳情： 下載並發布遠端設定範本。

修改遠端設定參數

您可以透過程式輔助方式修改及新增遠端設定參數。 參數群組例如，前往名為「new_menu」的現有參數群組 可以加入參數來控制季節性資訊的顯示方式：

Node.js

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

Java

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

Java

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

無論如何，您都必須在範本後方 進行修改。

注意： 由於每個值本來都是 Firebase 遠端設定的字串， 布林值輸入為「true」和「false」這些模型的類型正確轉換為 布林值。getBoolean「正確」或「False」或「1」或「0」是 不正確的 Firebase 遠端設定布林值表示法。

遠端設定後端 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);
      });
}

Java

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。

發布遠端設定範本

擷取範本並按照需求修改 發布更新按照本文說明發布範本 部分會將整個現有設定範本替換成更新後的檔案，且 新的有效範本獲派的版本號碼大於 取而代之

如有需要，您可以使用 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);
      });
}

Java

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

提示： 您也可以直接透過以下網址發布遠端設定範本： 也可前往 Firebase 控制台瞭解詳情： 下載並發布遠端設定範本。

使用 REST API 修改遠端設定

本節將說明 位於 https://firebaseremoteconfig.googleapis.com 的 Remote Config REST API。 詳情請參閱 API 參考資料。

取得存取權杖，以便驗證和授權 API 要求

Firebase 專案支援 Google 服務帳戶 可用來呼叫 Firebase 伺服器 API。如果您正在開發 或在地端部署環境部署應用程式 您就能使用取得 透過這個服務帳戶授權伺服器要求

驗證及授權服務帳戶 您必須先產生 JSON 格式的私密金鑰檔案，才能存取 Firebase 服務 格式。

如何產生服務帳戶的私密金鑰檔案：

1. 在 Firebase 控制台中開啟 設定 >服務帳戶。

2. 按一下「產生新私密金鑰」，然後按一下「產生金鑰」加以確認。

3. 安全地儲存包含金鑰的 JSON 檔案。

注意： 您用來產生憑證的服務帳戶必須具有 Firebase 遠端設定管理員角色所包含的權限。如果您按照上述步驟操作後，使用預設值 Firebase Admin SDK 服務帳戶 (必要角色) 包含遠端設定權限。如果你想要更新目標對象 透過 REST API 存取使用者屬性條件，您需要將 firebaseanalytics.resources.googleAnalyticsReadAndAnalyze 權限新增至 自訂角色

透過服務帳戶授權時，您有兩種方式可以提供 將憑證傳送至您的應用程式您可以設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數，或者也可以 在程式碼中明確傳送服務帳戶金鑰的路徑。 第一種安全性較高，強烈建議使用。

如何設定環境變數：

設定環境變數 GOOGLE_APPLICATION_CREDENTIALS 指向包含服務帳戶金鑰的 JSON 檔案路徑。 此變數僅適用於您目前的殼層工作階段，所以如果您開啟 新的工作階段，請再次設定變數。

Linux 或 macOS

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

Windows

使用 PowerShell：

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

完成上述步驟後，應用程式預設憑證 (ADC) 系統會以隱含方式判斷您的憑證，方便您使用 Service 在非 Google 環境中測試或執行時，就使用服務帳戶憑證

搭配使用 Firebase 憑證與 Google 驗證程式庫 ，以擷取慣用語言的 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);
      });
}
index.js

在此範例中，Google API 用戶端程式庫使用 JSON Web Token 或 JWT若需更多資訊，請參閲 JSON 網路權杖。

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
configure.py

Java

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

存取權杖到期後，系統會呼叫憑證更新方法 自動擷取更新過的存取權杖。

如要授權遠端設定的存取權，請要求範圍 https://www.googleapis.com/auth/firebase.remoteconfig。

修改遠端設定範本

使用遠端設定範本時 且每個版本的生命週期均自 ，有 90 天時間限制。 共 300 個儲存版本請參閱範本和版本管理 瞭解詳情

取得目前的遠端設定範本

您可以使用後端 API 取得目前有效版本的 JSON 格式的遠端設定範本。

專為以下項目建立的參數和參數值： 匯出的範本中沒有 A/B 測試實驗。

請使用以下指令：

cURL

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

注意： 由於這是讀取要求，因此會傳回 ETag ，但不會修改。 即可。

這個 API 呼叫會傳回下列 JSON，以及一個獨立標頭 包含您用於 後續要求

驗證遠端設定範本

你也可以選擇先驗證更新內容再發布。 透過附加的功能來驗證範本更新 網址參數：?validate_only=true。 回應中為狀態碼 200，並已更新 etag，後方加上 -0 代表您的更新已順利完成驗證。任何非 200 回應 表示 JSON 資料包含錯誤，您必須先予以修正。 以及發布內容

更新遠端設定範本

已擷取範本，並按照需求修改 JSON 內容 發布更新按照本文說明發布範本 部分會將整個現有設定範本替換成更新後的檔案，且 新的有效範本獲派的版本號碼大於 取而代之

如有需要，您可以使用 REST API 復原至先前版本。 如要降低更新發生錯誤的風險，您可以 在發布前進行驗證。

遠端設定個人化功能和條件已納入 下載範本，因此請務必留意下列事項 發布至其他專案的限制：

• 無法將個人化作業從專案匯入專案。

  舉例來說，如果專案啟用了個人化功能， 下載並編輯範本 就能將範本發布在 但無法發布至其他專案 套用範本的個人化設定

• 條件可從專案匯入至專案，但請注意 特定條件值 (例如應用程式 ID 或目標對象) 應存在於 在發布前就先選取目標專案

  舉例來說，如果您有一個使用條件的遠端設定參數 指定平台值 iOS 時，範本可發布至 其他專案的平台值都一樣。 但是，如果條件需要使用特定應用程式 ID 或使用者， 如果目標對像不存在於目標專案中，驗證就會失敗。

• 如果您要發布的範本包含 Google Analytics，您必須在目標中啟用 Analytics 專案。

cURL

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

修改遠端設定條件

您可以透過程式輔助的方式修改遠端設定條件和條件 輕鬆分配獎金使用 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 為 但為了管控版本

注意： 由於每個值本來都是 Firebase 遠端設定的字串， 布林值輸入為「true」和「false」這些模型的類型正確轉換為 布林值。getBoolean「正確」或「False」或「1」或「0」是 不正確的 Firebase 遠端設定布林值表示法。

遠端設定後端 API 提供多種條件並進行比較 可用來變更應用程式行為和外觀的運算子。目的地： 進一步瞭解這些條件支援的運算子和 請參閱條件運算式參考資料。

HTTP 錯誤代碼

狀態碼	意義
200	更新成功
400	發生驗證錯誤，舉例來說，如果要求包含的 允許的金鑰數量 (2000 個) 會與 300 個 (Bad Request) 傳回 錯誤訊息：Param count too large。 且發生以下兩種情況時，也可能會出現 HTTPS 狀態碼： 自您上次擷取 ETag 值後已更新一組值和條件，因此發生版本不符錯誤。如要解決這個問題，請使用 GET 指令取得新的範本和 ETag 值、更新範本，然後使用該範本和即時的 ETag 值提交內容。 完成 PUT 指令 (更新遠端設定範本要求)，但未指定 If-Match 標頭。
401	發生授權錯誤 (未提供存取權杖或 Firebase Remote Config REST API 尚未新增至以下項目的專案中： Cloud Developer Console)
403	發生驗證錯誤 (提供的存取權杖有誤)
500	發生內部錯誤，如果發生這項錯誤 提交 Firebase 支援單

狀態碼 200 表示遠端設定範本 (參數、值) 條款及細則) 已更新，現已開放應用程式使用 使用這項專案的專案其他狀態碼表示遠端設定 先前保留的範本依然有效。

提交範本的更新內容後，請前往 Firebase 控制台 確認您的變更能正常顯示。這點非常重要 條件的順序會影響評估方式 (第一個條件 評估 true 生效)。

ETag 使用與強制更新

Remote Config REST API 會使用實體標記 (ETag) 防止競爭狀況 以及對資源進行重疊的更新如要進一步瞭解 ETag，請參閱： ETag - HTTP。

如為 REST API，Google 建議您快取 最新 GET 指令提供的 ETag，並使用該 ETag 值 傳送至 If-Match 要求標頭中。PUT如果你的PUT 指令會產生 HTTPS 狀態碼 409，建議您發出最新的 GET 這個指令取得新的 ETag 和範本，並用於下一個 PUT 指令。

注意： 我們目前已發現 ETag 無法正確傳回 請求並未指定壓縮類型的情況。目前它為 必須在所有標頭中加入 Accept-Encoding: gzip 或同等標題 要求。

您可以透過下列方式規避 ETag 和其提供的保護： 強制更新遠端設定範本，如下所示：If-Match: * 不過，我們不建議這麼做，因為這麼做可能會導致 更新遠端設定範本時 遠端設定範本。這類衝突可能與多個 或與 API 用戶端衝突的更新 Firebase 控制台使用者。

如需管理遠端設定範本版本的指引，請參閱 遠端設定範本和版本管理。