Men-deploy ke situs Anda menggunakan REST API Hosting

REST API Firebase Hosting dapat digunakan untuk penerapan terprogram dan dapat disesuaikan ke situs yang dihosting oleh Firebase. Gunakan REST API ini untuk men-deploy file konten dan konfigurasi hosting yang baru atau yang telah diupdate.

Selain menggunakan antarmuka command line (CLI) Firebase untuk melakukan penerapan, Anda juga bisa menggunakan REST API Firebase Hosting guna secara terprogram membuat version baru dari aset untuk situs Anda, mengupload file ke versi tersebut, lalu men-deploy-nya ke situs Anda.

Sebagai contoh, dengan REST API Firebase Hosting, Anda dapat:

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

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

  • Mengotomatiskan penerapan ketika konten statis dihasilkan. Ketika suatu proses menghasilkan konten statis secara terprogram (misalnya konten buatan pengguna seperti artikel wiki atau berita), Anda dapat menerapkan konten yang dihasilkan tersebut sebagai file statis, bukan menayangkannya secara dinamis. Tindakan ini menghemat daya komputasi yang berharga dan menyalurkan 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 Firebase Hosting.

Sebelum memulai: Mengaktifkan REST API

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

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

  2. Saat diminta, pilih project Firebase Anda.

  3. Klik Aktifkan 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 menyetujui 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.

Gunakan kredensial Firebase Anda beserta Library Klien Google API untuk bahasa pilihan Anda saat mengambil token akses OAuth 2.0 yang berlaku 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 JWT. Untuk mengetahui informasi lebih lanjut, baca artikel 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 akses yang telah diupdate.

Langkah 2: 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-deploynya ke situs Anda.

  1. Tentukan site-name dari situs yang akan menjadi tujuan penerapan Anda.

  2. Panggil endpoint versions.create menggunakan site-name Anda dalam panggilan.

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

    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-name/versions
    

    Permintaan HTTP mentah

    Host: firebasehosting.googleapis.com
    
    POST /v1beta1/sites/site-name/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-name/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-name/versions/version-id. Anda akan membutuhkan ID unik ini di sepanjang panduan untuk merujuk ke versi khusus ini.

Langkah 3: Tentukan daftar file yang ingin Anda terapkan

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

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.

Untuk contoh ini, 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 lokasi 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-name/versions/version-id:populateFiles
    

    Permintaan HTTP mentah

    Host: firebasehosting.googleapis.com
    
    POST /v1beta1/sites/site-name/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-name/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 4: 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 hasil upload file ini, Anda akan membutuhkan hash file dan uploadUrl dari langkah sebelumnya.

  1. Tambahkan garis miring ke depan dan hash file ke uploadUrl untuk membuat URL khusus file dalam format: https://upload-firebasehosting.googleapis.com/upload/sites/site-name/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-name/versions/version-id/files/file-hash
    

    Permintaan HTTP mentah

    Host: upload-firebasehosting.googleapis.com
    
    POST /upload/sites/site-name/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 HTTP 200 OK.

Langkah 5: Ubah status versi menjadi FINALIZED

Setelah mengupload semua file yang tercantum dalam respons versions.populateFiles, Anda dapat mengupdate 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-name/versions/version-id?update_mask=status

Permintaan HTTP mentah

Host: firebasehosting.googleapis.com

PATCH /v1beta1/sites/site-name/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-name/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-name.iam.gserviceaccount.com"
  },
  "finalizeTime": "2018-12-02T14:56:13.047423Z",
  "finalizeUser": {
    "email": "your-email@domain.tld"
  },
  "fileCount": "5",
  "versionBytes": "114951"
}

Langkah 6: Rilis versi untuk penerapan

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-name/releases?versionName=sites/site-name/versions/version-id

Permintaan HTTP mentah

Host: firebasehosting.googleapis.com

POST /v1beta1/sites/site-name/releases?versionName=sites/site-name/versions/version-id HTTP/1.1
Authorization: Bearer access-token

Panggilan API untuk releases.create akan menampilkan JSON berikut:

{
  "name": "sites/site-name/releases/release-id",
  "version": {
    "name": "sites/site-name/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-name.web.app/file1
  • https://site-name.web.app/file2
  • https://site-name.web.app/file3

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

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