ใช้ Cloud Firestore REST API

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

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

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

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

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

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

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

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

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

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

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

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

การใช้งานโทเค็น 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

ปลายทาง API ของ REST ทั้งหมดจะอยู่ภายใต้ 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 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 ที่จัดการคำขอเกินกำหนดเวลาแล้ว โปรดลองอีกครั้งโดยใช้ Exponential Backoff
FAILED_PRECONDITION คำขอไม่เป็นไปตามเงื่อนไขล่วงหน้าข้อใดข้อหนึ่ง ตัวอย่างเช่น คำขอการค้นหาอาจกำหนดให้ยังไม่ได้กำหนดดัชนี ดูช่องข้อความในการตอบกลับเกี่ยวกับข้อผิดพลาดสำหรับเงื่อนไขล่วงหน้าที่ดำเนินการไม่สำเร็จ โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
INTERNAL เซิร์ฟเวอร์ Cloud Firestore แสดงผลข้อผิดพลาด อย่าลองทำคำขอนี้ซ้ำมากกว่า 1 ครั้ง
INVALID_ARGUMENT พารามิเตอร์คำขอมีค่าที่ไม่ถูกต้อง โปรดดูช่องข้อความในการตอบกลับเกี่ยวกับข้อผิดพลาดสำหรับค่าที่ไม่ถูกต้อง โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
NOT_FOUND คำขอนี้พยายามอัปเดตเอกสารที่ไม่มีอยู่ โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
PERMISSION_DENIED ผู้ใช้ไม่ได้รับอนุญาตให้ส่งคำขอนี้ โปรดอย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
RESOURCE_EXHAUSTED โปรเจ็กต์นี้มีโควต้าเกินโควต้าหรือความจุของภูมิภาค/หลายภูมิภาคแล้ว ตรวจสอบว่าไม่ได้เกินโควต้าของโปรเจ็กต์ หากโปรเจ็กต์เกินโควต้าแล้ว อย่าลองอีกครั้งโดยไม่แก้ปัญหา

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