วิธีที่ง่ายที่สุดที่จะใช้ 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 Authentication REST API
- ดึงข้อมูลโทเค็น Firebase ID ของผู้ใช้จาก SDK Firebase Authentication
การดึงข้อมูลโทเค็นระบุตัวตน 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
โทเค็นนี้ต้องมีขอบเขตต่อไปนี้เพื่อส่งคำขอไปยัง API ของ REST Cloud Firestore:
https://www.googleapis.com/auth/datastore
หากคุณตรวจสอบสิทธิ์คำขอด้วยบัญชีบริการและ Google Identity โทเค็น OAuth 2.0 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
v1.projects.databases.documents
ดำเนินการ CRUD ในเอกสาร ซึ่งคล้ายกับที่ระบุไว้ในคำแนะนำเพิ่มข้อมูลหรือรับข้อมูล
v1.projects.databases.collectionGroups.indexes
ดำเนินการกับดัชนี เช่น การสร้างดัชนีใหม่ การปิดใช้ดัชนีที่มีอยู่ หรือแสดงรายการดัชนีปัจจุบันทั้งหมด มีประโยชน์สำหรับการทำให้โครงสร้างข้อมูลเป็นแบบอัตโนมัติ การย้ายข้อมูลหรือการซิงค์ดัชนีระหว่างโปรเจ็กต์
และยังทำให้สามารถดึงข้อมูลเมตาของเอกสารได้ เช่น ลิสต์ทั้งหมด ช่องและคอลเล็กชันย่อยสําหรับเอกสารหนึ่งๆ
รหัสข้อผิดพลาด
เมื่อคำขอ Cloud Firestore สำเร็จ ระบบจะ
Cloud Firestore API แสดงรหัสสถานะ HTTP 200 OK
และ
ข้อมูลที่ขอ เมื่อคำขอล้มเหลว API ของ Cloud Firestore จะแสดงผล
รหัสสถานะ 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 |