Menggunakan REST API Cloud Firestore

Cara termudah untuk menggunakan Cloud Firestore adalah dengan menggunakan salah satu library native client, namun ada beberapa situasi di mana kita sebaiknya memanggil REST API secara langsung.

REST API berguna untuk kasus penggunaan berikut:

Mengakses Cloud Firestore dari lingkungan resource yang terbatas, seperti perangkat internet of things (IoT), tempat tidak bisa dijalankannya library klien secara menyeluruh.
Mengotomatisasi administrasi database atau mengambil metadata database yang terperinci.

Jika Anda menggunakan bahasa yang didukung gRPC, sebaiknya gunakan RPC API, bukan REST API.

Autentikasi dan otorisasi

Untuk autentikasi, REST API Cloud Firestore menerima token ID Firebase Authentication atau token Google Identity OAuth 2.0. Token yang Anda berikan berpengaruh terhadap otorisasi permintaan:

Gunakan token ID Firebase untuk mengautentikasi permintaan dari pengguna aplikasi Anda. Untuk permintaan ini, Cloud Firestore menggunakan Aturan Keamanan Cloud Firestore untuk menentukan apakah permintaan diotorisasi atau tidak.
Gunakan token Google Identity OAuth 2.0 dan akun layanan untuk mengautentikasi permintaan dari aplikasi Anda, seperti permintaan administrasi database. Untuk permintaan ini, Cloud Firestore menggunakan Identity and Access Management (IAM) untuk menentukan apakah permintaan diotorisasi atau tidak.

Bekerja dengan token ID Firebase

Anda bisa mendapatkan token ID Firebase dengan 2 cara:

Dengan mengambil token ID Firebase pengguna, Anda dapat mengajukan permintaan atas nama pengguna.

Untuk permintaan yang diautentikasi dengan token ID Firebase dan untuk permintaan yang tidak diautentikasi, Cloud Firestore menggunakan Aturan Keamanan Cloud Firestore untuk menentukan apakah permintaan diotorisasi atau tidak.

Bekerja dengan token Google Identity OAuth 2.0

Anda dapat membuat token akses menggunakan akun layanan dengan Library Klien Google API, atau dengan mengikuti langkah-langkah di bagian Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server. Anda juga dapat membuat token dengan alat command line gcloud dan perintah gcloud auth application-default print-access-token.

Token ini harus memiliki cakupan berikut untuk mengirim permintaan ke REST API Cloud Firestore:

https://www.googleapis.com/auth/datastore

Jika Anda mengautentikasi permintaan dengan akun layanan dan token Google Identity OAuth 2.0, Cloud Firestore menganggap permintaan Anda bertindak atas nama aplikasi Anda, dan bukan pengguna secara individual. Dengan Cloud Firestore, permintaan ini dapat mengabaikan aturan keamanan Anda. Sebagai gantinya, Cloud Firestore menggunakan IAM untuk menentukan apakah permintaan diizinkan.

Anda dapat mengontrol izin akses akun layanan dengan menetapkan peran IAM Cloud Firestore.

Mengautentikasi dengan token akses

Setelah Anda mendapatkan token ID Firebase atau token Google Identity OAuth 2.0, teruskan token tersebut ke endpoint Cloud Firestore sebagai Authorization yang ditetapkan ke Bearer {YOUR_TOKEN}.

Membuat panggilan REST

Semua endpoint REST API tersedia di bagian URL dasar https://firestore.googleapis.com/v1/.

Untuk membuat jalur ke dokumen dengan ID LA dalam koleksi cities di bagian project YOUR_PROJECT_ID, Anda akan menggunakan struktur berikut.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Untuk berinteraksi dengan jalur ini, gabungkan dengan URL API dasar.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Cara terbaik untuk mulai bereksperimen dengan REST API adalah dengan menggunakan API Explorer, yang secara otomatis menghasilkan token Google Identity OAuth 2.0 dan dapat Anda gunakan untuk memeriksa API.

Metode

Berikut adalah deskripsi singkat mengenai 2 grup metode yang paling penting. Untuk mengetahui daftar lengkapnya, lihat referensi REST API atau gunakan API Explorer.

`v1.projects.databases.documents`

Menjalankan operasi CRUD di dokumen, sama seperti yang dijelaskan dalam panduan menambahkan data atau mendapatkan data.

`v1.projects.databases.collectionGroups.indexes`

Melakukan tindakan pada indeks seperti membuat indeks baru, menonaktifkan indeks yang ada, atau membuat daftar semua indeks saat ini. Berguna untuk mengotomatisasi migrasi struktur data atau melakukan sinkronisasi indeks antar project.

Metode ini juga memungkinkan pengambilan metadata dokumen, seperti daftar semua kolom dan subkoleksi untuk dokumen tertentu.

Kode Error

Saat permintaan Cloud Firestore berhasil, Cloud Firestore API akan menampilkan kode status HTTP 200 OK dan data yang diminta. Jika permintaan gagal, Cloud Firestore API akan menampilkan kode status HTTP 4xx atau 5xx dan respons dengan informasi tentang error tersebut.

Tabel berikut mencantumkan tindakan yang direkomendasikan untuk setiap kode error. Kode ini berlaku untuk REST API dan RPC API Cloud Firestore. Cloud Firestore SDK dan library klien mungkin tidak menampilkan kode error yang sama.

Kode Error Kanonis	Deskripsi	Tindakan yang Direkomendasikan
`ABORTED`	Permintaan bertentangan dengan permintaan lain.	Untuk commit non-transaksional: Coba lagi permintaan atau susun ulang model data Anda untuk mengurangi pertentangan. Untuk permintaan dalam transaksi: Coba lagi seluruh transaksi atau susun ulang model data Anda untuk mengurangi pertentangan.
`ALREADY_EXISTS`	Permintaan mencoba membuat dokumen yang sudah ada.	Jangan mencoba lagi tanpa memperbaiki masalah.
`DEADLINE_EXCEEDED`	Server Cloud Firestore yang menangani permintaan melebihi batas waktu.	Coba lagi menggunakan backoff eksponensial.
`FAILED_PRECONDITION`	Permintaan tidak memenuhi salah satu prasyaratnya. Misalnya, permintaan kueri mungkin memerlukan indeks yang belum ditentukan. Lihat kolom pesan dalam respons error untuk prasyarat yang gagal.	Jangan mencoba lagi tanpa memperbaiki masalah.
`INTERNAL`	Server Cloud Firestore menampilkan error.	Jangan mencoba lagi permintaan ini lebih dari sekali.
`INVALID_ARGUMENT`	Parameter permintaan menyertakan nilai yang tidak valid. Lihat kolom pesan dalam respons error untuk nilai yang tidak valid.	Jangan mencoba lagi tanpa memperbaiki masalah.
`NOT_FOUND`	Permintaan tersebut berupaya memperbarui dokumen yang tidak ada.	Jangan mencoba lagi tanpa memperbaiki masalah.
`PERMISSION_DENIED`	Pengguna tidak diberi otorisasi untuk membuat permintaan ini.	Jangan mencoba lagi tanpa memperbaiki masalah.
`RESOURCE_EXHAUSTED`	Project ini melampaui kuota atau kapasitas region/multi-region.	Verifikasi bahwa Anda tidak melebihi kuota project. Jika Anda melebihi kuota project, jangan mencoba lagi tanpa memperbaiki masalah. Jika tidak, coba lagi dengan backoff eksponensial.
`UNAUTHENTICATED`	Permintaan tidak menyertakan kredensial autentikasi yang valid.	Jangan mencoba lagi tanpa memperbaiki masalah.
`UNAVAILABLE`	Server Cloud Firestore menampilkan error.	Coba lagi menggunakan backoff eksponensial.