Menyiapkan dan mengelola project Firebase menggunakan Management REST API

Firebase Management REST API memungkinkan penyiapan dan pengelolaan project Firebase secara terprogram, termasuk resource Firebase dan aplikasi Firebase pada suatu project.

Ringkasan ini berisi penjelasan mengenai alur kerja umum untuk menambahkan resource dan aplikasi Firebase ke project Google Cloud yang ada yang saat ini tidak menggunakan layanan Firebase.

Anda dapat melompat ke bagian tertentu dari halaman ini jika hanya ingin:

• Menambahkan layanan Firebase ke project
• Menambahkan Aplikasi Firebase ke project Firebase
• Menautkan project Firebase ke akun Google Analytics
• Memfinalisasi lokasi default project

Sebelum mengikuti langkah apa pun di halaman ini, pastikan Anda mengaktifkan API.

Untuk mengetahui informasi tentang pengelolaan akses untuk Firebase Management API, buka dokumentasi API Cloud Identity Access Management (IAM).

Catatan: Jika belum memiliki project Google Cloud, Anda dapat membuatnya menggunakan metode projects.create pada Google Cloud Resource Manager API atau menggunakan Google Cloud Console.

Buka artikel Memahami project Firebase untuk mengetahui informasi tentang jumlah project yang diizinkan per akun.

Sebelum memulai

Sebelum memulai, Anda harus mengaktifkan Management API untuk project Google Cloud dan membuat token akses.

Mengaktifkan Management REST API untuk project Google Cloud

Jika belum melakukannya, Anda harus mengaktifkan Firebase Management API untuk digunakan dengan project Google Cloud.

1. Buka halaman Firebase Management API di konsol API Google.
2. Jika diminta, pilih project Google Cloud Anda.
3. Klik Aktifkan di halaman Firebase Management API.

Membuat token akses API

Berikut adalah contoh untuk Node.js yang mengambil token akses Anda.

Pertama, jika tidak berada di lingkungan Google Cloud, tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur yang mengarah ke kunci akun layanan Anda.

Linux atau macOS

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Windows

Dengan PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-file.json"

Selanjutnya, gunakan Firebase Admin SDK untuk mendapatkan token akses dari kredensial akun layanan Anda:

const admin = require('firebase-admin');

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

Menemukan nama resource project

Anda dapat menemukan project Google Cloud, yang tersedia untuk penambahan layanan Firebase.

Untuk memanggil endpoint ini:

• Anda harus sudah memiliki project Google Cloud dan token akses API.
• Anggota project minimal harus merupakan Viewer pada project Google Cloud yang ada.

PERMINTAAN

Panggil availableProjects.list. Isi permintaan untuk panggilan ini harus kosong.

Berikut adalah contoh Node.js untuk meminta daftar project Google Cloud yang tersedia:

const fetch = require('node-fetch');

async function listProjects() {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/availableProjects';
  const options = {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    const projects = resp['projectInfo'];
    console.log('Project total: ' + projects.length);
    console.log('');
    for (let i in projects) {
      const project = projects[i];
      console.log('Project ' + i);
      console.log('ID: ' + project['project']);
      console.log('Display Name: ' + project['displayName']);
      console.log('');
    }
  } catch(err) {
    console.error(err);
  }
}

HASIL

Isi respons dari panggilan ke availableProjects.list berisi daftar objek ProjectInfo. Jika daftar project terlalu panjang, isi respons juga memuat nextPageToken yang dapat Anda gunakan sebagai parameter kueri untuk membuka halaman project berikutnya.

Berikut adalah contoh isi respons panggilan availableProjects.list:

{
  "projectInfo": [
    {
      "project": "projects/first-cloud-project",
      "displayName": "First Cloud Project"
    },
    {
      "project": "projects/second-cloud-project",
      "displayName": "Second Cloud Project"
    }
  ]
}

Contoh respons ini memiliki dua project Google Cloud yang dapat ditambahi layanan Firebase. Perlu diperhatikan bahwa kolom project memberikan nama resource unik secara global untuk sebuah project.

Anda dapat menggunakan nilai project apa pun yang tercantum dalam respons dari availableProjects.list untuk menambahkan layanan Firebase atau menambahkan aplikasi ke project Anda.

Di bagian berikutnya, kita akan menambahkan layanan Firebase ke First Cloud Project menggunakan nama resource projects/first-gcp-project.

Menambahkan layanan Firebase ke project

Project Google Cloud dapat memanfaatkan layanan yang ditawarkan Firebase. Di bagian ini, Anda akan mempelajari cara menambahkan layanan Firebase ke project Google Cloud yang ada secara terprogram. Perlu diperhatikan bahwa Anda juga dapat menambahkan layanan Firebase ke project Google Cloud yang ada di Firebase console.

Untuk memanggil endpoint ini:

• Anda harus sudah memiliki project Google Cloud, token akses API, dan nama resource unik milik project.
• Anggota project atau akun layanan harus memiliki izin berikut. Jika Anda adalah Editor atau Pemilik project Google Cloud yang ada, berarti Anda memiliki izin ini.
  firebase.projects.update
resourcemanager.projects.get
serviceusage.services.enable
serviceusage.services.get

PERMINTAAN

Panggil projects.addFirebase. Isi permintaan untuk panggilan ini harus kosong.

Berikut adalah contoh Node.js untuk menambahkan layanan Firebase ke project Google Cloud Anda:

const fetch = require('node-fetch');

async function addFirebase(projectId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addFirebase';
  const options = {
    method: 'POST',
    // Use a manual access token here since explicit user access token is required.
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

HASIL

Hasil panggilan ke projects.addFirebase adalah Operation. Sebelum Anda dapat memanggil endpoint lain terkait Firebase untuk project Anda, operasi harus berhasil.

Untuk memeriksa apakah operasi berhasil, Anda dapat memanggil operations.get pada operasi tersebut hingga done bernilai true dan response-nya berjenis FirebaseProject. Jika operasi gagal, error-nya akan disetel ke google.rpc.Status.

Berikut adalah isi respons panggilan operations.get:

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.FirebaseProject",
    "projectId": "first-cloud-project",
    "projectNumber": "...",
    "displayName": "First Cloud Project",
    "name": "projects/first-cloud-project",
    "resources": {
      "hostingSite": "first-cloud-project",
      "realtimeDatabaseInstance": "first-cloud-project"
    }
  }
}

Karena done bernilai true dan response-nya berjenis FirebaseProject, project Google Cloud sekarang memiliki layanan Firebase. Respons tersebut juga berisi informasi berguna lainnya tentang FirebaseProject yang baru dibuat, seperti projectNumber dan resources defaultnya. Operation akan otomatis dihapus setelah selesai.

Menambahkan Aplikasi Firebase ke project

Berbagai aplikasi dapat menggunakan FirebaseProject, termasuk aplikasi iOS, Android, dan web. Di bagian ini, Anda akan mempelajari cara menambahkan Aplikasi Firebase ke FirebaseProject yang ada secara terprogram. Perlu diperhatikan bahwa Anda juga dapat menambahkan Aplikasi Firebase ke project Firebase yang ada di Firebase console.

Untuk memanggil endpoint di bagian ini:

• Anda harus memiliki token akses API dan FirebaseProject yang ada.
• Anggota project harus menjadi Editor atau Pemilik project Firebase yang ada.

Pilih jenis Aplikasi Firebase untuk ditambahkan ke project Firebase Anda.

iOS Android Web

Anda dapat menambahkan Aplikasi Android Firebase ke project Firebase yang ada.

PERMINTAAN

Panggil projects.androidApps.create. Berikut cara membuat isi permintaan:

• Wajib diisi:

  • packageName: Nama paket kanonis Aplikasi Android seperti yang akan muncul di Konsol Google Play.

• Bersifat opsional, tetapi direkomendasikan:

  • displayName: Nama tampilan aplikasi yang ditetapkan oleh pengguna. Nilai ini berguna untuk menemukan aplikasi Anda nanti di Firebase console.

Dalam isi permintaan untuk contoh, kami akan menggunakan packageName dan displayName:

{
  "displayName": "My Firebase Android App"
  "packageName": "com.firebase.android"
}

Berikut adalah contoh Node.js untuk menambahkan Aplikasi Android Firebase ke project Firebase Anda:

const fetch = require('node-fetch');

async function addAndroidApp(projectId, displayName, packageName) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/androidApps';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'displayName': displayName,
      'packageName': packageName
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

HASIL

Hasil panggilan ke projects.androidApps.create adalah Operation. Sebelum Anda dapat memanggil endpoint lain terkait Firebase untuk project Anda, operasi harus berhasil.

Untuk memeriksa apakah operasi berhasil, Anda dapat memanggil operations.get pada operasi tersebut hingga done bernilai true dan response-nya berjenis AndroidApp. Jika operasi gagal, error-nya akan disetel ke google.rpc.Status.

Berikut adalah isi respons panggilan operations.get:

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AndroidApp",
    "name": "projects/first-cloud-project/androidApps/...",
    "appId": "...",
    "displayName": "My Firebase Android App",
    "projectId": "first-cloud-project",
    "packageName": "com.firebase.android"
  }
}

Karena done bernilai true dan response-nya berjenis AndroidApp, FirebaseProject sekarang memiliki AndroidApp. Respons tersebut juga berisi informasi berguna lainnya tentang Aplikasi Android Firebase yang baru dibuat, seperti appId Firebase yang unik. Operation akan otomatis dihapus setelah selesai.

Menambahkan sertifikat SHA

Anda dapat menambahkan sertifikat SHA ke Aplikasi Android Firebase yang ada dengan memanggil projects.androidApps.sha.create. Isi permintaan untuk panggilan metode ini harus memiliki kolom name yang kosong. Hasil dari panggilan ini adalah instance ShaCertificate yang baru dibuat.

Saat memanggil projects.androidApps.sha.create, Anda harus memberikan hash sertifikat SHA-1 atau SHA-256 yang valid. Anda bisa mendapatkan hash SHA dari sertifikat penandatanganan dengan perintah signingReport gradle:

./gradlew signingReport

Untuk mengetahui informasi selengkapnya, kunjungi Google API untuk Android.

Menautkan project Firebase ke akun Google Analytics (Opsional)

Anda dapat menautkan akun Google Analytics yang ada ke FirebaseProject yang ada secara terprogram. Perlu diperhatikan bahwa Anda juga dapat menautkan project Firebase yang ada ke Google Analytics di tab Integrasi pada Setelan Project Anda.

Untuk memanggil endpoint ini:

• Anda harus memiliki token akses API dan FirebaseProject yang ada.
• Anggota project harus menjadi Pemilik project Firebase yang ada.

Panggilan ke projects.addGoogleAnalytics memerlukan analytics_resource, yang dapat berupa analyticsAccountId atau analyticsPropertyId:

• Tentukan analyticsAccountId yang ada untuk menyediakan properti Google Analytics baru dalam akun yang ditentukan dan mengaitkan properti baru dengan project Firebase Anda.

• Tentukan analyticsPropertyId yang ada untuk mengaitkan properti Google Analytics dengan project Firebase Anda.

Anda dapat menemukan analyticsAccountId dan analyticsPropertyId yang ada di situs Google Analytics.

Saat Anda memanggil projects.addGoogleAnalytics:

1. Pemeriksaan pertama menentukan apakah aliran data yang ada di properti Google Analytics sesuai dengan Aplikasi Firebase yang ada di FirebaseProject Anda (berdasarkan packageName atau bundleId yang terkait dengan aliran data). Selanjutnya, aliran data dan aplikasi akan ditautkan jika berlaku. Perlu diperhatikan bahwa penautan otomatis ini hanya berlaku untuk Aplikasi Android dan Aplikasi iOS.

2. Jika aliran data yang terkait tidak ditemukan untuk Aplikasi Firebase, aliran data baru akan disediakan di properti Google Analytics untuk setiap Aplikasi Firebase. Perlu diperhatikan bahwa aliran data yang baru selalu disediakan untuk Aplikasi Web meskipun jika aliran data tersebut sebelumnya terkait dengan aliran data di properti Analytics.

Pelajari lebih lanjut hierarki dan struktur akun Google Analytics dalam dokumentasi Analytics.

Catatan: Jika Anda memiliki Aplikasi Web Firebase di project Firebase sebelum menautkan project ke Google Analytics, objek konfigurasi Firebase untuk aplikasi tersebut akan diupdate dengan menambahkan kolom measurementId baru. Objek konfigurasi yang diupdate ini diperlukan agar Aplikasi Web dapat menggunakan Analytics. Panggil projects.webApps.getConfig untuk mendapatkan objek konfigurasi yang telah diupdate.

PERMINTAAN

Panggil projects.addGoogleAnalytics.

Dalam isi permintaan untuk contoh panggilan ke project.addGoogleAnalytics, kami akan menentukan akun Google Analytics analyticsAccountId. Panggilan ini akan menyediakan properti Google Analytics baru dan mengaitkan properti baru tersebut dengan FirebaseProject.

{
  "analyticsAccountId": "<your-google-analytics-account-id>"
}

Berikut adalah contoh Node.js untuk menautkan project Firebase dengan akun Google Analytics:

const fetch = require('node-fetch');

async function addGoogleAnalytics(projectId, analyticsAccountId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addGoogleAnalytics';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'analyticsAccountId': analyticsAccountId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

HASIL

Hasil panggilan ke projects.addGoogleAnalytics adalah Operation. Sebelum Anda dapat memanggil endpoint lain terkait Firebase untuk project Anda, operasi harus berhasil.

Untuk memeriksa apakah operasi berhasil, Anda dapat memanggil operations.get pada operasi tersebut hingga done bernilai true dan response-nya berjenis analyticsDetails. Jika operasi gagal, error-nya akan disetel ke google.rpc.Status.

Berikut adalah isi respons panggilan operations.get:

{
  "name": "operations/...",
  "none": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AnalyticsDetails",
    "analyticsProperty": [
      {
        "id": "...",
        "displayName": "..."
      }
    ],
    "streamMappings": [
      {
        "app": "...",
        "streamId": "...",
        "measurementId": "..."
      }
    ]
  }
}

Karena done bernilai benar dan response-nya berjenis analyticsDetails, FirebaseProject sekarang ditautkan ke akun Google Analytics yang ditentukan. Operation akan otomatis dihapus setelah selesai.

Memfinalisasi lokasi default project (Opsional)

Jika project Firebase akan menggunakan Cloud Firestore, Cloud Storage, atau aplikasi App Engine, Anda dapat memfinalisasi lokasi resource Google Cloud Platform (GCP) default untuk project Anda secara terprogram. Perlu diperhatikan bahwa Anda juga dapat memilih lokasi di Firebase console.

Untuk memanggil endpoint ini:

• Anda harus memiliki token akses API dan FirebaseProject yang ada.
• Anggota project harus menjadi Pemilik project Firebase yang ada.

Peringatan: Setelan ini tidak dapat diurungkan atau diubah nanti. Setelah Anda menetapkan lokasi resource Google Cloud Platform (GCP) default untuk project, lokasi tersebut tidak dapat diubah.

Sebelum menetapkan lokasi ini, baca artikel Memilih lokasi untuk project guna mengetahui informasi tentang lokasi yang paling cocok untuk project Anda. Anda juga harus memanggil projects.availableLocations untuk menampilkan daftar lokasi yang valid untuk project Anda karena jika project tersebut adalah bagian dari organisasi Google Cloud, kebijakan organisasi dapat membatasi lokasi yang valid untuk project Anda.

Pemanggilan metode defaultLocation.finalize ini akan membuat aplikasi App Engine dengan bucket Cloud Storage default yang berada di locationId yang Anda berikan dalam isi permintaan.

Lokasi resource GCP default mungkin telah ditentukan jika Project sudah memiliki aplikasi App Engine atau metode defaultLocation.finalize ini sebelumnya telah dipanggil.

Catatan: Jika Anda memiliki Aplikasi Web Firebase di project Firebase sebelum memfinalisasi lokasi resource default, objek konfigurasi Firebase untuk aplikasi tersebut akan diupdate dengan menambahkan storageUrl untuk bucket default project. Objek konfigurasi yang diupdate ini diperlukan agar Aplikasi Web dapat menggunakan Cloud Storage. Panggil projects.webApps.getConfig untuk mendapatkan objek konfigurasi yang telah diupdate.

PERMINTAAN

Panggil projects.defaultLocation.finalize. Berikut cara membuat isi permintaan:

• Wajib diisi:

  • locationId: Lokasi tempat data Anda disimpan untuk layanan GCP yang memerlukan setelan lokasi, seperti Cloud Firestore atau Cloud Storage.

{
  "locationId": "us-west2"
}

Berikut adalah contoh Node.js untuk memfinalisasi lokasi default project Anda:

const fetch = require('node-fetch');

async function finalizeProjectLocation(projectId, locationId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/defaultLocation:finalize';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'locationId': locationId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

HASIL

Hasil panggilan ke projects.defaultLocation.finalize adalah Operation. Sebelum Anda dapat memanggil endpoint lain terkait Firebase untuk project Anda, operasi harus berhasil.

Untuk memeriksa apakah operasi berhasil, Anda dapat memanggil operations.get pada operasi tersebut hingga done bernilai true dan response-nya berjenis google.protobuf.Empty. Jika operasi tidak berhasil, isi respons error akan berjenis google.rpc.Status. Operation akan otomatis dihapus setelah selesai.