กฎความปลอดภัยของ Cloud Firestore ช่วยให้คุณควบคุมการเข้าถึงเอกสารและคอลเล็กชันในฐานข้อมูลได้ ไวยากรณ์กฎที่ยืดหยุ่นช่วยให้คุณสร้างกฎที่ตรงกับอะไรก็ได้ ตั้งแต่การเขียนทั้งหมดไปจนถึงฐานข้อมูลทั้งหมดไปจนถึงการดำเนินการในเอกสารที่เฉพาะเจาะจง
คู่มือนี้จะอธิบายไวยากรณ์และโครงสร้างพื้นฐานของกฎความปลอดภัย รวมไวยากรณ์นี้กับเงื่อนไขกฎความปลอดภัยเพื่อสร้างชุดกฎที่สมบูรณ์
การประกาศบริการและฐานข้อมูล
กฎความปลอดภัยของ Cloud Firestore จะเริ่มต้นด้วยการประกาศต่อไปนี้เสมอ
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
การประกาศ service cloud.firestore
กำหนดขอบเขตของกฎไปยัง Cloud Firestore เพื่อป้องกันความขัดแย้งระหว่างกฎความปลอดภัยของ Cloud Firestore กับกฎสำหรับผลิตภัณฑ์อื่นๆ เช่น Cloud Storage
การประกาศ match /databases/{database}/documents
ระบุว่ากฎควรตรงกับฐานข้อมูล Cloud Firestore ทั้งหมดในโปรเจ็กต์ ปัจจุบันแต่ละโปรเจ็กต์มีเพียงฐานข้อมูลเดียวที่ชื่อว่า (default)
กฎการอ่าน/เขียนพื้นฐาน
กฎพื้นฐานประกอบด้วยคำสั่ง match
ที่ระบุเส้นทางของเอกสารและนิพจน์ allow
ที่มีรายละเอียดเมื่ออ่านข้อมูลที่ระบุ
service cloud.firestore {
match /databases/{database}/documents {
// Match any document in the 'cities' collection
match /cities/{city} {
allow read: if <condition>;
allow write: if <condition>;
}
}
}
ข้อความที่ตรงกันทั้งหมดควรชี้ไปยังเอกสาร ไม่ใช่คอลเล็กชัน คำสั่งที่ตรงกันจะชี้ไปยังเอกสารที่ระบุได้ เช่น ใน match /cities/SF
หรือใช้ไวลด์การ์ดเพื่อชี้ไปยังเอกสารใดก็ได้ในเส้นทางที่ระบุ เช่น match /cities/{city}
ในตัวอย่างด้านบน คำสั่งจับคู่จะใช้ไวยากรณ์ไวลด์การ์ด {city}
กฎนี้จะมีผลกับเอกสารในคอลเล็กชัน cities
เช่น /cities/SF
หรือ /cities/NYC
เมื่อประเมินนิพจน์ allow
ในคำสั่งการจับคู่ ตัวแปร city
จะเปลี่ยนเป็นชื่อเอกสารของเมือง เช่น SF
หรือ NYC
การดำเนินการแบบละเอียด
ในบางสถานการณ์ การจำแนก read
และ write
เป็นการดำเนินการที่ละเอียดขึ้นอาจมีประโยชน์ ตัวอย่างเช่น แอปของคุณอาจต้องการบังคับใช้เงื่อนไขในการสร้างเอกสารที่แตกต่างจากการลบเอกสาร หรือคุณอาจต้องการอนุญาตให้อ่านเอกสารรายการเดียว แต่ปฏิเสธการค้นหาขนาดใหญ่
คุณสร้างกฎ read
ออกเป็น get
และ list
ได้ แต่จะแบ่งกฎ write
ออกเป็น create
, update
และ delete
ได้ดังนี้
service cloud.firestore {
match /databases/{database}/documents {
// A read rule can be divided into get and list rules
match /cities/{city} {
// Applies to single document read requests
allow get: if <condition>;
// Applies to queries and collection read requests
allow list: if <condition>;
}
// A write rule can be divided into create, update, and delete rules
match /cities/{city} {
// Applies to writes to nonexistent documents
allow create: if <condition>;
// Applies to writes to existing documents
allow update: if <condition>;
// Applies to delete operations
allow delete: if <condition>;
}
}
}
ข้อมูลตามลําดับชั้น
ข้อมูลใน Cloud Firestore จะจัดระเบียบเป็นคอลเล็กชันของเอกสาร และเอกสารแต่ละรายการอาจขยายลำดับชั้นผ่านคอลเล็กชันย่อย คุณควรเข้าใจว่ากฎความปลอดภัยโต้ตอบกับข้อมูลตามลำดับชั้นอย่างไร
ลองพิจารณาสถานการณ์ที่เอกสารแต่ละรายการในคอลเล็กชัน cities
มีคอลเล็กชันย่อย landmarks
กฎความปลอดภัยจะมีผลกับเส้นทางที่ตรงกันเท่านั้น ดังนั้นการควบคุมการเข้าถึงที่กำหนดไว้ในคอลเล็กชัน cities
จึงไม่มีผลกับคอลเล็กชันย่อย landmarks
แต่ให้เขียนกฎที่ชัดเจนเพื่อควบคุมการเข้าถึงคอลเล็กชันย่อยแทน ดังนี้
service cloud.firestore {
match /databases/{database}/documents {
match /cities/{city} {
allow read, write: if <condition>;
// Explicitly define rules for the 'landmarks' subcollection
match /landmarks/{landmark} {
allow read, write: if <condition>;
}
}
}
}
เมื่อซ้อนคำสั่ง match
เส้นทางของคำสั่ง match
ภายในจะสัมพันธ์กับเส้นทางของคำสั่ง match
ด้านนอกเสมอ ดังนั้นชุดกฎต่อไปนี้
จึงเทียบเท่ากัน
service cloud.firestore {
match /databases/{database}/documents {
match /cities/{city} {
match /landmarks/{landmark} {
allow read, write: if <condition>;
}
}
}
}
service cloud.firestore {
match /databases/{database}/documents {
match /cities/{city}/landmarks/{landmark} {
allow read, write: if <condition>;
}
}
}
ไวลด์การ์ดที่เกิดซ้ำ
หากต้องการใช้กฎกับลำดับชั้นลึกที่กำหนดเอง ให้ใช้ไวยากรณ์ไวลด์การ์ดแบบเวียนเกิด {name=**}
ตัวอย่างเช่น
service cloud.firestore {
match /databases/{database}/documents {
// Matches any document in the cities collection as well as any document
// in a subcollection.
match /cities/{document=**} {
allow read, write: if <condition>;
}
}
}
เมื่อใช้ไวยากรณ์ไวลด์การ์ดที่เกิดซ้ำ ตัวแปรไวลด์การ์ดจะมีกลุ่มเส้นทางที่ตรงกันทั้งหมด แม้ว่าเอกสารจะอยู่ในคอลเล็กชันย่อยที่ฝังหลายระดับก็ตาม เช่น กฎที่แสดงด้านบนจะตรงกับเอกสารที่ /cities/SF/landmarks/coit_tower
และค่าของตัวแปร document
จะเป็น SF/landmarks/coit_tower
อย่างไรก็ตาม โปรดทราบว่าลักษณะการทำงานของไวลด์การ์ดที่เกิดซ้ำจะขึ้นอยู่กับเวอร์ชันของกฎ
เวอร์ชัน 1
กฎความปลอดภัยจะใช้เวอร์ชัน 1 โดยค่าเริ่มต้น ในเวอร์ชัน 1 ไวลด์การ์ดที่เกิดซ้ำ
จะตรงกับรายการเส้นทางอย่างน้อย 1 รายการ ซึ่งไม่ตรงกับเส้นทางที่ว่างเปล่า ดังนั้น match /cities/{city}/{document=**}
จะจับคู่เอกสารในคอลเล็กชันย่อย แต่ไม่ตรงกับในคอลเล็กชัน cities
ในขณะที่ match /cities/{document=**}
จะจับคู่ทั้งเอกสารในคอลเล็กชัน cities
และคอลเล็กชันย่อย
ไวลด์การ์ดที่เกิดซ้ำต้องอยู่ท้ายคำสั่งการจับคู่
เวอร์ชัน 2
ในกฎความปลอดภัยเวอร์ชัน 2 ไวลด์การ์ดที่เกิดซ้ำจะจับคู่กับรายการเส้นทาง 0 รายการขึ้นไป match/cities/{city}/{document=**}
จะจับคู่เอกสารในคอลเล็กชันย่อย เช่นเดียวกับเอกสารในคอลเล็กชัน cities
คุณต้องเลือกใช้เวอร์ชัน 2 โดยเพิ่ม rules_version = '2';
ที่ด้านบนของกฎความปลอดภัย ดังนี้
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// Matches any document in the cities collection as well as any document
// in a subcollection.
match /cities/{city}/{document=**} {
allow read, write: if <condition>;
}
}
}
คุณมีคำสั่งไวลด์การ์ดซ้ำได้สูงสุด 1 รายการต่อคำสั่งการจับคู่ แต่ในเวอร์ชัน 2 คุณจะวางไวลด์การ์ดนี้ไว้ที่ใดก็ได้ในคำสั่งการจับคู่ ตัวอย่างเช่น
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// Matches any document in the songs collection group
match /{path=**}/songs/{song} {
allow read, write: if <condition>;
}
}
}
หากใช้การค้นหากลุ่มคอลเล็กชัน คุณต้องใช้เวอร์ชัน 2 โปรดดูการรักษาความปลอดภัยการค้นหากลุ่มคอลเล็กชัน
ข้อความการจับคู่ที่ทับซ้อนกัน
เอกสารอาจตรงกับคำสั่ง match
มากกว่า 1 รายการ ในกรณีที่นิพจน์ allow
หลายรายการตรงกับคำขอ ระบบจะอนุญาตให้เข้าถึงหากเงื่อนไขใดๆ เป็น true
ดังนี้
service cloud.firestore {
match /databases/{database}/documents {
// Matches any document in the 'cities' collection.
match /cities/{city} {
allow read, write: if false;
}
// Matches any document in the 'cities' collection or subcollections.
match /cities/{document=**} {
allow read, write: if true;
}
}
}
ในตัวอย่างด้านบน ระบบจะอนุญาตการอ่านและเขียนทั้งหมดในคอลเล็กชัน cities
เนื่องจากกฎที่ 2 คือ true
เสมอ แม้ว่ากฎแรกจะเป็น false
เสมอก็ตาม
ขีดจำกัดของกฎความปลอดภัย
โปรดคำนึงถึงขีดจำกัดต่อไปนี้เมื่อทำงานกับกฎความปลอดภัย
ขีดจำกัด | รายละเอียด |
---|---|
จำนวนการโทรสูงสุด exists() , get() และ getAfter() ต่อคำขอ |
หากเกินขีดจำกัดใดขีดจำกัดจะทำให้เกิดข้อผิดพลาดเกี่ยวกับสิทธิ์ถูกปฏิเสธ การเรียกการเข้าถึงเอกสารบางรายการอาจถูกแคชไว้ และไม่นับรวมการเรียกที่แคชไว้ตามขีดจำกัด |
ความลึกของคำสั่ง match ที่ฝังสูงสุด |
10 |
ความยาวเส้นทางสูงสุดในกลุ่มเส้นทาง อนุญาตภายในชุดคำสั่ง match ที่ฝังอยู่ |
100 |
จำนวนตัวแปรการบันทึกเส้นทางสูงสุดที่อนุญาตภายในชุดคำสั่ง match ที่ฝังอยู่ |
20 |
ความลึกของการเรียกใช้ฟังก์ชันสูงสุด | 20 |
จำนวนอาร์กิวเมนต์ของฟังก์ชันสูงสุด | 7 |
จำนวนการเชื่อมโยงตัวแปรสูงสุด let รายการต่อฟังก์ชัน |
10 |
จำนวนสูงสุดของการเรียกใช้ฟังก์ชันแบบเวียนเกิดหรือแบบวนซ้ำ | 0 (ไม่ได้รับอนุญาต&r; |
จำนวนนิพจน์สูงสุดที่ประเมินต่อคำขอ | 1,000 ราย |
ขนาดสูงสุดของชุดกฎ | ชุดกฎต้องเป็นไปตามขีดจำกัด 2 ขนาดดังนี้
|