Men-deploy ke situs Anda menggunakan REST API Hosting

REST API Firebase Hosting memungkinkan deployment terprogram dan dapat disesuaikan ke situs yang dihosting oleh Firebase. Gunakan REST API ini untuk men-deploy konten dan konfigurasi Hosting baru atau yang diperbarui.

Selain menggunakan Firebase CLI untuk deployment, Anda juga dapat menggunakan REST API Firebase Hosting untuk secara terprogram membuat version baru dari aset situs Anda, mengupload file ke versi tersebut, lalu men-deploy-nya ke situs Anda.

Misalnya, dengan REST API Firebase Hosting, Anda dapat:

  • Menjadwalkan deployment. Dengan menggunakan REST API bersamaan dengan cron job, Anda dapat mengubah konten yang dihosting oleh Firebase sesuai jadwal reguler (misalnya untuk men-deploy konten spesial versi liburan atau terkait acara).

  • Melakukan integrasi dengan alat developer. Anda bisa membuat opsi dalam alat untuk men-deploy project aplikasi web Anda ke Firebase Hosting hanya dengan sekali klik (misalnya mengklik tombol deploy dalam IDE).

  • Mengotomatiskan deployment ketika konten statis dihasilkan. Ketika suatu proses menghasilkan konten statis secara terprogram (misalnya konten buatan pengguna seperti artikel wiki atau berita), Anda dapat men-deploy konten yang dihasilkan tersebut sebagai file statis, bukan menayangkannya secara dinamis. Tindakan ini menghemat daya komputasi yang mahal dan menayangkan file dengan cara yang lebih skalabel.

Panduan ini diawali dengan penjelasan cara mengaktifkan, mengautentikasi, dan memberi otorisasi API. Selanjutnya, panduan ini akan memberikan contoh untuk membuat versi Firebase Hosting, mengupload file yang diperlukan ke versi, dan men-deploy versi tersebut.

Anda juga dapat mempelajari REST API lebih lanjut dalam dokumentasi lengkap referensi REST API Hosting.

Sebelum memulai: Mengaktifkan REST API

Anda harus mengaktifkan REST API Firebase Hosting di konsol API Google:

  1. Buka halaman Firebase Hosting API di konsol API Google.

  2. Saat diminta, pilih project Firebase Anda.

  3. Klik Enable di halaman Firebase Hosting API.

Langkah 1: 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 men-deploy aplikasi secara lokal, gunakan kredensial yang diperoleh melalui akun layanan ini untuk mengizinkan 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 Settings > Service Accounts.

  2. Klik Generate New Private Key, lalu konfirmasikan dengan mengklik Generate Key.

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

Gunakan kredensial Firebase Anda beserta Library Google Auth untuk bahasa pilihan Anda saat mengambil token akses OAuth 2.0 yang memiliki masa aktif singkat:

node.js

const {google} = require('googleapis');
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);
    });
  });
}

Dalam contoh ini, library klien Google API mengautentikasi permintaan dengan token web JSON, atau yang disebut JWT. Untuk informasi lebih lanjut, baca token web 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

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.

Langkah 2: Pastikan project Anda memiliki situs Hosting default

Sebelum melakukan deployment pertama ke Firebase Hosting, project Firebase Anda harus memiliki Hosting SITE default.

  1. Pastikan bahwa project Anda sudah memiliki situs Hosting default dengan memanggil endpoint sites.list.

    Contoh:

    Perintah cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites

    Permintaan HTTPS mentah

    Host: firebasehosting.googleapis.com

POST /v1beta1/projects/PROJECT_ID/sites HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

    • Jika salah satu situs memiliki "type": "DEFAULT_SITE", berarti project Anda sudah memiliki situs Hosting default. Lewati sisa langkah yang ada dan lanjutkan ke langkah berikutnya: Buat versi baru untuk situs Anda.

    • Jika mendapatkan array kosong, berarti Anda tidak memiliki situs Hosting default. Selesaikan sisa langkah yang ada.

  2. Tentukan SITE_ID untuk situs Hosting default Anda. Perhatikan hal berikut saat menentukan SITE_ID ini:

    • SITE_ID ini digunakan untuk membuat subdomain Firebase default:
      SITE_ID.web.app dan SITE_ID.firebaseapp.com.

    • SITE_ID memiliki persyaratan berikut:

      • Harus berupa label nama host yang valid, artinya tidak boleh berisi ., _, dll.
      • Harus terdiri dari 30 karakter atau kurang
      • Harus unik secara global dalam Firebase

    Perhatikan bahwa kami sering merekomendasikan penggunaan project ID sebagai SITE_ID untuk situs Hosting default Anda. Pelajari cara menemukan ID ini di bagian Memahami project Firebase.

  3. Buat situs Hosting default dengan memanggil endpoint sites.create menggunakan SITE_ID yang diinginkan sebagai parameter siteId.

    Contoh:

    Perintah cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID

    Permintaan HTTPS mentah

    Host: firebasehosting.googleapis.com

POST /v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

    Panggilan API untuk sites.create akan menampilkan JSON berikut:

    {
  "name": "projects/PROJECT_ID/sites/SITE_ID",
  "defaultUrl": "https://SITE_ID.web.app",
  "type": "DEFAULT_SITE"
}

Langkah 3: Buat versi baru untuk situs Anda

Panggilan API pertama Anda adalah membuat Version baru untuk situs Anda. Selanjutnya dalam panduan ini, Anda akan mengupload file ke versi ini, lalu men-deploy-nya ke situs Anda.

  1. Tentukan SITE_ID untuk situs yang menjadi tujuan deployment Anda.

  2. Panggil endpoint versions.create menggunakan SITE_ID Anda dalam panggilan.

    (Opsional) Anda juga bisa meneruskan objek konfigurasi Firebase Hosting dalam panggilan, termasuk menetapkan header yang menyimpan semua file selama jangka waktu tertentu dalam cache.

    Contoh:

    Perintah cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       -d '{
             "config": {
               "headers": [{
                 "glob": "**",
                 "headers": {
                   "Cache-Control": "max-age=1800"
                 }
               }]
             }
           }' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions

    Permintaan HTTPS mentah

    Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/versions HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 134

{
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {
        "Cache-Control": "max-age=1800"
      }
    }]
  }
}

Panggilan API untuk versions.create akan menampilkan JSON berikut:

{
  "name": "sites/SITE_ID/versions/VERSION_ID",
  "status": "CREATED",
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {
        "Cache-Control": "max-age=1800"
      }
    }]
  }
}

Respons ini berisi ID unik untuk versi baru, dalam format: sites/SITE_ID/versions/VERSION_ID. Anda akan membutuhkan ID unik ini di sepanjang panduan untuk merujuk ke versi khusus ini.

Langkah 4: Tentukan daftar file yang ingin Anda deploy

Setelah memiliki ID versi baru, Anda harus memberi tahu Firebase Hosting file mana yang ingin di-deploy pada versi baru ini.

Perhatikan bahwa Hosting memiliki batas ukuran maksimum sebesar 2 GB untuk setiap file.

API ini mengharuskan Anda mengidentifikasi file dengan hash SHA256. Jadi, agar dapat melakukan panggilan API, pertama-tama Anda harus menghitung hash untuk setiap file statis dengan mengompresi file menggunakan Gzip, kemudian mengambil hash SHA256 dari file yang baru dikompresi.

Selanjutnya, misalkan Anda ingin men-deploy tiga file dalam versi baru: file1, file2, dan file3.

  1. Kompresi file menggunakan Gzip:

    gzip file1 && gzip file2 && gzip file3

    Sekarang Anda memiliki tiga file yang dikompresi, yaitu file1.gz, file2.gz, dan file3.gz.

  2. Dapatkan hash SHA256 dari setiap file yang dikompresi:

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    Sekarang Anda memiliki tiga hash SHA256 dari ketiga file yang dikompresi.

  3. Kirim ketiga hash ini dalam permintaan API ke endpoint versions.populateFiles. Cantumkan setiap hash berdasarkan jalur yang diinginkan untuk file yang diupload (dalam contoh ini, /file1, /file2, dan /file3).

    Contoh:

    Perintah cURL

    $ curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -d '{
               "files": {
                 "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4",
                 "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
                 "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
               }
             }' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles

    Permintaan HTTPS Mentah

    Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 181

{
  "files": {
    "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4",
    "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
    "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
  }
}

Panggilan API untuk versions.populateFiles akan menampilkan JSON berikut:

{
  "uploadRequiredHashes": [
    "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
    "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
  ],
  "uploadUrl": "https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files"
}

Respons ini menyertakan:

  • Hash dari setiap file yang perlu diupload. Misalnya, dalam contoh ini file1 telah diupload dalam versi sebelumnya sehingga hash-nya tidak disertakan dalam daftar uploadRequiredHashes.

  • uploadUrl yang bersifat khusus untuk versi baru.

Pada langkah berikutnya, untuk mengupload kedua file baru ini, Anda akan membutuhkan hash dan uploadURL dari respons versions.populateFiles.

Langkah 5: Upload file yang diperlukan

Anda harus mengupload setiap file yang diperlukan satu per satu (file yang tercantum dalam uploadRequiredHashes dari respons versions.populateFiles pada langkah sebelumnya). Untuk upload file ini, Anda akan membutuhkan hash file dan uploadUrl dari langkah sebelumnya.

  1. Tambahkan garis miring dan hash file ke uploadUrl untuk membuat URL khusus file dalam format: https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH.

  2. Upload semua file yang diperlukan satu per satu (dalam contoh ini, hanya file2.gz dan file3.gz) ke URL khusus file menggunakan serangkaian permintaan.

    Misalnya, untuk mengupload file2.gz yang dikompresi:

    Perintah cURL

    curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -H "Content-Type: application/octet-stream" \
       --data-binary @./file2.gz \
https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH

    Permintaan HTTPS Mentah

    Host: upload-firebasehosting.googleapis.com

POST /upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/octet-stream
Content-Length: 500

content-of-file2.gz

Upload yang berhasil akan menampilkan respons HTTPS 200 OK.

Langkah 6: Ubah status versi menjadi FINALIZED

Setelah mengupload semua file yang tercantum dalam respons versions.populateFiles, Anda dapat memperbarui status versi Anda menjadi FINALIZED.

Panggil endpoint versions.patch dengan kolom status dalam permintaan API yang ditetapkan ke FINALIZED.

Contoh:

Perintah cURL

curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       -X PATCH \
       -d '{"status": "FINALIZED"}' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status

Permintaan HTTPS Mentah

Host: firebasehosting.googleapis.com

PATCH /v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 23

{"status": "FINALIZED"}

Panggilan API untuk versions.patch akan menampilkan JSON berikut. Pastikan status telah diupdate menjadi FINALIZED.

{
  "name": "sites/SITE_ID/versions/VERSION_ID",
  "status": "FINALIZED",
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {"Cache-Control": "max-age=1800"}
    }]
  },
  "createTime": "2018-12-02T13:41:56.905743Z",
  "createUser": {
    "email": "SERVICE_ACCOUNT_EMAIL@SITE_ID.iam.gserviceaccount.com"
  },
  "finalizeTime": "2018-12-02T14:56:13.047423Z",
  "finalizeUser": {
    "email": "USER_EMAIL@DOMAIN.tld"
  },
  "fileCount": "5",
  "versionBytes": "114951"
}

Langkah 7: Rilis versi untuk deployment

Setelah mendapatkan versi akhir, rilis versi tersebut untuk di-deploy. Untuk melakukan langkah ini, Anda harus membuat Release dari versi Anda yang berisi konfigurasi hosting dan semua file konten untuk versi baru Anda.

Panggil endpoint releases.create untuk membuat rilis Anda.

Contoh:

Perintah cURL

curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -X POST
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID

Permintaan HTTPS Mentah

Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

Panggilan API untuk releases.create akan menampilkan JSON berikut:

{
  "name": "sites/SITE_ID/releases/RELEASE_ID",
  "version": {
    "name": "sites/SITE_ID/versions/VERSION_ID",
    "status": "FINALIZED",
    "config": {
    "headers": [{
      "glob": "**",
      "headers": {"Cache-Control": "max-age=1800"}
    }]
  }
  },
  "type": "DEPLOY",
  "releaseTime": "2018-12-02T15:14:37Z"
}

Konfigurasi hosting dan semua file untuk versi baru sekarang sudah di-deploy ke situs Anda, dan Anda dapat mengakses file tersebut menggunakan URL:

  • https://SITE_ID.web.app/file1
  • https://SITE_ID.web.app/file2
  • https://SITE_ID.web.app/file3

File-file ini juga dapat diakses di URL yang terkait dengan domain SITE_ID.firebaseapp.com Anda.

Anda juga dapat melihat rilis baru yang tercantum di dasbor Hosting Firebase console.