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

Cloud Firestore Security Rules ช่วยให้คุณควบคุมสิทธิ์เข้าถึงเอกสารและคอลเล็กชันในฐานข้อมูลได้ ไวยากรณ์ของกฎที่ยืดหยุ่นช่วยให้คุณสร้างกฎที่ตรงกับทุกอย่างได้ ตั้งแต่การเขียนทั้งหมดไปยังฐานข้อมูลทั้งหมดไปจนถึงการดำเนินการกับเอกสารที่เฉพาะเจาะจง

คู่มือนี้จะอธิบายไวยากรณ์และโครงสร้างพื้นฐานของกฎความปลอดภัย รวมไวยากรณ์นี้เข้ากับเงื่อนไขของกฎความปลอดภัยเพื่อสร้างชุดกฎที่สมบูรณ์

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Firestore data.

การประกาศบริการและฐานข้อมูล

Cloud Firestore Security Rules จะขึ้นต้นด้วยการประกาศต่อไปนี้เสมอ

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

การประกาศ service cloud.firestore จะกำหนดขอบเขตของกฎให้เป็นกฎ ซึ่งจะป้องกันความขัดแย้งระหว่าง Cloud Firestore Security Rules กับกฎสำหรับผลิตภัณฑ์อื่นๆ เช่น Cloud Storage

การประกาศ match /databases/{database}/documents ระบุว่ากฎควรตรงกับฐานข้อมูล Rules ใดๆ ในโปรเจ็กต์ แม้ว่าโปรเจ็กต์จะมีฐานข้อมูลได้สูงสุด 100 รายการ แต่ระบบจะกำหนดให้ฐานข้อมูลแรกที่สร้างขึ้นเป็นฐานข้อมูลเริ่มต้นเท่านั้น

ระบบจะใช้ Cloud Firestore Security Rules แยกกันสำหรับฐานข้อมูลที่มีชื่อแต่ละรายการในโปรเจ็กต์ ซึ่งหมายความว่าหากคุณสร้างฐานข้อมูลหลายรายการ คุณต้องจัดการและติดตั้งใช้งานกฎสำหรับแต่ละรายการแยกกัน ดูวิธีการโดยละเอียดเกี่ยวกับการติดตั้งใช้งานการอัปเดตได้ที่ติดตั้งใช้งานการอัปเดต

กฎการอ่าน/เขียนพื้นฐาน

กฎพื้นฐานประกอบด้วยคำสั่ง 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 ทั้งหมดควรชี้ไปยังเอกสาร ไม่ใช่คอลเล็กชัน คำสั่ง match สามารถชี้ไปยังเอกสารที่เฉพาะเจาะจงได้ เช่นใน match /cities/SF หรือใช้ไวลด์การ์ดเพื่อชี้ไปยังเอกสารใดก็ได้ในเส้นทางที่ระบุ เช่นใน match /cities/{city}

ในตัวอย่างข้างต้น คำสั่งจับคู่จะใช้ไวยากรณ์ไวลด์การ์ด {city} ซึ่งหมายความว่ากฎจะมีผลกับเอกสารใดก็ได้ในคอลเล็กชัน cities เช่น /cities/SF หรือ /cities/NYC เมื่อประเมินนิพจน์ allow ในคำสั่ง match ตัวแปร 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>;
    }
  }
}

ข้อมูลแบบลำดับชั้น

ข้อมูลในกฎจะจัดระเบียบเป็นคอลเล็กชันของเอกสาร และเอกสารแต่ละรายการอาจขยายลำดับชั้นผ่านคอลเล็กชันย่อย สิ่งสำคัญคือต้องเข้าใจว่ากฎความปลอดภัยโต้ตอบกับข้อมูลแบบลำดับชั้นอย่างไร

พิจารณาสถานการณ์ที่เอกสารแต่ละรายการในคอลเล็กชัน 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

อย่างไรก็ตาม โปรดทราบว่าลักษณะการทำงานของไวลด์การ์ดแบบเรียกซ้ำจะขึ้นอยู่กับเวอร์ชันของกฎ

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>;
   }
 }
}

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 เสมอก็ตาม

ขีดจำกัดของกฎความปลอดภัย

เมื่อทำงานกับกฎความปลอดภัย โปรดคำนึงถึงขีดจำกัดต่อไปนี้

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

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