Структурирование правил безопасности Cloud Firestore

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

Однако следует отметить, что поведение рекурсивных подстановочных знаков зависит от версии правил.

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 . Если запросу соответствует несколько выражений 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 .

Ограничения правил безопасности

При работе с правилами безопасности обратите внимание на следующие ограничения:

Следующие шаги

• Напишите пользовательские условия правил безопасности .
• Ознакомьтесь со справочником правил безопасности .