แม้ว่าวิธีที่ง่ายที่สุดในการใช้ Cloud Firestore คือการใช้ไลบรารีไคลเอ็นต์เนทีฟตัวใดตัวหนึ่ง แต่ก็มีบางสถานการณ์ที่การเรียก REST API โดยตรงมีประโยชน์
REST API มีประโยชน์ในกรณีการใช้งานต่อไปนี้:
- การเข้าถึง Cloud Firestore จากสภาพแวดล้อมที่จำกัดทรัพยากร เช่น อุปกรณ์ Internet of Things (IoT) ซึ่งไม่สามารถเรียกใช้ไลบรารีไคลเอ็นต์ทั้งหมดได้
- การบริหารฐานข้อมูลอัตโนมัติหรือการดึงข้อมูลเมตาฐานข้อมูลโดยละเอียด
หากคุณใช้ ภาษาที่รองรับ gRPC ให้ลองใช้ RPC API แทน REST API
การรับรองความถูกต้องและการอนุญาต
สำหรับการตรวจสอบสิทธิ์ Cloud Firestore REST API ยอมรับโทเค็น Firebase Authentication ID หรือโทเค็น Google Identity OAuth 2.0 โทเค็นที่คุณให้ส่งผลต่อการอนุญาตคำขอของคุณ:
ใช้โทเค็น Firebase ID เพื่อตรวจสอบสิทธิ์คำขอจากผู้ใช้แอปพลิเคชันของคุณ สำหรับคำขอเหล่านี้ Cloud Firestore จะใช้ กฎความปลอดภัยของ Cloud Firestore เพื่อพิจารณาว่าคำขอนั้นได้รับอนุญาตหรือไม่
ใช้โทเค็น Google Identity OAuth 2.0 และ บัญชีบริการ เพื่อตรวจสอบสิทธิ์คำขอจากแอปพลิเคชันของคุณ เช่น คำขอสำหรับการดูแลฐานข้อมูล สำหรับคำขอเหล่านี้ Cloud Firestore จะใช้ Identity and Access Management (IAM) เพื่อพิจารณาว่าคำขอนั้นได้รับอนุญาตหรือไม่
การทำงานกับโทเค็น Firebase ID
คุณสามารถรับโทเค็น Firebase ID ได้สองวิธี:
- สร้างโทเค็น Firebase ID โดยใช้ Firebase Authentication REST API
- ดึงโทเค็น Firebase ID ของผู้ใช้จาก Firebase Authentication SDK
เมื่อเรียกข้อมูลโทเค็น Firebase ID ของผู้ใช้ คุณจะส่งคำขอในนามของผู้ใช้ได้
สำหรับคำขอที่ตรวจสอบสิทธิ์ด้วยโทเค็น Firebase ID และสำหรับคำขอที่ไม่ผ่านการตรวจสอบสิทธิ์ Cloud Firestore จะใช้ กฎความปลอดภัยของ Cloud Firestore ของคุณเพื่อพิจารณาว่าคำขอนั้นได้รับอนุญาตหรือไม่
การทำงานกับโทเค็น 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 ID หรือโทเค็น Google Identity OAuth 2.0 แล้ว ให้ส่งต่อไปยังปลายทาง Cloud Firestore เป็นส่วนหัว Authorization ที่ตั้งค่าเป็น Bearer {YOUR_TOKEN}
การโทร REST
จุดสิ้นสุด REST API ทั้งหมดอยู่ภายใต้ URL พื้นฐาน https://firestore.googleapis.com/v1/
หากต้องการสร้างเส้นทางไปยังเอกสารด้วย ID 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 ได้
วิธีการ
ด้านล่างนี้เป็นคำอธิบายโดยย่อของกลุ่มวิธีการที่สำคัญที่สุดสองกลุ่ม สำหรับรายการทั้งหมด โปรดดู ข้อมูลอ้างอิง REST API หรือใช้ API Explorer
v1.projects.databases.documents
ดำเนินการ CRUD กับเอกสาร คล้ายกับที่ระบุไว้ในการ เพิ่มข้อมูล หรือ รับคำแนะนำข้อมูล
v1.projects.databases.collectionGroups.indexes
ดำเนินการกับดัชนี เช่น การสร้างดัชนีใหม่ ปิดการใช้งานดัชนีที่มีอยู่ หรือแสดงรายการดัชนีปัจจุบันทั้งหมด มีประโยชน์สำหรับการย้ายโครงสร้างข้อมูลอัตโนมัติหรือการซิงโครไนซ์ดัชนีระหว่างโปรเจ็กต์
นอกจากนี้ยังเปิดใช้งานการดึงข้อมูลเมตาของเอกสาร เช่น รายการฟิลด์ทั้งหมดและคอลเลกชันย่อยสำหรับเอกสารที่กำหนด
รหัสข้อผิดพลาด
เมื่อคำขอ Cloud Firestore สำเร็จ Cloud Firestore API จะส่งคืนรหัสสถานะ HTTP 200 OK และข้อมูลที่ร้องขอ เมื่อคำขอล้มเหลว Cloud Firestore API จะส่งคืนรหัสสถานะ HTTP 4xx หรือ 5xx และการตอบกลับพร้อมข้อมูลเกี่ยวกับข้อผิดพลาด
ตารางต่อไปนี้แสดงรายการการดำเนินการที่แนะนำสำหรับรหัสข้อผิดพลาดแต่ละรายการ รหัสเหล่านี้ใช้กับ Cloud Firestore REST และ RPC API Cloud Firestore SDK และไลบรารีไคลเอ็นต์ อาจไม่ส่งคืนรหัสข้อผิดพลาดเดียวกันนี้
| รหัสข้อผิดพลาด Canonical | คำอธิบาย | การดำเนินการที่แนะนำ |
|---|---|---|
ABORTED | คำขอขัดแย้งกับคำขออื่น | สำหรับการกระทำที่ไม่ใช่ธุรกรรม: ลองส่งคำขออีกครั้งหรือปรับโครงสร้างโมเดลข้อมูลของคุณใหม่เพื่อลดความขัดแย้ง สำหรับการร้องขอในการทำธุรกรรม: ลองธุรกรรมทั้งหมดอีกครั้งหรือปรับโครงสร้างโมเดลข้อมูลของคุณใหม่เพื่อลดความขัดแย้ง |
ALREADY_EXISTS | คำขอพยายามสร้างเอกสารที่มีอยู่แล้ว | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
DEADLINE_EXCEEDED | เซิร์ฟเวอร์ Cloud Firestore ที่จัดการคำขอเกินกำหนดเวลา | ลองใช้การถอยกลับแบบเอ็กซ์โปเนนเชียลอีกครั้ง |
FAILED_PRECONDITION | การร้องขอไม่ตรงตามเงื่อนไขเบื้องต้นข้อใดข้อหนึ่ง ตัวอย่างเช่น คำขอสืบค้นอาจต้องมีดัชนีที่ยังไม่ได้กำหนดไว้ ดูช่องข้อความในการตอบกลับข้อผิดพลาดสำหรับเงื่อนไขเบื้องต้นที่ล้มเหลว | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
INTERNAL | เซิร์ฟเวอร์ Cloud Firestore ส่งคืนข้อผิดพลาด | อย่าลองคำขอนี้ซ้ำมากกว่าหนึ่งครั้ง |
INVALID_ARGUMENT | พารามิเตอร์คำขอมีค่าที่ไม่ถูกต้อง ดูช่องข้อความในการตอบกลับข้อผิดพลาดสำหรับค่าที่ไม่ถูกต้อง | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
NOT_FOUND | คำขอพยายามอัปเดตเอกสารที่ไม่มีอยู่ | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
PERMISSION_DENIED | ผู้ใช้ไม่ได้รับอนุญาตให้ทำการร้องขอนี้ | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
RESOURCE_EXHAUSTED | โครงการเกิน โควต้า หรือความจุของภูมิภาค/หลายภูมิภาค | ตรวจสอบว่าคุณไม่เกินโควต้าโครงการของคุณ หากคุณใช้โควต้าโครงการเกินโควต้า อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา มิฉะนั้น ให้ลองอีกครั้งโดยใช้การถอยกลับแบบเอ็กซ์โปเนนเชียล |
UNAUTHENTICATED | คำขอไม่รวมข้อมูลรับรองความถูกต้องที่ถูกต้อง | อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา |
UNAVAILABLE | เซิร์ฟเวอร์ Cloud Firestore ส่งคืนข้อผิดพลาด | ลองใช้การถอยกลับแบบเอ็กซ์โปเนนเชียลอีกครั้ง |