ใช้ Cloud Firestore REST API

แม้ว่าวิธีที่ง่ายที่สุดในการใช้ 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 และคําขอที่ไม่มีการตรวจสอบสิทธิ์ Cloud Firestore จะใช้ Cloud Firestore Security Rules เพื่อระบุว่าคําขอได้รับอนุญาตหรือไม่

การใช้โทเค็น 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 Cloud Firestore จะถือว่าคำขอของคุณดำเนินการในนามของแอปพลิเคชันแทนผู้ใช้แต่ละราย Cloud Firestore อนุญาตให้คำขอเหล่านี้ไม่สนใจกฎความปลอดภัย แต่ Cloud Firestore ใช้ IAM เพื่อระบุว่าคำขอได้รับอนุญาตหรือไม่

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

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

หลังจากได้รับโทเค็นระบุตัวตน Firebase หรือโทเค็น OAuth 2.0 ของข้อมูลประจำตัวของ Google แล้ว ให้ส่งโทเค็นดังกล่าวไปยังปลายทาง Cloud Firestore ในส่วนหัว Authorization ที่ตั้งค่าเป็น Bearer {YOUR_TOKEN}

การเรียก REST

ปลายทาง REST API ทั้งหมดจะอยู่ภายใต้ 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 ซึ่งจะสร้างโทเค็น OAuth 2.0 ของ Google Identity โดยอัตโนมัติและให้คุณตรวจสอบ 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 และไลบรารีไคลเอ็นต์อาจไม่แสดงรหัสข้อผิดพลาดเดียวกันเหล่านี้

รหัสข้อผิดพลาดตามรูปแบบมาตรฐาน คำอธิบาย การดำเนินการที่แนะนำ
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