Cloud Storage 的 Firebase Security Rules 可讓您控管儲存物件的存取權 在 Cloud Storage 個值區中。彈性規則語法可讓您建立 任何作業 (包括所有寫入至 Cloud Storage) 的規則 對特定檔案執行各種作業
本指南將說明 Cloud Storage Security Rules 的基本語法和結構, 以及建立完整的規則集
服務和資料庫宣告
Cloud Storage 的 Firebase Security Rules 一律會以以下宣告開頭:
service firebase.storage {
// ...
}
service firebase.storage
宣告會將規則範圍設為 Cloud Storage,避免 Cloud Storage Security Rules 與 Cloud Firestore 等其他產品的規則發生衝突。
基本讀取/寫入規則
基本規則包含 match
陳述式,用於識別 Cloud Storage 值區、指定檔案名稱的配對陳述式,以及 allow
運算式,用於說明何時允許讀取指定資料。allow
運算式會指定涉及的存取方法 (例如讀取、寫入),以及條件 (允許或拒絕存取)。
在預設規則集中,第一個 match
陳述式使用 {bucket}
萬用字元
運算式,用於表示規則適用於您專案中的所有值區。我們會在下一節進一步討論萬用字元比對的概念。
service firebase.storage {
// The {bucket} wildcard indicates we match files in all Cloud Storage buckets
match /b/{bucket}/o {
// Match filename
match /filename {
allow read: if <condition>;
allow write: if <condition>;
}
}
}
所有比對陳述式都指向檔案。比對陳述式可以指向特定
檔案,例如 match /images/profilePhoto.png
。
比對萬用字元
除了指向單一檔案,Rules 除了可使用萬用字元外,
指向名稱中含有指定字串前置字元 (包括斜線) 的任何檔案
與 match /images/{imageId}
中一樣
在上述範例中,比對陳述式使用 {imageId}
萬用字元語法。
也就是說,這個規則會套用至名稱開頭為 /images/
的任何檔案,例如 /images/profilePhoto.png
或 /images/croppedProfilePhoto.png
。當
系統會評估比對陳述式中的 allow
運算式,也就是 imageId
變數
會解析為圖片檔案名稱,例如 profilePhoto.png
或
croppedProfilePhoto.png
。
您可以在 match
中參照萬用字元變數,以便提供檔案名稱或路徑授權:
// Another way to restrict the name of a file
match /images/{imageId} {
allow read: if imageId == "profilePhoto.png";
}
階層式資料
如前所述,Cloud Storage 值區中沒有階層結構。不過,只要使用檔案命名慣例 (通常會在檔案名稱中加入斜線),就能模擬出類似巢狀目錄和子目錄的結構。請務必瞭解 Firebase Security Rules 如何與這些檔案名稱互動。
請考慮以下情況:一組檔案的名稱都以 /images/
開頭。Firebase Security Rules 只會套用至相符的檔案名稱,因此在 /images/
主幹上定義的存取控制項不會套用至 /mp3s/
主幹。相反地,您應該寫出符合不同檔案名稱模式的明確規則:
service firebase.storage {
match /b/{bucket}/o {
match /images/{imageId} {
allow read, write: if <condition>;
}
// Explicitly define rules for the 'mp3s' pattern
match /mp3s/{mp3Id} {
allow read, write: if <condition>;
}
}
}
為 match
陳述式建立巢狀結構時,內部 match
陳述式的路徑為
一律附加至外部 match
陳述式的路徑。因此,下列兩個規則集是等效的:
service firebase.storage {
match /b/{bucket}/o {
match /images {
// Exact match for "images/profilePhoto.png"
match /profilePhoto.png {
allow write: if <condition>;
}
}
}
}
service firebase.storage {
match /b/{bucket}/o {
// Exact match for "images/profilePhoto.png"
match /images/profilePhoto.png {
allow write: if <condition>;
}
}
}
遞迴比對萬用字元
除了用萬用字元比對檔案名稱,並在檔案名稱結尾傳回字串以外,
呼叫多個區段萬用字元,可宣告更複雜的比對,方法為
將 =**
新增至萬用字元名稱,例如 {path=**}
:
// Partial match for files that start with "images"
match /images {
// Exact match for "images/**"
// e.g. images/users/user:12345/profilePhoto.png is matched
// images/profilePhoto.png is also matched!
match /{allImages=**} {
// This rule matches one or more path segments (**)
// allImages is a path that contains all segments matched
allow read: if <other_condition>;
}
}
如果有多個規則與檔案相符,結果就是所有規則評估結果的 OR
。也就是說,如果檔案符合的任何規則評估為 true
,
結果是「true
」。
在上述規則中,檔案「images/profilePhoto.png」就能讀取
condition
或 other_condition
的值為 true,而檔案
「images/users/user:12345/profilePhoto.png」只有在結果為
other_condition
。
Cloud Storage Security Rules 不會串聯,且系統只會評估 要求路徑與包含指定規則的路徑相符。
版本 1
Firebase Security Rules 預設會使用第 1 版。在 1 版中,遞迴萬用字元會比對一或多個檔案名稱元素,而非零或多個元素。因此,match /images/{filenamePrefixWildcard}/{imageFilename=**}
會比對 /images/profilePics/profile.png 這類檔案名稱,但不會比對 /images/badge.png。請改用 /images/{imagePrefixorFilename=**}
。
遞迴萬用字元必須放在比對陳述式的結尾。
建議您改用第 2 版,以便享有更強大的功能。
版本 2
在 Firebase Security Rules 2 版中,遞迴萬用字元會比對零個或多個路徑項目。因此,/images/{filenamePrefixWildcard}/{imageFilename=**}
會比對檔案名稱 /images/profilePics/profile.png 和 /images/badge.png。
您必須在安全性規則頂端新增 rules_version = '2';
,才能選擇採用第 2 版:
rules_version = '2';
service cloud.storage {
match /b/{bucket}/o {
...
}
}
每個比對陳述式最多只能有一個遞迴萬用字元,但 版本 2 中,這個萬用字元可以放在比對陳述式中的任何位置。例如:
rules_version = '2';
service firebase.storage {
match /b/{bucket}/o {
// Matches any file in a songs "subdirectory" under the
// top level of your Cloud Storage bucket.
match /{prefixSegment=**}/songs/{mp3filenames} {
allow read, write: if <condition>;
}
}
}
精細運算
在某些情況下,將 read
和 write
細分為更常見的 ID
執行精細作業舉例來說,您的應用程式可能想強制執行
而非刪除檔案時的條件。
read
作業可分為 get
和 list
。
write
規則可分為 create
、update
和 delete
:
service firebase.storage { match /b/{bucket}/o { // A read rule can be divided into read and list rules match /images/{imageId} { // Applies to single file read requests allow get: if <condition>; // Applies to list and listAll requests (Rules Version 2) allow list: if <condition>; // A write rule can be divided into create, update, and delete rules match /images/{imageId} { // Applies to writes to file contents allow create: if <condition>; // Applies to updates to (pre-existing) file metadata allow update: if <condition>; // Applies to delete operations allow delete: if <condition>; } } } }
重疊的配對陳述式
檔案名稱可能會與多個 match
陳述式相符。在
如果有多個 allow
運算式符合同一個要求,則允許存取
如果「任一」條件為 true
:
service firebase.storage {
match b/{bucket}/o {
// Matches file names directly inside of '/images/'.
match /images/{imageId} {
allow read, write: if false;
}
// Matches file names anywhere under `/images/`
match /images/{imageId=**} {
allow read, write: if true;
}
}
}
在上例中,系統允許對名稱以 /images/
開頭的檔案執行所有讀取和寫入作業,因為第二個規則一律為 true
,即使第一個規則為 false
也一樣。
規則不是篩選器
保護資料並開始執行檔案作業後,請注意安全性規則並非篩選器。您無法對一組 符合檔案名稱模式的檔案,且預期 Cloud Storage 只能存取 是目前用戶端有權存取的檔案。
例如,請參考下列安全性規則:
service firebase.storage {
match /b/{bucket}/o {
// Allow the client to read files with contentType 'image/png'
match /aFileNamePrefix/{aFileName} {
allow read: if resource.contentType == 'image/png';
}
}
}
已拒絕:這項規則拒絕下列內容:
要求,因為結果集可能包含 contentType
檔案
非image/png
:
網路
filesRef = storage.ref().child("aFilenamePrefix"); filesRef.listAll() .then(function(result) { console.log("Success: ", result.items); }) });
Cloud Storage Security Rules 中的規則會根據每個查詢的潛在結果進行評估,如果可能傳回用戶端沒有讀取權限的檔案,就會拒絕要求。存取要求必須遵循 規則。
後續步驟
您可以進一步瞭解 Firebase Security Rules 與 Cloud Storage 的關係:
瞭解規則語言的下一個重要概念:動態條件,讓規則可檢查使用者授權、比較現有資料和傳入資料、驗證傳入資料等等。
回顧一般的安全性用途,以及 能夠解決這些難題的 Firebase Security Rules 定義。
您可以探索 Cloud Storage 專屬的 Firebase Security Rules 用途: