วิธีที่ง่ายที่สุดที่จะใช้ 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 |