Buka konsol

Menggunakan REST API Remote Config

Dokumen ini menjelaskan bagaimana Anda dapat menggunakan REST API Remote Config untuk membaca dan memodifikasi seperangkat parameter dan condition berformat JSON yang dikenal sebagai template Remote Config. Ini memungkinkan Anda untuk mengelola template secara terprogram, melakukan perubahan template di backend yang dapat diambil oleh aplikasi klien dengan menggunakan library klien.

Dengan menggunakan API ini, Anda dapat melompati langkah pengelolaan template di konsol Remote Config dan langsung mengintegrasikan perubahan Remote Config ke dalam proses Anda sendiri. Misalnya, dengan REST API Remote Config, Anda bisa:

  • Menjadwalkan update Remote Config. Dengan menggunakan REST API secara bersamaan dengan cron job, Anda dapat mengubah nilai Remote Config sesuai jadwal berkala.
  • Melakukan batch import untuk nilai konfigurasi agar dapat melakukan transisi secara efisien dari sistem yang Anda miliki ke Firebase Remote Config.
  • Gunakan Remote Config dengan Cloud Functions for Firebase untuk mengubah nilai di aplikasi Anda berdasarkan peristiwa yang terjadi di sisi server. Misalnya, Anda dapat menggunakan Remote Config untuk mempromosikan fitur baru di aplikasi Anda, lalu menonaktifkan promosi itu secara otomatis begitu Anda mendeteksi cukup banyak orang yang berinteraksi dengan fitur baru ini.

Bagian panduan berikut menjelaskan langkah-langkah yang diperlukan untuk memulai menggunakan REST API Remote Config. Jika Anda hanya ingin menjalankan kode dan memeriksanya, lihat salah satu contoh aplikasi yang mendemonstrasikan penggunaan REST API Remote Config:

Mulai menggunakan REST API Remore Config

Langkah-langkah di bagian ini menjelaskan cara mendapatkan dan memodifikasi template Remote Config dengan API.

Langkah 1: Tetapkan nilai di Firebase console

Biasanya, Anda akan mulai dengan menetapkan nilai di Firebase console. Untuk keperluan panduan ini, anggaplah Anda telah menyiapkan contoh aplikasi Quickstart Remote Config untuk iOS atau Android. Untuk aplikasi ini, Anda hanya perlu menambahkan dua parameter berikut ke Firebase console:

Kunci parameter Nilai Default Catatan
welcome_message Selamat datang di aplikasi contoh ini Ubahlah untuk menggunakan pesan sambutan yang berbeda.
welcome_message_caps false Setel ke true agar pesan sambutan ditampilkan dalam huruf kapital semua.

Langkah 2: Dapatkan token akses untuk mengautentikasi dan memberi otorisasi permintaan API

Project Firebase mendukung akun layanan Google, yang dapat Anda gunakan untuk memanggil API server Firebase dari server aplikasi atau lingkungan tepercaya. Jika Anda mengembangkan kode secara lokal atau menerapkan aplikasi di lokasi lokal, Anda dapat menggunakan kredensial yang diperoleh melalui akun layanan ini untuk mengotorisasi permintaan server.

Untuk mengautentikasi akun layanan dan memberinya akses ke layanan Firebase, Anda harus membuat file kunci pribadi dalam format JSON.

Untuk membuat file kunci pribadi untuk akun layanan Anda:

  1. Di Firebase console, buka Setelan > Akun Layanan.

  2. Klik Buat Kunci Pribadi Baru, lalu konfirmasikan dengan mengklik Buat Kunci.

  3. Simpan dengan aman file JSON yang memuat kunci tersebut.

Saat mengotorisasi melalui akun layanan, Anda diberikan dua pilihan untuk memberikan kredensial ke aplikasi. Anda dapat menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, atau secara eksplisit meneruskan lokasi ke kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat disarankan.

Untuk menyetel variabel lingkungan:

Setel variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke lokasi file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini, jadi jika Anda membuka sesi baru, tetapkan variabel lagi.

Linux atau macOS

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

Windows

Dengan PowerShell:

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

Setelah Anda menyelesaikan langkah-langkah di atas, Kredensial Default Aplikasi (ADC) secara implisit dapat menentukan kredensial Anda sehingga Anda dapat menggunakan kredensial akun layanan saat menguji atau menjalankan di lingkungan non-Google.

Gunakan kredensial Firebase Anda beserta Library Klien Google API untuk bahasa pilihan Anda saat mengambil token akses OAuth 2.0 yang berumur pendek:

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

Setelah masa berlaku token akses berakhir, metode refresh token akan otomatis dipanggil untuk mengambil token yang telah diperbarui.

Untuk memberikan akses ke Remote Config, mintalah cakupan https://www.googleapis.com/auth/firebase.remoteconfig.

Langkah 3: Dapatkan JSON dari layanan Remote Config dengan API

Selanjutnya, Anda dapat menggunakan API untuk mendapatkan template Remote Config versi aktif saat ini dalam format JSON. Lakukan langkah ini dengan menggunakan perintah berikut, yang akan menggantikan project ID Anda sendiri (tersedia di panel Setelan Firebase Console) untuk <my-project-id>:

Perintah curl:

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

Perintah ini menampilkan payload JSON ke sebuah file dan headernya (termasuk Etag) ke file terpisah.

Permintaan HTTP mentah:

Host: firebaseremoteconfig.googleapis.com

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

Panggilan API ini menampilkan JSON berikut ini beserta header terpisah yang menyertakan ETag yang untuk digunakan pada permintaan berikutnya. Contoh berikut menunjukkan JSON yang ditampilkan:

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

Langkah 4: Tambahkan condition ke data JSON

Selanjutnya, tambahkan beberapa condition dan nilai condition yang akan mengupdate aplikasi sampel untuk:

  • Menampilkan pesan yang sedikit berbeda (dengan menambahkan kata "baru") ke 10% pengguna.
  • Menampilkan pesan dalam huruf besar untuk pengguna di Amerika Serikat atau Inggris.

Untuk memperluas JSON dengan cara ini, buat file yang berisi berikut ini:

{
  "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 yang ditunjukkan di atas pertama-tama menetapkan serangkaian condition, kemudian menetapkan nilai default dan parameter value berbasis condition (nilai bersyarat) untuk masing-masing parameter. Tindakan ini juga menambahkan deskripsi opsional untuk setiap elemen. Seperti komentar kode, nilai ini dapat digunakan oleh developer tetapi tidak ditampilkan dalam aplikasi. ETag juga disediakan dalam header terpisah untuk keperluan pengendalian versi.

REST API Remote Config menyediakan beberapa condition dan operator perbandingan yang dapat Anda gunakan untuk mengubah perilaku dan tampilan aplikasi Anda. Untuk mempelajari condition dan operator yang didukung untuk condition ini lebih lanjut, lihat referensi ekspresi kondisional.

Langkah 5: Publikasikan data JSON untuk mengganti data di layanan Remote Config

Setelah membuat file JSON untuk memperbarui template Remote Config, Anda dapat memublikasikannya dengan menambahkan JSON yang ditunjukkan di atas ke perintah berikut, dan menggantikannya dengan konfigurasi yang ada. Operasi ini menggantikan seluruh template konfigurasi yang ada dengan file yang telah diperbarui, dan template aktif yang baru diberi nomor versi satu angka lebih besar daripada template yang digantikannya.

Untuk perintah curl, Anda cukup menentukan isi file menggunakan karakter "@" diikuti nama file.

Jika perlu, Anda dapat melakukan rollback ke versi sebelumnya. Untuk mengurangi risiko error dalam proses pembaruan, Anda dapat memvalidasi sebelum memublikasikan.

Perintah 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

Permintaan HTTP mentah:

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

Karena ini adalah permintaan tulis, perintah ini mengubah ETag dan ETag yang sudah diperbarui akan disediakan dalam header respons pada perintah PUT berikutnya.

Memvalidasi sebelum memublikasi

Jika ingin, Anda dapat memvalidasi pembaruan sebelum memublikasikannya dengan menambahkan parameter URL ?validate_only=true. Hasilnya, kode status 200 dan etag baru dengan akhiran -0 menandakan bahwa pembaruan berhasil divalidasi. Hasil non-200 menunjukkan bahwa data JSON memuat error yang harus Anda perbaiki sebelum melakukan publikasi.

Kode error

Kode Status Arti
200 Berhasil diupdate
400 Terjadi error pada validasi. Misalnya, permintaan yang mengandung lebih dari jumlah kunci yang diizinkan -—2000—- akan menampilkan 400 (Permintaan Buruk) dengan pesan error, Param count too large.
401 Terjadi error pada otorisasi (tidak ada token akses yang diberikan atau REST API Firebase Remote Config belum ditambahkan ke project Anda di Cloud Developer Console)
403 Terjadi error pada autentikasi (token akses yang diberikan salah)
409 Kode Status HTTPS ini dapat terjadi pada 2 situasi:
  • Error pada ketidakcocokan versi terjadi karena rangkaian nilai dan condition telah diupdate sejak Anda terakhir kali mengambil nilai ETag. Untuk mengatasi ini, sebaiknya gunakan perintah GET untuk mendapatkan template dan nilai ETag baru. Setelah itu, update template, lalu kirimkan update dengan menggunakan template tersebut dan nilai ETag yang baru.
  • Perintah PUT (permintaan Update template Remote Config) dibuat tanpa menentukan header If-Match.
500 Terjadi error internal. Jika terjadi error ini, ajukan tiket bantuan Firebase

Kode status 200 berarti template Remote Config (parameter, nilai, dan condition project) telah diupdate dan sekarang tersedia untuk aplikasi yang menggunakan project ini. Kode status lainnya menunjukkan bahwa template Remote Config yang ada sebelumnya masih berlaku.

Setelah mengirimkan update ke template Anda, buka Firebase console untuk memastikan bahwa perubahan Anda muncul seperti yang diharapkan. Hal ini penting karena pengurutan condition memengaruhi bagaimana condition tersebut dievaluasi (condition pertama yang mengevaluasi ke true berlaku).

Penggunaan ETag dan update paksa

REST API Remote Config menggunakan tag entitas (ETag) untuk mencegah condition yang saling mendahului dan update yang tumpang tindih pada resource. Untuk mempelajari lebih lanjut tentang ETag, lihat ETag - HTTP.

Google menganjurkan Anda menyembunyikan ETag yang disediakan oleh perintah GET terbaru dan menggunakan nilai ETag tersebut dalam header permintaan If-Match saat mengeluarkan perintah PUT. Jika perintah PUT menghasilkan Kode Status HTTPS 409, Anda harus mengeluarkan perintah GET baru untuk memperoleh ETag dan template baru untuk digunakan dengan perintah PUT berikutnya.

Anda bisa mengakali ETag dan perlindungan yang menyertainya dengan memaksakan template Remote Config untuk diperbarui sebagai berikut: If-Match: * Namun, pendekatan ini tidak direkomendasikan karena berisiko menyebabkan hilangnya pembaruan pada template Remote Config Anda saat beberapa klien memperbarui template Remote Config tersebut. Konflik semacam ini dapat terjadi ketika beberapa klien menggunakan API, atau jika pembaruan dari klien API bertentangan dengan pembaruan dari pengguna Firebase Console.

Untuk mendapatkan panduan dalam mengelola versi template Remote Config, baca artikel Pembuatan versi dan template Remote Config.