Tworzenie struktury reguł zabezpieczeń Cloud Firestore

Cloud Firestore Security Rules umożliwiają kontrolowanie dostępu do dokumentów i kolekcji w bazie danych. Elastyczna składnia reguł umożliwia tworzenie reguł, które pasują do wszystkiego – od wszystkich zapisów w całej bazie danych po operacje na konkretnym dokumencie.

W tym przewodniku opisano podstawową składnię i strukturę reguł zabezpieczeń. Połącz tę składnię z warunkami reguł zabezpieczeń, aby utworzyć kompletne zestawy reguł.

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.

Deklaracja usługi i bazy danych

Cloud Firestore Security Rules zawsze zaczynają się od tej deklaracji:

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 {
    // ...
  }
}

Deklaracja service cloud.firestore ogranicza zakres reguł do Rules, zapobiegając konfliktom między regułami Cloud Firestore Security Rules a regułami innych usług, takich jak Cloud Storage.

Deklaracja match /databases/{database}/documents określa, że reguły powinny pasować do dowolnej bazy danych reguł w projekcie. Projekt może zawierać do 100 baz danych, ale tylko pierwsza utworzona baza danych jest oznaczona jako domyślna.

Cloud Firestore Security Rules są stosowane osobno do każdej nazwanej bazy danych w projekcie. Oznacza to, że jeśli utworzysz kilka baz danych, musisz zarządzać regułami i wdrażać je osobno dla każdej z nich. Szczegółowe instrukcje wdrażania aktualizacji znajdziesz w artykule Wdrażanie aktualizacji.

Podstawowe reguły odczytu i zapisu

Reguły podstawowe składają się z instrukcji match określającej ścieżkę dokumentu i wyrażenia allow, które szczegółowo określa, kiedy dozwolony jest odczyt określonych danych:

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

Wszystkie instrukcje dopasowania powinny wskazywać dokumenty, a nie kolekcje. Instrukcja dopasowania może wskazywać konkretny dokument, jak w match /cities/SF, lub używać symboli wieloznacznych, aby wskazywać dowolny dokument w określonej ścieżce, jak w match /cities/{city}.

W powyższym przykładzie instrukcja dopasowania używa składni symbolu wieloznacznego {city}. Oznacza to, że reguła ma zastosowanie do każdego dokumentu w kolekcji cities, np. /cities/SF lub /cities/NYC. Gdy wyrażenia allow w instrukcji dopasowania zostaną ocenione, zmienna city zostanie rozwiązana do nazwy dokumentu miasta, np. SF lub NYC.

Operacje szczegółowe

W niektórych sytuacjach warto podzielić operacje read i write na bardziej szczegółowe. Na przykład aplikacja może wymagać innych warunków tworzenia dokumentu niż jego usuwania. Możesz też zezwolić na odczytywanie pojedynczych dokumentów, ale odrzucać duże zapytania.

Regułę read można podzielić na get i list, a regułę write na create, update i 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>;
    }
  }
}

Dane hierarchiczne

Dane w Regułach są uporządkowane w kolekcje dokumentów, a każdy dokument może rozszerzać hierarchię za pomocą podkolekcji. Ważne jest, aby zrozumieć, jak reguły zabezpieczeń współdziałają z danymi hierarchicznymi.

Rozważ sytuację, w której każdy dokument w kolekcji cities zawiera podkolekcję landmarks. Reguły zabezpieczeń mają zastosowanie tylko do dopasowanej ścieżki, więc ustawienia kontroli dostępu zdefiniowane w kolekcji cities nie mają zastosowania do podkolekcji landmarks. Zamiast tego napisz wyraźne reguły kontrolujące dostęp do podkolekcji:

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

W przypadku zagnieżdżania instrukcji match ścieżka wewnętrznej instrukcji match jest zawsze względna względem ścieżki zewnętrznej instrukcji match. Te zestawy reguł są więc równoważne:

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

Rekurencyjne symbole wieloznaczne

Jeśli chcesz, aby reguły były stosowane do dowolnie głębokiej hierarchii, użyj składni rekurencyjnego symbolu wieloznacznego {name=**}. Przykład:

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

W przypadku rekurencyjnej składni symbolu wieloznacznego zmienna symbolu wieloznacznego będzie zawierać cały pasujący segment ścieżki, nawet jeśli dokument znajduje się w głęboko zagnieżdżonej podkolekcji. Na przykład podane wyżej reguły będą pasować do dokumentu znajdującego się w /cities/SF/landmarks/coit_tower, a wartością zmiennej document będzie SF/landmarks/coit_tower.

Pamiętaj jednak, że działanie rekurencyjnych symboli wieloznacznych zależy od wersji reguł.

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

Jeśli używasz zapytań dotyczących grup kolekcji, musisz używać wersji 2. Zobacz Zabezpieczanie zapytań dotyczących grup kolekcji.

Nakładające się instrukcje dopasowania

Dokument może pasować do więcej niż 1 instrukcji match. Jeśli kilka wyrażeń allow pasuje do żądania, dostęp jest dozwolony, gdy dowolny z warunków ma wartość 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;
    }
  }
}

W powyższym przykładzie wszystkie operacje odczytu i zapisu w kolekcji cities będą dozwolone, ponieważ druga reguła zawsze ma wartość true, mimo że pierwsza reguła zawsze ma wartość false.

Limity reguł zabezpieczeń

Podczas pracy z regułami zabezpieczeń pamiętaj o tych limitach:

Dalsze kroki

• Napisz warunki niestandardowych reguł zabezpieczeń.
• Zapoznaj się z dokumentacją reguł zabezpieczeń.