ใช้ Cloud Firestore REST API

แม้ว่าวิธีที่ง่ายที่สุดในการใช้ 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 และคำขอที่ไม่ได้ตรวจสอบสิทธิ์ 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 Identity Cloud Firestore จะถือว่าคำขอของคุณดำเนินการในนามของแอปพลิเคชันแทนผู้ใช้แต่ละราย Cloud Firestore อนุญาตให้คำขอเหล่านี้ไม่สนใจกฎความปลอดภัย แต่ Cloud Firestore ใช้ IAM เพื่อพิจารณาว่าคำขอได้รับอนุญาตหรือไม่

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

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

หลังจากได้รับโทเค็นรหัส Firebase หรือโทเค็น OAuth 2.0 ของ Google Identity แล้ว ให้ส่งโทเค็นไปยังปลายทาง 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 สำเร็จ API Cloud Firestore จะแสดงรหัสสถานะ 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 โปรเจ็กต์มีโควต้าหรือความจุของภูมิภาค/แบบหลายภูมิภาคเกิน ตรวจสอบว่าคุณไม่ได้ใช้โควต้าของโปรเจ็กต์เกิน หากคุณใช้โควต้าโปรเจ็กต์เกินแล้ว อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา

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