แม้ว่าวิธีที่ง่ายที่สุดในการใช้ Cloud Firestore คือการเรียกใช้ไลบรารีของไคลเอ็นต์แบบเนทีฟ แต่ก็มีบางกรณีที่การเรียกใช้ REST API โดยตรงจะมีประโยชน์
REST API มีประโยชน์สำหรับกรณีการใช้งานต่อไปนี้
- การเข้าถึง Cloud Firestore จากสภาพแวดล้อมที่มีทรัพยากรจํากัด เช่น อุปกรณ์อินเทอร์เน็ตของสรรพสิ่ง (IoT) ซึ่งไม่สามารถเรียกใช้คลังไคลเอ็นต์ที่สมบูรณ์ได้
- การดูแลระบบฐานข้อมูลอัตโนมัติหรือการดึงข้อมูลเมตาฐานข้อมูลที่ละเอียด
หากคุณใช้ภาษาที่ gRPC รองรับ ให้พิจารณาใช้ RPC API แทน REST API
การตรวจสอบสิทธิ์และการให้สิทธิ์
Cloud Firestore REST API ยอมรับโทเค็นระบุตัวตน Firebase Authentication หรือโทเค็น Google Identity OAuth 2.0 สำหรับการตรวจสอบสิทธิ์ โทเค็นที่คุณระบุจะส่งผลต่อการให้สิทธิ์ของคําขอ ดังนี้
ใช้โทเค็นรหัส Firebase เพื่อตรวจสอบสิทธิ์คำขอจากผู้ใช้แอปพลิเคชัน สําหรับคําขอเหล่านี้ Cloud Firestore จะใช้ Cloud Firestore Security Rules เพื่อพิจารณาว่าคําขอได้รับอนุญาตหรือไม่
ใช้โทเค็น OAuth 2.0 ของ Google Identity และบัญชีบริการเพื่อตรวจสอบสิทธิ์คําขอจากแอปพลิเคชัน เช่น คําขอการดูแลระบบฐานข้อมูล สำหรับคำขอเหล่านี้ Cloud Firestore จะใช้ Identity and Access Management (IAM) เพื่อระบุว่าคำขอได้รับอนุญาตหรือไม่
การใช้โทเค็นรหัส Firebase
คุณรับโทเค็นระบุตัวตน Firebase ได้ 2 วิธีดังนี้
- สร้างโทเค็นระบุตัวตน Firebase โดยใช้ Firebase AuthenticationREST API
- เรียกข้อมูลโทเค็นระบุตัวตน Firebase ของผู้ใช้จาก Firebase Authentication SDK
การดึงข้อมูลโทเค็นระบุตัวตน Firebase ของผู้ใช้จะช่วยให้คุณส่งคําขอในนามของผู้ใช้ได้
สําหรับคําขอที่ตรวจสอบสิทธิ์ด้วยโทเค็นระบุตัวตน Firebase และคําขอที่ไม่มีการรับรอง Cloud Firestore จะใช้ Cloud Firestore Security Rules เพื่อระบุว่าคําขอได้รับอนุญาตหรือไม่
การใช้งานโทเค็น OAuth 2.0 ของ Google Identity
คุณสามารถสร้างโทเค็นการเข้าถึงได้โดยใช้บัญชีบริการที่มีไลบรารีของไคลเอ็นต์ Google API หรือทำตามขั้นตอนในการใช้ OAuth 2.0 สําหรับแอปพลิเคชันระหว่างเซิร์ฟเวอร์กับเซิร์ฟเวอร์ นอกจากนี้ คุณยังสร้างโทเค็นด้วยเครื่องมือบรรทัดคำสั่ง gcloud และคำสั่ง gcloud auth application-default print-access-token ได้ด้วย
โทเค็นนี้ต้องมีขอบเขตต่อไปนี้เพื่อส่งคำขอไปยัง Cloud Firestore REST API
https://www.googleapis.com/auth/datastore
หากคุณตรวจสอบสิทธิ์คำขอด้วยบัญชีบริการและโทเค็น OAuth 2.0 ของข้อมูลประจำตัวของ Google Cloud Firestore จะถือว่าคำขอของคุณดำเนินการในนามของแอปพลิเคชันแทนผู้ใช้แต่ละราย Cloud Firestore อนุญาตให้คำขอเหล่านี้ไม่สนใจกฎความปลอดภัย แต่ Cloud Firestore จะใช้ IAM เพื่อกำหนดว่าคำขอได้รับอนุญาตหรือไม่
คุณควบคุมสิทธิ์การเข้าถึงของบัญชีบริการได้โดยการกำหนดCloud Firestoreบทบาท IAM
การตรวจสอบสิทธิ์ด้วยโทเค็นเพื่อการเข้าถึง
หลังจากได้รับโทเค็นระบุตัวตน Firebase หรือโทเค็น OAuth 2.0 ของข้อมูลประจำตัวของ Google แล้ว ให้ส่งโทเค็นดังกล่าวไปยังปลายทาง 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 และข้อมูลที่ขอ เมื่อคำขอล้มเหลว API Cloud Firestore จะแสดงผลรหัสสถานะ HTTP 4xx หรือ 5xx และการตอบกลับที่มีข้อมูลเกี่ยวกับข้อผิดพลาด
ตารางต่อไปนี้แสดงการดำเนินการที่แนะนำสำหรับรหัสข้อผิดพลาดแต่ละรหัส รหัสเหล่านี้ใช้กับ Cloud Firestore REST และ RPC API Cloud Firestore SDK และไลบรารีของไคลเอ็นต์อาจไม่แสดงผลรหัสข้อผิดพลาดเดียวกันเหล่านี้
| รหัสข้อผิดพลาดตามมาตรฐาน | คำอธิบาย | การดำเนินการที่แนะนำ |
|---|---|---|
ABORTED |
คําขอขัดแย้งกับคําขออื่น | สำหรับสัญญาผูกมัดที่ไม่ทำธุรกรรม: ลองส่งคำขอหรือปรับโครงสร้างโมเดลข้อมูลใหม่เพื่อลดการช่วงชิง สำหรับคำขอในธุรกรรม ลองทำธุรกรรมทั้งหมดอีกครั้งหรือปรับโครงสร้างโมเดลข้อมูลใหม่เพื่อลดการช่วงชิง |
ALREADY_EXISTS |
คำขอพยายามสร้างเอกสารที่มีอยู่แล้ว | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
DEADLINE_EXCEEDED |
เซิร์ฟเวอร์ Cloud Firestore ที่จัดการคำขอเกินกำหนดเวลาแล้ว | ลองอีกครั้งโดยใช้ Exponential Backoff |
FAILED_PRECONDITION |
คำขอไม่เป็นไปตามเงื่อนไขเบื้องต้นข้อใดข้อหนึ่ง ตัวอย่างเช่น คำขอการค้นหาอาจกำหนดให้ยังไม่ได้กำหนดดัชนี ดูช่องข้อความในการตอบกลับข้อผิดพลาดสำหรับเงื่อนไขเบื้องต้นที่ไม่สําเร็จ | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
INTERNAL |
เซิร์ฟเวอร์ Cloud Firestore แสดงข้อผิดพลาด | อย่าส่งคำขอนี้ซ้ำมากกว่า 1 ครั้ง |
INVALID_ARGUMENT |
พารามิเตอร์คำขอมีค่าที่ไม่ถูกต้อง โปรดดูช่องข้อความในการตอบกลับเกี่ยวกับข้อผิดพลาดสำหรับค่าที่ไม่ถูกต้อง | โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
NOT_FOUND |
คำขอพยายามอัปเดตเอกสารที่ไม่มีอยู่ | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
PERMISSION_DENIED |
ผู้ใช้ไม่ได้รับอนุญาตให้ส่งคำขอนี้ | โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
RESOURCE_EXHAUSTED |
โปรเจ็กต์มีโควต้าหรือความจุของภูมิภาค/หลายภูมิภาคเกิน | ตรวจสอบว่าคุณไม่ได้ใช้โควต้าของโปรเจ็กต์เกิน หากคุณใช้โควต้าของโปรเจ็กต์เกินแล้ว อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา หรือลองอีกครั้งโดยใช้การถดถอยแบบทวีคูณ |
UNAUTHENTICATED |
คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้อง | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
UNAVAILABLE |
เซิร์ฟเวอร์ Cloud Firestore แสดงข้อผิดพลาด | ลองอีกครั้งโดยใช้ Exponential Backoff |