หน้านี้ได้รับการแปลโดย Cloud Translation API

การจัดโครงสร้างกฎความปลอดภัยของ Cloud Firestore

กฎความปลอดภัยของ 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()` ต่อคำขอ	10 สำหรับคำขอเอกสารและคำขอการค้นหารายการเดียว 20 สำหรับการอ่านเอกสารหลายเอกสาร ธุรกรรม และการเขียนแบบกลุ่ม ขีดจำกัดก่อนหน้านี้ที่ 10 รายการมีผลกับการดำเนินการแต่ละรายการด้วย ตัวอย่างเช่น สมมติว่าคุณสร้างคำขอเขียนแบบกลุ่มที่มีการดำเนินการเขียน 3 รายการ และกฎความปลอดภัยใช้การเรียกการเข้าถึงเอกสาร 2 ครั้งเพื่อตรวจสอบการเขียนแต่ละรายการ ในกรณีนี้ การเขียนแต่ละรายการจะใช้การเรียกการเข้าถึง 2 จาก 10 ครั้ง และคำขอเขียนแบบกลุ่มใช้การเรียกการเข้าถึง 6 จาก 20 ครั้ง หากเกินขีดจำกัดใดขีดจำกัดจะทำให้เกิดข้อผิดพลาดเกี่ยวกับสิทธิ์ถูกปฏิเสธ การเรียกการเข้าถึงเอกสารบางรายการอาจถูกแคชไว้ และไม่นับรวมการเรียกที่แคชไว้ตามขีดจำกัด
ความลึกของคำสั่ง `match` ที่ฝังสูงสุด	10
ความยาวเส้นทางสูงสุดในกลุ่มเส้นทาง อนุญาตภายในชุดคำสั่ง `match` ที่ฝังอยู่	100
จำนวนตัวแปรการบันทึกเส้นทางสูงสุดที่อนุญาตภายในชุดคำสั่ง `match` ที่ฝังอยู่	20
ความลึกของการเรียกใช้ฟังก์ชันสูงสุด	20
จำนวนอาร์กิวเมนต์ของฟังก์ชันสูงสุด	7
จำนวนการเชื่อมโยงตัวแปรสูงสุด `let` รายการต่อฟังก์ชัน	10
จำนวนสูงสุดของการเรียกใช้ฟังก์ชันแบบเวียนเกิดหรือแบบวนซ้ำ	0 (ไม่ได้รับอนุญาต&r;
จำนวนนิพจน์สูงสุดที่ประเมินต่อคำขอ	1,000 ราย
ขนาดสูงสุดของชุดกฎ	ชุดกฎต้องเป็นไปตามขีดจำกัด 2 ขนาดดังนี้ ขนาดสูงสุดของแหล่งที่มาของข้อความชุดกฎที่ 256 KB ที่เผยแพร่จากคอนโซล Firebase หรือจาก CLI โดยใช้ `firebase deploy` ขนาดชุดกฎที่คอมไพล์แล้วมีการจำกัดขนาด 250 KB ซึ่งจะส่งผลให้ เมื่อ Firebase ประมวลผลต้นทางและทำให้มีการใช้งานที่แบ็กเอนด์

ขั้นตอนถัดไป

เขียนเงื่อนไขของกฎความปลอดภัยที่กำหนดเอง
โปรดอ่านข้อมูลอ้างอิงกฎความปลอดภัย