ใช้ Cloud Firestore REST API

แม้ว่าวิธีที่ง่ายที่สุดในการใช้ Cloud Firestore คือการใช้ไลบรารีของไคลเอ็นต์แบบเนทีฟ แต่ก็มีบางสถานการณ์ที่การเรียก REST API โดยตรงจะมีประโยชน์

REST API อาจมีประโยชน์ในกรณีการใช้งานต่อไปนี้

• การเข้าถึง Cloud Firestore จากสภาพแวดล้อมที่มีข้อจำกัดด้านทรัพยากร เช่น อุปกรณ์ Internet of Things (IoT) ซึ่งไม่สามารถเรียกใช้ไลบรารีของไคลเอ็นต์ที่สมบูรณ์ได้
• การทำให้การดูแลระบบฐานข้อมูลเป็นไปโดยอัตโนมัติหรือการดึงข้อมูลเมตาของฐานข้อมูลแบบละเอียด

หากคุณใช้ภาษาที่รองรับ gRPC ให้พิจารณาใช้ RPC API แทน REST API

การตรวจสอบสิทธิ์และการให้สิทธิ์

สำหรับการตรวจสอบสิทธิ์ Cloud Firestore REST API ยอมรับโทเค็นรหัส Firebase Authentication หรือโทเค็น Google Identity OAuth 2.0 โทเค็นที่คุณระบุจะส่งผลต่อการให้สิทธิ์ของคำขอ

• ใช้โทเค็นรหัส Firebase เพื่อตรวจสอบสิทธิ์คำขอจากผู้ใช้แอปพลิเคชัน สำหรับคำขอเหล่านี้ Cloud Firestore ใช้ Cloud Firestore Security Rules เพื่อพิจารณาว่าคำขอ ได้รับอนุญาตหรือไม่

• ใช้โทเค็น Google Identity OAuth 2.0 และ บัญชีบริการเพื่อตรวจสอบสิทธิ์คำขอจาก แอปพลิเคชัน เช่น คำขอการดูแลระบบฐานข้อมูล สำหรับคำขอเหล่านี้ Cloud Firestore จะใช้ Identity and Access Management (IAM) เพื่อพิจารณาว่า คำขอได้รับอนุญาตหรือไม่

การใช้โทเค็นรหัส Firebase

คุณสามารถรับโทเค็นรหัส Firebase ได้ 2 วิธีดังนี้

• สร้างโทเค็นรหัส Firebase โดยใช้ Firebase Authentication REST API
• ดึงโทเค็นรหัส Firebase ของผู้ใช้จาก Firebase Authentication SDK

การดึงโทเค็นรหัส Firebase ของผู้ใช้จะช่วยให้คุณส่งคำขอในนามของผู้ใช้ได้

สำหรับคำขอที่ตรวจสอบสิทธิ์ด้วยโทเค็นรหัส Firebase และคำขอที่ไม่ได้ตรวจสอบสิทธิ์ Cloud Firestore จะใช้ Cloud Firestore Security Rules เพื่อพิจารณาว่าคำขอได้รับ อนุญาตหรือไม่

การใช้โทเค็น Google Identity OAuth 2.0

คุณสามารถสร้างโทเค็นเพื่อการเข้าถึงได้โดยใช้ บัญชีบริการกับ ไลบรารีของไคลเอ็นต์ Google API หรือทำตามขั้นตอนใน การใช้ OAuth 2.0 สำหรับแอปพลิเคชันแบบเซิร์ฟเวอร์ถึงเซิร์ฟเวอร์ นอกจากนี้ คุณ ยังสร้างโทเค็นด้วยเครื่องมือบรรทัดคำสั่ง gcloud และ คำสั่ง gcloud auth application-default print-access-token ได้ด้วย

โทเค็นนี้ต้องมีขอบเขตต่อไปนี้เพื่อส่งคำขอไปยัง Cloud Firestore REST API:

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

หากคุณตรวจสอบสิทธิ์คำขอด้วยบัญชีบริการและโทเค็น Google Identity OAuth 2.0 Cloud Firestore จะถือว่าคำขอของคุณดำเนินการในนาม ของแอปพลิเคชันแทนที่จะเป็นผู้ใช้แต่ละราย Cloud Firestore อนุญาตให้ คำขอเหล่านี้ละเว้นกฎความปลอดภัย แต่ Cloud Firestore จะใช้ IAM เพื่อพิจารณาว่าคำขอได้รับอนุญาตหรือไม่

คุณสามารถควบคุมสิทธิ์เข้าถึงของบัญชีบริการได้โดยการกำหนด Cloud Firestoreบทบาท IAM

การตรวจสอบสิทธิ์ด้วยโทเค็นเพื่อการเข้าถึง

หลังจากได้รับโทเค็นรหัส Firebase หรือโทเค็น Google Identity OAuth 2.0 แล้ว ให้ส่งโทเค็นไปยังปลายทางของ Cloud Firestore เป็นส่วนหัว Authorization ที่ตั้งค่าเป็น Bearer {YOUR_TOKEN}

การเรียก REST

ปลายทาง REST API ทั้งหมดอยู่ใน URL ฐาน https://firestore.googleapis.com/v1/

หากต้องการสร้างเส้นทางไปยังเอกสารที่มีรหัส LA ในคอลเล็กชัน cities ภายใต้โปรเจ็กต์ YOUR_PROJECT_ID คุณจะต้องใช้โครงสร้างต่อไปนี้

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

หากต้องการโต้ตอบกับเส้นทางนี้ ให้รวมเส้นทางกับ URL ฐานของ API

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

วิธีที่ดีที่สุดในการเริ่มต้นทดลองใช้ REST API คือการใช้ API Explorer ซึ่งจะสร้างโทเค็น Google Identity OAuth 2.0 โดยอัตโนมัติและช่วยให้คุณตรวจสอบ API ได้

เมธอด

ด้านล่างนี้คือคำอธิบายสั้นๆ เกี่ยวกับกลุ่มเมธอดที่สำคัญที่สุด 2 กลุ่ม ดูรายการทั้งหมดได้ที่ เอกสารอ้างอิง REST API หรือใช้ โปรแกรมสำรวจ API

v1.projects.databases.documents

ดำเนินการ CRUD กับเอกสาร ซึ่งคล้ายกับที่ระบุไว้ใน คู่มือการเพิ่มข้อมูล หรือ รับข้อมูล

v1.projects.databases.collectionGroups.indexes

ดำเนินการกับดัชนี เช่น การสร้างดัชนีใหม่ การปิดใช้ดัชนีที่มีอยู่ หรือการแสดงดัชนีปัจจุบันทั้งหมด มีประโยชน์สำหรับการทำให้การย้ายโครงสร้างข้อมูลเป็นไปโดยอัตโนมัติหรือการซิงค์ดัชนีระหว่างโปรเจ็กต์

นอกจากนี้ยังช่วยให้ดึงข้อมูลเมตาของเอกสารได้ เช่น รายการฟิลด์และคอลเล็กชันย่อยทั้งหมดสำหรับเอกสารที่ระบุ

รหัสข้อผิดพลาด

เมื่อคำขอ Cloud Firestore สำเร็จ API Cloud Firestore จะแสดงรหัสสถานะ HTTP 200 OK และข้อมูลที่ขอ เมื่อคำขอไม่สำเร็จ Cloud Firestore API จะแสดง รหัสสถานะ HTTP 4xx หรือ 5xx และการตอบกลับพร้อมข้อมูลเกี่ยวกับ ข้อผิดพลาด

ตารางต่อไปนี้แสดงการดำเนินการที่แนะนำสำหรับรหัสข้อผิดพลาดแต่ละรายการ รหัสเหล่านี้ใช้ กับ Cloud Firestore REST และ RPC API Cloud Firestore SDK และไลบรารีของไคลเอ็นต์อาจไม่แสดงรหัสข้อผิดพลาดเดียวกัน