ใช้ Cloud Firestore REST API

แม้ว่าวิธีที่ง่ายที่สุดในการใช้ Cloud Firestore คือการใช้ 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

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

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

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

หลังจากได้รับโทเค็นรหัส 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 และพารามิเตอร์ ข้อมูลที่ขอ เมื่อคำขอล้มเหลว 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