แม้ว่าวิธีที่ง่ายที่สุดในการใช้ 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 โดยใช้ REST API การตรวจสอบสิทธิ์ของ Firebase
- ดึงข้อมูลโทเค็นรหัส Firebase ของผู้ใช้จาก SDK การตรวจสอบสิทธิ์ Firebase
การเรียกโทเค็นรหัส 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 |