Buka konsol

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 Pengelolaan Akses dan Identitas (IAM) Cloud 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 fitur 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 peraturan keamanan Anda. Sebagai gantinya, Cloud Firestore menggunakan Pengelolaan Akses dan Identitas (IAM) Cloud untuk menentukan apakah permintaan diotorisasi atau tidak.

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

Mengautentikasi dengan token akses

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

Membuat panggilan REST

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

Untuk membuat jalur menuju dokumen dengan ID LA di koleksi cities pada project YOUR_PROJECT_ID, Anda harus menggunakan struktur berikut.

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

Untuk berinteraksi dengan lokasi 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

Jalankan operasi CRUD pada 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.