コンソールへ移動

Remote Config REST API を使用する

このドキュメントでは、Remote Config REST API を使用して、JSON 形式のパラメータと条件からなるセット(Remote Config テンプレートと呼ばれる)を読み取り、変更する方法について説明します。これにより、テンプレートをプログラムで管理し、クライアント アプリがクライアント ライブラリを使用して取得可能なバックエンドでテンプレートの変更を行うことができます。

この API を使用すると、Remote Config コンソールでのテンプレートの管理を迂回して、Remote Config の変更を独自のプロセスに直接統合できます。たとえば、Remote Config REST API を使用すると、次のことができます。

  • Remote Config 更新のスケジュール。cron ジョブと一緒に REST API を使用することにより、Remote Config の値を定期的に変更することができます。
  • 独自のシステムから Firebase Remote Config に効率的に移行するための構成値の一括インポート
  • サーバー側で発生したイベントに基づいてアプリ内の値を変更する Cloud Functions for Firebase と Remote Config の使用。たとえば、Remote Config を使用してアプリ内の新しい機能をプロモートした後、十分な人数の担当者が新しい機能に慣れた段階で、そのプロモーションを自動的にオフにすることができます。

このガイドの以降のセクションでは、Remote Config REST API を使い始めるために必要な手順について詳しく説明します。コードの実行と検査のみを行う場合は、以下のいずれかのサンプルアプリで Remote Config REST API の使用例をご覧ください。

Remote Config REST API の使用を開始する

このセクションでは、API を使用して Remote Config テンプレートを取得および変更する方法について順を追って説明します。

ステップ 1: Firebase コンソールに値を設定する

通常は、最初に Firebase コンソールで値を設定します。このガイドでは、iOS または Android 用の Remote Config クイックスタート サンプルアプリがセットアップされているものとします。このアプリでは、次の 2 つのパラメータを Firebase コンソールに追加する必要があるだけです。

パラメータキー デフォルト値 備考
welcome_message Welcome to this sample app 別のウェルカム メッセージを使用するように変更します。
welcome_message_caps false ウェルカム メッセージをすべて大文字で表示する場合は true に設定します。

ステップ 2: API リクエストを認証して承認するためのアクセス トークンを取得する

Firebase プロジェクトでは Google サービス アカウントがサポートされています。これを使用して、アプリサーバーまたは信頼できる環境から Firebase サーバー API を呼び出せます。コードをローカルで開発しているか、またはアプリケーションをオンプレミスでデプロイしている場合、このサービス アカウントで取得した認証情報を使用してサーバー リクエストを承認できます。

サービス アカウントを認証して Firebase サービスへのアクセスを承認するには、秘密鍵ファイルを JSON 形式で生成する必要があります。

サービス アカウント用の秘密鍵ファイルを生成するには:

  1. Firebase コンソールで、[設定] > [サービス アカウント] を開きます。

  2. [新しい秘密鍵の生成] をクリックし、[キーを生成] をクリックして確定します。

  3. キーを含む JSON ファイルを安全に保管します。

サービス アカウントを介して承認する場合、アプリケーションの認証情報を指定するには 2 つの選択肢があります。GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定することも、サービス アカウント キーへのパスをコードで明示的に渡すこともできます。1 つ目の選択肢のほうが安全であるため、強くおすすめします。

環境変数を設定するには:

環境変数 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)は認証情報を暗黙的に判別できるようになり、Google 以外の環境でテストするか実行するときに、サービス アカウントの認証情報を使用できます。

次に示すように、有効期間の短い OAuth 2.0 アクセス トークンを取得するために、適切な言語の Google API クライアント ライブラリと一緒に Firebase 認証情報を使用します。

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 へのアクセスを承認するには、スコープ https://www.googleapis.com/auth/firebase.remoteconfig をリクエストします。

ステップ 3: API を使用して Remote Config サービスから JSON を取得する

次に、API を使用して Remote Config テンプレートの現在のアクティブなバージョンを JSON 形式で取得します。それには、次のコマンドを使用します。<my-project-id> は実際のプロジェクト ID に置き換えてください(プロジェクト ID は Firebase コンソール設定ペインで確認できます)。

curl コマンド:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

このコマンドは、JSON ペイロードを 1 つのファイルに出力し、ヘッダー(Etag を含む)を別のファイルに出力します。

未加工の HTTP リクエスト:

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

この API 呼び出しは、後続のリクエストで使用する ETag を含む個別のヘッダーとともに、次の JSON を返します。返される JSON の例を次に示します。

{
  "parameters":[
    {
      "key":"welcome_message",
      "value_options":[
        {
          "value":"Welcome to this sample app"
        }
      ]
    },
    {
      "key":"welcome_message_caps",
      "value_options":[
        {
          "value":"false"
        }
      ]
    }
  ],
  "version":{
    "version_number": "42",
    "update_time":"2018-05-11T18:46:40Z",
    "update_user":{
      "name":"Jane Developer",
      "email":"jane@developer.org",
      "imageUrl":"http://image.google.com/path-to-profile-photo-for-jane"
    },
    "description":"Adding welcome messages",
    "update_origin":"CONSOLE",
    "update_type":"INCREMENTAL_UPDATE"
  }
}

ステップ 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: Remote Config サービスのデータに置き換わる JSON データを公開する

Remote Config テンプレートを更新するための JSON ファイルを作成したら、上記の JSON を次のコマンドに追加して公開できます(既存の構成を置き換えます)。このオペレーションでは、既存の構成テンプレート全体が更新後のファイルに置き換えられます。新しいアクティブなテンプレートには、置き換え前のテンプレートよりも 1 つ大きいバージョン番号が割り当てられます。

curl コマンドでは、「@」文字に続けてファイル名を使用することで、コンテンツを指定できます。

必要に応じて、前のバージョンにロールバックできます。更新中のエラーのリスクを軽減するために、公開前に検証できます。

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

未加工の 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 コマンドのレスポンス ヘッダーに入力されます。

公開前に検証する

必要に応じて、公開リクエストに URL パラメータ ?validate_only=true を追加することにより、公開前に更新を検証できます。レスポンスで、ステータス コード 200 と接尾辞が -0 の更新された etag は、更新が正常に検証されたことを意味します。200 以外のレスポンスは、JSON データに、公開前に訂正しなければならないエラーが含まれていることを示します。

エラーコード

ステータス コード 意味
200 正常に更新されました。
400 検証エラーが発生しました。たとえば、許可されるキー数(2,000)を超えるキーを含むリクエストにより、400(Bad Request)およびエラー メッセージ「 Param count too large」が返されます。
401 許可エラーが発生しました(アクセス トークンが指定されていないか、Firebase Remote Config REST API が Cloud Developer Console 内のプロジェクトにまだ追加されていません)。
403 認証エラーが発生しました(誤ったアクセス トークンが提供された)。
409 この HTTPS ステータス コードは、2 つの状況で発生します。
  • 最後に ETag 値を取得した後に値と条件のセットが更新されているため、バージョンの不一致エラーが発生した。このエラーを解決するには、GET コマンドを使用して新しいテンプレートと ETag 値を取得し、テンプレートを更新してから、そのテンプレートと新しい ETag 値を使用して送信する必要があります。
  • If-Match ヘッダーを指定せずに PUT コマンド(Remote Config テンプレートの更新リクエスト)が行われた。
500 内部エラーが発生しました。このエラーが発生した場合は、Firebase サポート チケットを申請してください

ステータス コード 200 の場合、Remote Config テンプレート(プロジェクトのパラメータ、値、および条件)がすでに更新され、このプロジェクトを使用するアプリで利用できる状態になっています。その他のステータス コードの場合は、これまでの Remote Config テンプレートが引き続き使用されます。

テンプレートに更新を送信した後、Firebase コンソールに移動して、意図したとおりに変更が表示されることを確認します。条件の順序は条件の評価内容に影響するため、ここで確認しておくことが重要です(最初に true と評価された条件が適用されます)。

ETag の使用と強制的な更新

Remote Config REST API では、エンティティ タグ(ETag)を使用して、競合状態やリソースの更新の重複を防ぎます。ETag の詳細については、ETag-HTTP をご覧ください。

最新の GET コマンドで提供された ETag をキャッシュし、PUT コマンドを発行するときに If-Match リクエスト ヘッダーでその ETag 値を使用することをおすすめします。PUT コマンドの結果が HTTPS ステータス コード 409 の場合、新しい GET コマンドを発行して、次の PUT コマンドで使用する新しい ETag とテンプレートを取得する必要があります。

ETag および ETag が提供する保護を回避するには、If-Match: * という方法で Remote Config テンプレートを強制的に更新できます。ただし、複数のクライアントが Remote Config テンプレートを更新する場合は、Remote Config テンプレートの更新が失われる危険性があるため、この方法はおすすめしません。こうした競合は、API を使用する複数のクライアント、または API クライアントおよび Firebase コンソール ユーザーからの更新の競合によって発生する可能性があります。

Remote Config テンプレートのバージョン管理の指針については、Remote Config テンプレートとバージョニングをご覧ください。