Firebase 云存储安全规则中的使用条件

本指南以学习 Firebase 安全规则语言指南的核心语法为基础，展示如何向 Cloud Storage 的 Firebase 安全规则添加条件。

云存储安全规则的主要构建块是条件。条件是一个布尔表达式，用于确定是否应允许或拒绝特定操作。对于基本规则，使用true文字作为条件false有效。但是 Cloud Storage 语言的 Firebase 安全规则为您提供了编写更复杂条件的方法，这些条件可以：

• 检查用户身份验证
• 验证传入数据

验证

Cloud Storage 的 Firebase 安全规则与 Firebase 身份验证集成，为 Cloud Storage 提供强大的基于用户的身份验证。这允许基于 Firebase 身份验证令牌的声明进行精细的访问控制。

当经过身份验证的用户对 Cloud Storage 执行请求时， request.auth变量会填充用户的uid ( request.auth.uid ) 以及 Firebase 身份验证 JWT ( request.auth.token ) 的声明。

此外，在使用自定义身份验证时， request.auth.token字段中会出现其他声明。

当未经身份验证的用户执行请求时， request.auth变量为null 。

使用这些数据，有几种常用的方法可以使用身份验证来保护文件：

• 公共：忽略request.auth
• Authenticated private：检查request.auth是否为null
• 用户私有：检查request.auth.uid是否等于路径uid
• 组私有：检查自定义令牌的声明以匹配所选声明，或读取文件元数据以查看元数据字段是否存在

上市

任何不考虑request.auth上下文的规则都可以被视为public规则，因为它不考虑用户的身份验证上下文。这些规则可用于显示公共数据，例如游戏资产、声音文件或其他静态内容。

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

经过身份验证的私人

在某些情况下，您可能希望应用程序的所有经过身份验证的用户都可以查看数据，而不是未经身份验证的用户。由于request.auth变量对于所有未经身份验证的用户都为null ，因此您只需检查request.auth变量是否存在以要求身份验证：

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

用户私有

到目前为止， request.auth最常见的用例是为个人用户提供对其文件的精细权限：从上传个人资料图片到阅读私人文档。

由于 Cloud Storage 中的文件具有文件的完整“路径”，因此使文件由用户控制所需的只是文件名前缀（例如用户的uid ）中的一条唯一的用户识别信息（例如用户的 uid ）评估规则时：

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

团体私人

另一个同样常见的用例是允许对对象的组权限，例如允许多个团队成员在共享文档上进行协作。有几种方法可以做到这一点：

• 铸造一个 Firebase 身份验证自定义令牌，其中包含有关组成员的其他信息（例如组 ID）
• 在文件元数据中包含组信息（例如组 ID 或授权的uid列表）

一旦此数据存储在令牌或文件元数据中，就可以从规则中引用它：

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

请求评估

使用发送到 Cloud Storage 的request评估上传、下载、元数据更改和删除。除了如上所述的request.auth对象中的用户唯一 ID 和 Firebase 身份验证负载外， request变量还包含正在执行请求的文件路径、接收请求的时间以及新的resource值（如果请求是写。还包括 HTTP 标头和身份验证状态。

request对象还在request.auth对象中包含用户的唯一 ID 和 Firebase 身份验证负载，这将在文档的User-Based Security部分中进一步解释。

request对象中的完整属性列表如下：

资源评估

在评估规则时，您可能还需要评估正在上传、下载、修改或删除的文件的元数据。这允许您创建复杂而强大的规则，例如只允许上传具有特定内容类型的文件，或者只允许删除大于特定大小的文件。

Cloud Storage 的 Firebase 安全规则在resource对象中提供文件元数据，其中包含 Cloud Storage 对象中出现的元数据的键/值对。可以在read或write请求时检查这些属性，以确保数据完整性。

在write请求（例如上传、元数据更新和删除）时，除了包含请求路径中当前存在的文件的文件元数据的resource对象外，您还可以使用request.resource对象，如果允许写入，它包含要写入的文件元数据的子集。您可以使用这两个值来确保数据完整性或强制应用程序约束，例如文件类型或大小。

resource对象中的完整属性列表如下：

request.resource包含所有这些，但generation 、 metageneration 、 etag 、 timeCreated和updated除外。

验证数据

Cloud Storage 的 Firebase 安全规则也可用于数据验证，包括验证文件名和路径以及文件元数据属性，例如contentType和size 。

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

自定义函数

随着您的 Firebase 安全规则变得越来越复杂，您可能希望将条件集包装在可以在规则集中重复使用的函数中。安全规则支持自定义函数。自定义函数的语法有点像 JavaScript，但 Firebase 安全规则函数是用特定领域的语言编写的，具有一些重要的限制：

• 函数只能包含一个return语句。它们不能包含任何额外的逻辑。例如，它们不能执行循环或调用外部服务。
• 函数可以从定义它们的范围内自动访问函数和变量。例如，在service firebase.storage范围内定义的函数可以访问resource变量，并且仅对于 Cloud Firestore，可以访问get()和exists()等内置函数。
• 函数可以调用其他函数，但不能递归。总调用堆栈深度限制为 10。
• 在版本rules2中，函数可以使用let关键字定义变量。函数可以有任意数量的 let 绑定，但必须以 return 语句结束。

函数使用function关键字定义，并接受零个或多个参数。例如，您可能希望将上述示例中使用的两种类型的条件组合成一个函数：

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

随着规则复杂性的增加，在 Firebase 安全规则中使用函数可以使它们更易于维护。

下一步

在对条件的讨论之后，您对规则有了更深入的了解，并准备好：

了解如何处理核心用例，并了解开发、测试和部署规则的工作流程：

• 编写解决常见场景的规则。
• 通过查看您必须发现和避免不安全规则的情况来建立您的知识。
• 使用Cloud Storage 模拟器和专用安全规则测试库测试规则。
• 查看可用于部署规则的方法。

本指南以学习 Firebase 安全规则语言指南的核心语法为基础，展示如何向 Cloud Storage 的 Firebase 安全规则添加条件。

云存储安全规则的主要构建块是条件。条件是一个布尔表达式，用于确定是否应允许或拒绝特定操作。对于基本规则，使用true文字作为条件false有效。但是 Cloud Storage 语言的 Firebase 安全规则为您提供了编写更复杂条件的方法，这些条件可以：

• 检查用户身份验证
• 验证传入数据

验证

Cloud Storage 的 Firebase 安全规则与 Firebase 身份验证集成，为 Cloud Storage 提供强大的基于用户的身份验证。这允许基于 Firebase 身份验证令牌的声明进行精细的访问控制。

当经过身份验证的用户对 Cloud Storage 执行请求时， request.auth变量会填充用户的uid ( request.auth.uid ) 以及 Firebase 身份验证 JWT ( request.auth.token ) 的声明。

此外，在使用自定义身份验证时， request.auth.token字段中会出现其他声明。

当未经身份验证的用户执行请求时， request.auth变量为null 。

使用这些数据，有几种常用的方法可以使用身份验证来保护文件：

• 公共：忽略request.auth
• Authenticated private：检查request.auth是否为null
• 用户私有：检查request.auth.uid是否等于路径uid
• 组私有：检查自定义令牌的声明以匹配所选声明，或读取文件元数据以查看元数据字段是否存在

上市

任何不考虑request.auth上下文的规则都可以被视为public规则，因为它不考虑用户的身份验证上下文。这些规则可用于显示公共数据，例如游戏资产、声音文件或其他静态内容。

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

经过身份验证的私人

在某些情况下，您可能希望应用程序的所有经过身份验证的用户都可以查看数据，而不是未经身份验证的用户。由于request.auth变量对于所有未经身份验证的用户都为null ，因此您只需检查request.auth变量是否存在以要求身份验证：

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

用户私有

到目前为止， request.auth最常见的用例是为个人用户提供对其文件的精细权限：从上传个人资料图片到阅读私人文档。

由于 Cloud Storage 中的文件具有文件的完整“路径”，因此使文件由用户控制所需的只是文件名前缀（例如用户的uid ）中的一条唯一的用户识别信息（例如用户的 uid ）评估规则时：

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

团体私人

另一个同样常见的用例是允许对对象的组权限，例如允许多个团队成员在共享文档上进行协作。有几种方法可以做到这一点：

• 铸造一个 Firebase 身份验证自定义令牌，其中包含有关组成员的其他信息（例如组 ID）
• 在文件元数据中包含组信息（例如组 ID 或授权的uid列表）

一旦此数据存储在令牌或文件元数据中，就可以从规则中引用它：

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

请求评估

使用发送到 Cloud Storage 的request评估上传、下载、元数据更改和删除。除了如上所述的request.auth对象中的用户唯一 ID 和 Firebase 身份验证负载外， request变量还包含正在执行请求的文件路径、接收请求的时间以及新的resource值（如果请求是写。还包括 HTTP 标头和身份验证状态。

request对象还在request.auth对象中包含用户的唯一 ID 和 Firebase 身份验证负载，这将在文档的User-Based Security部分中进一步解释。

request对象中的完整属性列表如下：

资源评估

在评估规则时，您可能还需要评估正在上传、下载、修改或删除的文件的元数据。这允许您创建复杂而强大的规则，例如只允许上传具有特定内容类型的文件，或者只允许删除大于特定大小的文件。

Cloud Storage 的 Firebase 安全规则在resource对象中提供文件元数据，其中包含 Cloud Storage 对象中出现的元数据的键/值对。可以在read或write请求时检查这些属性，以确保数据完整性。

在write请求（例如上传、元数据更新和删除）时，除了包含请求路径中当前存在的文件的文件元数据的resource对象外，您还可以使用request.resource对象，如果允许写入，它包含要写入的文件元数据的子集。您可以使用这两个值来确保数据完整性或强制应用程序约束，例如文件类型或大小。

resource对象中的完整属性列表如下：

request.resource包含所有这些，但generation 、 metageneration 、 etag 、 timeCreated和updated除外。

验证数据

Cloud Storage 的 Firebase 安全规则也可用于数据验证，包括验证文件名和路径以及文件元数据属性，例如contentType和size 。

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

自定义函数

随着您的 Firebase 安全规则变得越来越复杂，您可能希望将条件集包装在可以在规则集中重复使用的函数中。安全规则支持自定义函数。自定义函数的语法有点像 JavaScript，但 Firebase 安全规则函数是用特定领域的语言编写的，具有一些重要的限制：

• 函数只能包含一个return语句。它们不能包含任何额外的逻辑。例如，它们不能执行循环或调用外部服务。
• 函数可以从定义它们的范围内自动访问函数和变量。例如，在service firebase.storage范围内定义的函数可以访问resource变量，并且仅对于 Cloud Firestore，可以访问get()和exists()等内置函数。
• 函数可以调用其他函数，但不能递归。总调用堆栈深度限制为 10。
• 在版本rules2中，函数可以使用let关键字定义变量。函数可以有任意数量的 let 绑定，但必须以 return 语句结束。

函数使用function关键字定义，并接受零个或多个参数。例如，您可能希望将上述示例中使用的两种类型的条件组合成一个函数：

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

随着规则复杂性的增加，在 Firebase 安全规则中使用函数可以使它们更易于维护。

下一步

在对条件的讨论之后，您对规则有了更深入的了解，并准备好：

了解如何处理核心用例，并了解开发、测试和部署规则的工作流程：

• 编写解决常见场景的规则。
• 通过查看您必须发现和避免不安全规则的情况来建立您的知识。
• 使用Cloud Storage 模拟器和专用安全规则测试库测试规则。
• 查看可用于部署规则的方法。