此页面由 Cloud Translation API 翻译。

面向 Cloud Storage 的 Firebase 安全规则参考

Cloud Storage 的 Firebase Security Rules 用于确定谁具有读写权限存储在 Cloud Storage 中的文件，以及文件的结构以及其中包含的元数据Cloud Storage Security Rules由多个规则组成可以考虑使用 request 和 resource 来允许或拒绝所需的操作，例如例如上传文件或检索文件元数据。这些参考文档的内容包括规则类型、request 和 resource 的属性、数据 Cloud Storage Security Rules 使用的类型以及错误的发生方式。

规则

rule 是一个表达式，用于评估以确定 request 是否执行所需的操作。

类型

允许

allow 规则包含一个方法（例如 read 或 write），可选条件。在执行规则时，系统会评估条件，并且如果条件的计算结果为 true，则允许使用所需方法；否则此方法会被拒绝。不含条件的 allow 规则始终允许所需的方法

// Always allow method
allow <method>;

// Allow method if condition is true
allow <method>: if <condition>;

目前，allow 是唯一支持的规则类型。

请求方法

Read

read 方法涵盖读取文件数据或元数据的所有请求，包括文件下载和文件元数据读取。

// Always allow reads
allow read;

// Allow reads if condition evaluates to true
allow read: if <condition>;

Write

write 方法涵盖写入文件数据或元数据的所有请求，包括文件上传、文件删除和文件元数据更新。

// Always allow writes
allow write;

// Allow writes if condition evaluates to true
allow write: if <condition>;

Match

当用户 request（例如文件上传或下载）时，系统会执行规则与规则覆盖的文件路径匹配。match 由路径和正文组成，该模板必须至少包含一条 allow 规则。如果没有匹配的路径，则请求已被拒绝。

您可以使用 match 完整命名路径，也可以插入通配符以匹配所有路径符合特定模式的路径。

路径细分

`single_segment`

您可以使用单路径段来创建与存储的文件匹配的规则在 Cloud Storage 中。

// Allow read at "path" if condition evaluates to true
match /path {
  allow read: if <condition>;
}

也允许使用多个路径段和嵌套路径：

// Allow read at "path/to/object" if condition evaluates to true
match /path {
  match /to {
    match /object {
      allow read: if <condition>;
    }
  }
}

`{single_segment_wildcard}`

如果要将规则应用于同一路径下的多个文件，您可以使用通配符路径段以匹配特定路径下的所有文件。通配符变量将变量用大括号括起来，可在路径中进行声明：{variable}。此变量可作为 string 在 match 语句中访问。

// Allow read at any path "/*", if condition evaluates to true
match /{single_path} {
  // Matches "path", "to", or "object" but not "path/to/object"
  allow read: if <condition>;
}

多个路径段和嵌套路径也可以包含通配符：

// Allow read at any path "/path/*/newPath/*", if condition evaluates to true
match /path/{first_wildcard} {
  match /newPath/{second_wildcard} {
    // Matches "path/to/newPath/newObject" or "path/from/newPath/oldObject"
    allow read: if <condition>;
  }
}

`{multi_segment_wildcard=**}`

如果要在路径上或路径之下匹配任意数量的路径段，您可以使用多段通配符，该通配符将匹配所有位置。这对于为用户提供自己的自由形式非常有用或创建与许多不同路径段（例如创建一组可公开读取的文件，或要求对所有写入操作）。

多段通配符路径的声明方式与单段类似。通配符，并在变量末尾添加 =**： {variable=**}。匹配中有一个多段通配符变量声明为 path 对象。

// Allow read at any path "/**", if condition evaluates to true
match /{multi_path=**} {
  // Matches anything at or below this, from "path", "path/to", "path/to/object", ...
  allow read: if <condition>;
}

请求

request 变量在条件内提供，用于表示请求。request 变量包含很多属性，可用于决定是否允许传入请求。

属性

`auth`

当经过身份验证的用户针对 Cloud Storage 发出请求时， auth 变量由用户的 uid (request.auth.uid) 填充，如下所示以及 Firebase Authentication JWT (request.auth.token) 的声明。

request.auth.token 包含以下部分或全部键：

字段	说明
`email`	与账号关联的电子邮件地址（如果存在）。
`email_verified`	如果用户已验证他们可以访问 `email` 地址，则为 `true`。某些提供方会自动验证他们拥有的电子邮件地址。
`phone_number`	与账号关联的电话号码（如果有）。
`name`	用户的显示名（如果已设置）。
`sub`	用户的 Firebase UID。此 UID 在项目中是唯一的。
`firebase.identities`	与此用户账号关联的所有身份的字典。字典的键可以是以下任一值：`email`、`phone`、`google.com`、`facebook.com`、`github.com`、`twitter.com`。字典的值是与账号关联的每个身份提供方的唯一标识符的数组。例如，`auth.token.firebase.identities["google.com"][0]` 包含与该账号关联的第一个 Google 用户 ID。
`firebase.sign_in_provider`	用于获取此令牌的登录服务提供方。可以是以下任一字符串：`custom`、`password`、`phone`、`anonymous`、`google.com`、`facebook.com`、`github.com`、`twitter.com`。
`firebase.tenant`	与账号关联的租户 ID（如有）。例如 `tenant2-m6tyz`

如果使用自定义身份验证，request.auth.token 还包含任何自定义声明。

当未经身份验证的用户发出请求时，request.auth 为 null。

// Allow requests from authenticated users
allow read, write: if request.auth != null;

`path`

path 变量包含正在执行 request 的路径。

// Allow a request if the first path segment equals "images"
allow read, write: if request.path[0] == 'images';

`resource`

resource 变量包含正在上传的文件的元数据或更新现有文件的元数据。这与 resource 变量，该变量包含当前的文件元数据，而不是新的元数据。

// Allow a request if the new value is smaller than 5MB
allow read, write: if request.resource.size < 5 * 1024 * 1024;

request.resource 包含 resource 中的以下属性：

属性
`name`
`bucket`
`metadata`
`size`
`contentType`

`time`

time 变量包含表示当前服务器时间的时间戳请求的评估时间。你可以用它来提供基于时间的访问权限文件，例如：仅允许在某个特定日期之前上传文件；或者仅允许在文件上传后最长一小时内读取文件。

// Allow a read if the file was created less than one hour ago
allow read: if request.time < resource.timeCreated + duration.value(1, 'h');

提供许多函数来使用时间戳和时长。

资源

resource 变量包含以下项目的文件元数据： Cloud Storage，例如文件名、大小、创建时间和自定义元数据

属性

`name`

包含文件全名（包括文件路径）的字符串。

// Allow reads if the resource name is "path/to/object"
allow read: if resource.name == 'path/to/object'

`bucket`

包含 Google Cloud Storage 的字符串存储此文件的存储分区中。

// Allow reads of all resources in your bucket
allow read: if resource.bucket == '<your-cloud-storage-bucket>'

`generation`

包含 Google Cloud Storage 的 int 对象生成文件。用于对象版本控制。

// Allow reads if the resource matches a known object version
allow read: if resource.generation == <known-generation>

`metageneration`

包含 Google Cloud Storage 的 int 对象元数据生成文件副本。用于对象版本控制。

// Allow reads if the resource matches a known object metadata version
allow read: if resource.metageneration == <known-generation>

`size`

包含文件大小（以字节为单位）的整数。

// Allow reads if the resource is less than 10 MB
allow read: if resource.size < 10 * 1024 * 1024;

`timeCreated`

表示文件的创建时间的时间戳。

// Allow reads if the resource was created less than an hour ago
allow read: if resource.timeCreated < request.time + duration.value(60, "m")

`updated`

表示文件上次更新时间的时间戳。

// Allow reads if the resource was updated less than an hour ago
allow read: if resource.updated < request.time + duration.value(60, "m")

`md5Hash`

一个包含文件。

// Allow writes if the hash of the uploaded file is the same as the existing file
allow write: if request.resource.md5Hash == resource.md5Hash;

`crc32c`

包含 crc32c hash 文件。

// Allow writes if the hash of the uploaded file is the same as the existing file
allow write: if request.resource.crc32c == resource.crc32c;

`etag`

一个包含 etag 的字符串，文件。

// Allow writes if the etag matches a known object etag
allow write: if resource.etag == <known-generation>

`contentDisposition`

包含文件内容处置的字符串。

// Allow reads if the content disposition matches a certain value
allow read: if resource.contentDisposition == 'inlined';

`contentEncoding`

包含文件内容编码的字符串。

// Allow reads if the content is encoded with gzip
allow read: if resource.contentEncoding == 'gzip';

`contentLanguage`

包含文件内容语言的字符串。

// Allow reads if the content language is Japanese
allow read: if resource.contentLanguage == 'ja';

`contentType`

包含文件内容类型的字符串。

// Allow reads if the content type is PNG.
allow read: if resource.contentType == 'image/png';

`metadata`

一个包含开发者提供的其他元数据的 Map<String, String> 字段。

// Allow reads if a certain metadata field matches a desired value
allow read: if resource.metadata.customProperty == 'customValue';

firestore.get 和 firestore.exists

借助 firestore.get() 和 firestore.exists() 函数，您可以访问 Cloud Firestore 中的文档，以评估复杂的授权标准。

firestore.get() 和 firestore.exists() 函数都需要完全指定的文档路径。使用变量为 firestore.get() 和 firestore.exists()，您需要显式转义变量使用 $(variable) 语法。

Firestore.get

获取 Cloud Firestore 文档的内容。

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{club}/files/{fileId} {
      allow read: if club in
        firestore.get(/databases/(default)/documents/users/$(request.auth.uid)).data.memberships
    }
  }
}

Firestore.exists

检查 Cloud Firestore 文档是否存在。

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/photos/{fileId} {
      allow read: if
        firestore.exists(/databases/(default)/documents/users/$(userId)/friends/$(request.auth.uid))
    }
  }
}

Service

service 是 Cloud Storage Security Rules 文件中的第一个声明，指定这些规则将应用于哪些服务。

名称

`name`

服务规则的名称将应用于。唯一的当前值是 firebase.storage。

// Specify the service name
service firebase.storage {
  match /b/{bucket}/o {
    ...
  }
}

数据类型

Rules 语言允许您使用 is 运算符检查类型。

// For example
a is null
a is string

`null`

null 数据类型表示不存在的值。

allow read: if request.auth != null;

`bool`

bool 类型表示布尔值 true 或 false。

allow read: if true;   // always succeeds
allow write: if false; // always fails

比较

您可以使用 == 运算符 != 比较布尔值。

布尔值运算

操作	表达式
`AND`	`x && y`
`OR`	`x \|\| y`
`NOT`	`!x`

操作短路，可以返回 true、false 或错误。

allow read: if true || false;   // always succeeds, short circuits at true
allow write: if false && true; // always fails, short circuits at false

`int`和`float`

int 和 float 类型表示数字。整数包括 0、1、-2 等。，而浮点数为 1.0、-2.0、3.33 等。

整数是有符号的 64 位值，浮点值是符合 64 位 IEEE 754 标准的值。在比较运算中使用时，int 类型的值将被强制转换为 float 值为 float 的算术运算。

比较

您可以使用 ==、!=、>、< 比较整数和浮点数，并对其进行排序。 >= 和 <= 运算符。

算术

整数和浮点数可以进行加减法运算、乘法、除法、取模和运算；否定：

操作	表达式
添加	`x + y`
减	`x - y`
乘	`x * y`
除	`x / y`
取模	`x % y`
取反	`-x`

数学函数

Cloud Storage 的 Firebase Security Rules 还提供了许多数学帮助程序以下函数来简化表达式：

函数	说明
`math.ceil(x)`	数值的上限
`math.floor(x)`	数值的底价
`math.round(x)`	将输入值四舍五入为最接近的整数
`math.abs(x)`	输入的绝对值
`math.isInfinite(x)`	测试值是否为 `±∞`，会返回 `bool`
`math.isNaN(x)`	测试值是否不是数字 `NaN`，返回 `bool`

`string`

比较

您可以使用 ==、!=、>、<、>= 和 <= 运算符。

串联

可以使用 + 运算符串联字符串。

// Concatenate a file name and extension
'file' + '.txt'

索引和范围

index 运算符 string[] 会返回包含字符。

// Allow reads of files that begin with 'a'
match /{fileName} {
  allow read: if fileName[0] == 'a';
}

range 运算符 string[i:j] 会返回一个包含指定索引之间的个字符，范围为 i（含）到 j （不含边界值）。如果未指定 i 或 j，则它们会默认为 0，而字符串，但必须至少指定 i 或 j 才能使范围有效。

// Allow reads of files that begin with 'abcdef'
match /{fileName} {
  allow read: if fileName[0:6] == 'abcdef';
}

如果提供索引，index 和 range 运算符会产生错误超出字符串边界。

`size`

返回字符串中的字符数。

// Allow files with names less than 10 characters
match /{fileName} {
  allow write: if fileName.size() < 10;
}

`matches`

执行正则表达式匹配，如果字符串与true 指定正则表达式用途 Google RE2 语法。

// Allow writes to files which end in ".txt"
match /{fileName} {
  allow write: if fileName.matches('.*\\.txt')
}

`split`

根据提供的正则表达式拆分字符串并返回 list 字符串。使用 Google RE2 语法。

// Allow files named "file.*" to be uploaded
match /{fileName} {
  allow write: if fileName.split('.*\\..*')[0] == 'file'
}

`path`

路径是类似于目录的名称，具有可选的模式匹配。通过正斜杠 / 表示路径段的开头。

`path`

将 string 参数转换为 path。

// Allow reads on a specific file path
match /{allFiles=**} {
  allow read: if allFiles == path('/path/to/file');
}

`timestamp`

时间戳采用世界协调时间 (UTC)，可能的值从 0001-01-01T00.00.00Z 开始收货地址为 9999-12-31T23.59.59Z。

比较

您可以使用 ==、!=、>、<、>= 和 <= 运算符。

算术

时间戳支持在时间戳和时长之间进行加减运算，如如下：

表达式	结果
`timestamp + duration`	`timestamp`
`duration + timestamp`	`timestamp`
`timestamp - duration`	`timestamp`
`timestamp - timestamp`	`duration`
`duration + duration`	`duration`
`duration - duration`	`duration`

`date`

timestamp 值，仅包含 year、month 和 day。

// Allow reads on the same day that the resource was created.
allow read: if request.time.date() == resource.timeCreated.date()

`year`

以整数表示的年份值，介于 1 到 9999 之间。

// Allow reads on all requests made before 2017
allow read: if request.time.year() < 2017

`month`

以整数形式表示的月份值，介于 1 到 12 之间。

// Allow reads on all requests made during the month of January
allow read: if request.time.month() == 1;

`day`

一个月中的当前日期，以整数表示，介于 1 到 31 之间。

// Allow reads on all requests made during the first day of each month
allow read: if request.time.day() == 1;

`time`

包含当前时间的 duration 值。

// Allow reads on all requests made before 12PM
allow read: if request.time.time() < duration.time(12, 0, 0, 0);

`hours`

以整数形式表示的小时值，范围为 0 到 23。

// Allow reads on all requests made before 12PM
allow read: if request.time.hours() < 12;

`minutes`

以整数表示的分钟数值，范围为 0 到 59。

// Allow reads during even minutes of every hour
allow read: if request.time.minutes() % 2 == 0;

`seconds`

以整数形式表示的秒值，范围为 0 到 59。

// Allow reads during the second half of each minute
allow read: if request.time.seconds() > 29;

`nanos`

以纳秒为单位的小数秒，以整数表示。

// Allow reads during the first 0.1 seconds of each second
allow read: if request.time.nanos() < 100000000;

`dayOfWeek`

周几，从 1（星期一）到 7（星期日）

// Allow reads on weekdays (Monday to Friday)
allow read: if request.time.dayOfWeek() < 6;

`dayOfYear`

当前一年中的第几天，从 1 到 366。

// Allow reads every fourth day
allow read: if request.time.dayOfYear() % 4 == 0;

`toMillis`

返回自 Unix 公元纪年以来的当前毫秒数。

// Allow reads if the request is made before a specified time
allow read: if request.time.toMillis() < <milliseconds>;

`duration`

时长值以秒加上小数秒的形式表示，纳秒。

比较

您可以使用 ==、!=、>、<、>= 和 <= 运算符。

算术

时长支持在时间戳和时长之间进行加减运算，例如如下：

表达式	结果
`timestamp + duration`	`timestamp`
`duration + timestamp`	`timestamp`
`timestamp - duration`	`timestamp`
`timestamp - timestamp`	`duration`
`duration + duration`	`duration`
`duration - duration`	`duration`

`seconds`

当前时长的秒数。必须介于 -315,576,000,000 之间和 +315,576,000,000（含）之间的流量。

`nanos`

当前时长的小数秒（以纳秒为单位）。必须介于 -999,999,999 和 +999,999,999（含）之间。对于非零秒和非零纳秒，则两者的迹象必须一致。

`duration.value`

可以使用 duration.value(int magnitude, string units) 创建时长函数，该函数基于给定量级和单位创建持续时间。

// All of these durations represent one hour:
duration.value(1, "h")
duration.value(60, "m")
duration.value(3600, "s")

可能的 unit 包括：

时长	`unit`
周	`w`
天	`d`
小时	`h`
分钟	`m`
秒	`s`
毫秒	`ms`
纳秒	`ns`

`duration.time`

您可以使用 duration.time(int hours, int minutes, int seconds, int nanoseconds) 函数，该函数将创建由指定小时、分钟、秒和纳秒。

// Create a four hour, three minute, two second, one nanosecond duration
duration.time(4, 3, 2, 1)

`list`

列表包含一个有序的值数组，值的类型如下：null、bool、 int、float、string、path、list、map、timestamp 或 duration。

假定 x 和 y 的类型为 list 和 i 以及类型为 int 的 j

创建

如需创建列表，请在方括号之间添加值：

// Create a list of strings
['apples', 'grapes', 'bananas', 'cheese', 'goats']

比较

您可以使用 == 运算符 != 比较列表。两个列表相等要求所有值必须相同。

索引和范围

index 运算符 list[] 会返回。

// Allow reads of all files that begin with 'a'
match /{fileName} {
  allow read: if fileName[0] == 'a';
}

range 运算符 list[i:j] 会返回介于指定索引，范围为 i（含）到 j（不含）。如果 i 或 j 未指定，它们分别默认为 0 和列表大小，但必须至少指定 i 或 j 才能使范围有效。

// Allow reads of all files that begin with 'abcdef'
match /{fileName} {
  allow read: if fileName[0:6] == 'abcdef';
}

`in`

如果所需值出现在列表中，则返回 true；否则返回 false 存在。

// Allow read if a filename has the string 'txt' in it
match /{fileName} {
  allow read: if 'txt' in fileName.split('\\.');
}

`join`

将一系列字符串合并为单个字符串，并以给定字符串分隔。

// Allow reads if the joined array is 'file.txt'
allow read: if ['file', 'txt'].join('.') == 'file.txt';

`size`

列表中项目的数量。

// Allow read if there are three items in our list
allow read: if ['foo', 'bar', 'baz'].size() == 3;

`hasAll`

如果列表中的所有值都存在，则返回 true。

// Allow read if one list has all items in the other list
allow read: if ['file', 'txt'].hasAll(['file', 'txt']);

`map`

映射包含键值对，其中键是字符串，值可以是任何值 /null、bool、int、float、string、path、list、map、 timestamp 或 duration。

创建

如需创建映射，请在大括号内添加键值对：

// Create a map of strings to strings
{
  'mercury': 'mars',
  'rain': 'cloud',
  'cats': 'dogs',
}

比较

您可以使用 == 运算符 != 比较地图。两个映射相等要求两个映射中都存在所有键，并且所有值都相同。

索引

映射中的值可通过括号或点表示法来访问：

// Access custom metadata properties
allow read: if resource.metadata.property == 'property'
allow write: if resource.metadata['otherProperty'] == 'otherProperty'

如果键不存在，则返回 error。

`in`

如果所需键出现在映射中，则返回 true；如果不存在，则返回 false 存在。

// Allow reads if a property is present in the custom metadata
allow read: if property in resource.metadata;

`size`

映射中的键数量。

// Allow reads if there's exactly one custom metadata key
allow read: if resource.metadata.size() == 1;

`keys`

映射中所有键的列表。

// Allow reads if the first metadata key is 'myKey'
allow read: if resource.metadata.keys()[0] == 'myKey';

`values`

映射中所有值的列表（按键顺序）。

// Allow reads if the first metadata value is 'myValue'
allow read: if resource.metadata.values()[0] == 'myValue';

错误

错误评估

Cloud Storage 的 Firebase Security Rules 在遇到错误时继续评估。这很有用，因为条件 && 和 || 表达式可以吸收错误如果该条件会短路到 false 或 true 。例如：

表达式	结果
`error && true`	`error`
`error && false`	`false`
`error \|\| true`	`true`
`error \|\| false`	`error`

导致错误的常见位置包括：除数为零、取值列表或映射中，并且传递的值类型不正确一个函数。

// Error if resource.size is zero
allow read: if 1000000 / resource.size;

// Error, key doesn't exist
allow read: if resource.metadata.nonExistentKey == 'value';

// Error, no unit 'y' exists
allow read: if request.time < resource.timeCreated + duration.value(1, 'y');

面向 Cloud Storage 的 Firebase 安全规则参考

规则

类型

允许

请求方法

Read

Write

Match

路径细分

single_segment

{single_segment_wildcard}

{multi_segment_wildcard=**}

请求

属性

auth

path

resource

time

资源

属性

name

bucket

generation

metageneration

size

timeCreated

updated

md5Hash

crc32c

etag

contentDisposition

contentEncoding

contentLanguage

contentType

metadata

firestore.get 和 firestore.exists

Firestore.get

Firestore.exists

Service

名称

name

数据类型

null

bool

比较

布尔值运算

int和float

比较

算术

数学函数

string

比较

串联

索引和范围

size

matches

split

path

path

timestamp

比较

算术

date

year

month

day

time

hours

minutes

seconds

nanos

dayOfWeek

dayOfYear

toMillis

duration

比较

算术

seconds

nanos

duration.value

`single_segment`

`{single_segment_wildcard}`

`{multi_segment_wildcard=**}`

`auth`

`path`

`resource`

`time`

`name`

`bucket`

`generation`

`metageneration`

`size`

`timeCreated`

`updated`

`md5Hash`

`crc32c`

`etag`

`contentDisposition`

`contentEncoding`

`contentLanguage`

`contentType`

`metadata`

`name`

`null`

`bool`

`int`和`float`

`string`

`size`

`matches`

`split`

`path`

`path`

`timestamp`

`date`

`year`

`month`

`day`

`time`

`hours`

`minutes`

`seconds`

`nanos`

`dayOfWeek`

`dayOfYear`

`toMillis`

`duration`

`seconds`

`nanos`

`duration.value`

`duration.time`

`list`

`in`

`join`

`size`

`hasAll`

`map`

`in`

`size`

`keys`

`values`