Cloud Firestore Security Rules позволяют вам контролировать доступ к документам и коллекциям в вашей базе данных. Гибкий синтаксис правил позволяет создавать правила, соответствующие чему угодно: от всех операций записи во всю базу данных до операций над конкретным документом.
В этом руководстве описываются основной синтаксис и структура правил безопасности. Объедините этот синтаксис с условиями правил безопасности, чтобы создать полные наборы правил.
Декларация службы и базы данных
Cloud Firestore Security Rules всегда начинаются со следующего объявления:
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
Объявление service cloud.firestore распространяет правила на Cloud Firestore , предотвращая конфликты между Cloud Firestore Security Rules и правилами для других продуктов, таких как 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 может указывать на конкретный документ, как в 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 рекурсивные подстановочные знаки соответствуют одному или нескольким элементам пути. Они не соответствуют пустому пути, поэтому match /cities/{city}/{document=**} соответствует документам в подколекциях, но не в коллекции cities , тогда как match /cities/{document=**} соответствует обоим документам в коллекции. Коллекция cities и подколлекции.
Рекурсивные подстановочные знаки должны располагаться в конце оператора сопоставления.
Версия 2
В правилах безопасности версии 2 рекурсивные подстановочные знаки соответствуют нулю или более элементам пути. 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>;
}
}
}
Вы можете использовать не более одного рекурсивного подстановочного знака для каждого оператора сопоставления, но в версии 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 . В случае, когда запросу соответствует несколько выражений 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 будут разрешены, поскольку второе правило всегда true , даже если первое правило всегда false .
Ограничения правил безопасности
При работе с правилами безопасности обратите внимание на следующие ограничения:
| Лимит | Подробности |
|---|---|
Максимальное количество вызовов exists() , get() и getAfter() на запрос |
Превышение любого ограничения приводит к ошибке отказа в разрешении. Некоторые вызовы доступа к документу могут кэшироваться, и кэшированные вызовы не учитываются при расчете ограничений. |
Максимальная глубина вложенного оператора match | 10 |
Максимальная длина пути в сегментах пути, разрешенная в наборе вложенных операторов match . | 100 |
Максимальное количество переменных захвата пути, разрешенное в наборе вложенных операторов match | 20 |
| Максимальная глубина вызова функции | 20 |
| Максимальное количество аргументов функции | 7 |
Максимальное количество привязок переменных let на функцию | 10 |
| Максимальное количество рекурсивных или циклических вызовов функций | 0 (не разрешено) |
| Максимальное количество выражений, оцениваемых за запрос | 1000 |
| Максимальный размер набора правил | Наборы правил должны подчиняться двум ограничениям по размеру:
|
Следующие шаги
- Напишите условия пользовательских правил безопасности .
- Прочтите справочник правил безопасности .