ใช้ Cloud Firestore REST API

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

REST API มีประโยชน์สำหรับกรณีการใช้งานต่อไปนี้

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

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

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

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

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

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

การทำงานกับโทเค็น Firebase ID

คุณรับโทเค็น Firebase ID ได้ 2 วิธีดังนี้

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

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

การทำงานกับโทเค็น OAuth 2.0 ของ Google Identity

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

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

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

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

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

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

หลังจากได้รับโทเค็น Firebase ID หรือโทเค็น 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 ซึ่งจะสร้างโทเค็น OAuth 2.0 ของ Google Identity โดยอัตโนมัติและช่วยให้คุณตรวจสอบ API ได้

เมธอด

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

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

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

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

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

รหัสข้อผิดพลาด Canonical คำอธิบาย การดำเนินการที่แนะนำ
ABORTED คำขอขัดแย้งกับคำขออื่น สำหรับคอมมิตที่ไม่ใช่ธุรกรรม:
ลองส่งคำขออีกครั้งหรือปรับโครงสร้างโมเดลข้อมูลเพื่อลดการช่วงชิงทรัพยากร

สำหรับคำขอในธุรกรรม:
ลองทำธุรกรรมทั้งหมดอีกครั้งหรือปรับโครงสร้างโมเดลข้อมูลเพื่อลดการช่วงชิงทรัพยากร
ALREADY_EXISTS คำขอพยายามสร้างเอกสารที่มีอยู่แล้ว อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
DEADLINE_EXCEEDED เซิร์ฟเวอร์ Cloud Firestore ที่จัดการคำขอเกินกำหนดเวลา ลองอีกครั้งโดยใช้ Exponential Backoff
FAILED_PRECONDITION คำขอไม่เป็นไปตามเงื่อนไขเบื้องต้นข้อใดข้อหนึ่ง เช่น คำขอการค้นหาอาจต้องใช้ดัชนีที่ยังไม่ได้กำหนด ดูช่องข้อความในการตอบกลับข้อผิดพลาดสำหรับเงื่อนไขเบื้องต้นที่ไม่สำเร็จ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
INTERNAL เซิร์ฟเวอร์ Cloud Firestore แสดงข้อผิดพลาด อย่าลองส่งคำขอนี้ซ้ำเกิน 1 ครั้ง
INVALID_ARGUMENT พารามิเตอร์คำขอมีค่าที่ไม่ถูกต้อง ดูช่องข้อความในการตอบกลับข้อผิดพลาดสำหรับค่าที่ไม่ถูกต้อง อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
NOT_FOUND คำขอพยายามอัปเดตเอกสารที่ไม่มีอยู่ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
PERMISSION_DENIED ผู้ใช้ไม่ได้รับอนุญาตให้ส่งคำขอนี้ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
RESOURCE_EXHAUSTED โปรเจ็กต์มีโควต้าหรือความจุระดับภูมิภาค/หลายภูมิภาคเกินขีดจำกัด ตรวจสอบว่าคุณไม่ได้ใช้เกินโควต้าของโปรเจ็กต์ หากคุณใช้โควต้าโปรเจ็กต์เกินขีดจำกัด อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา

มิฉะนั้น ให้ลองอีกครั้งด้วย Exponential Backoff
UNAUTHENTICATED คำขอไม่มีข้อมูลรับรองการตรวจสอบสิทธิ์ที่ถูกต้อง อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
UNAVAILABLE เซิร์ฟเวอร์ Cloud Firestore แสดงข้อผิดพลาด ลองอีกครั้งโดยใช้ Exponential Backoff