Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

了解 Cloud Storage 語言的 Firebase 安全規則的核心語法

Cloud Storage 的 Firebase 安全規則允許您控制對存儲在 Cloud Storage 存儲分區中的對象的訪問。靈活的規則語法允許您創建規則來控制任何操作,從對 Cloud Storage 存儲分區的所有寫入到對特定文件的操作。

本指南介紹了用於創建完整規則集的 Cloud Storage 安全規則的基本語法和結構。

服務和數據庫聲明

Cloud Storage 的 Firebase 安全規則始終以以下聲明開頭:

service firebase.storage {
    // ...
}

service firebase.storage聲明將規則範圍service firebase.storage為 Cloud Storage,防止 Cloud Storage 安全規則與其他產品(例如 Cloud Firestore)的規則發生衝突。

基本讀/寫規則

基本規則由一個的match語句識別雲存儲桶,一個匹配語句中指定一個文件名,和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 語句可以指向特定文件,如match /images/profilePhoto.png

匹配通配符

除了指向單個文件之外,Rules 還可以使用通配符指向名稱中帶有給定字符串前綴的任何文件,包括斜線,如match /images/{imageId}

在上面的示例中,匹配語句使用{imageId}通配符語法。這意味著該規則適用於名稱開頭帶有/images/任何文件,例如/images/profilePhoto.png/images/croppedProfilePhoto.png 。當匹配語句中的allow表達式被計算時, imageId變量將解析為圖像文件名,例如profilePhoto.pngcroppedProfilePhoto.png

可以從match引用通配符變量以提供文件名或路徑授權:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

分層數據

正如我們之前所說,Cloud Storage 存儲分區內沒有層次結構。但是通過使用文件命名約定,通常是在文件名中包含斜杠的約定,我們可以模仿一種看起來像一系列嵌套目錄和子目錄的結構。了解 Firebase 安全規則如何與這些文件名交互非常重要。

考慮一組名稱都以/images/詞幹開頭的文件的情況。 Firebase 安全規則僅適用於匹配的文件名,因此/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”可以在conditionother_condition計算結果為true時讀取,而文件“images/users/user:12345/profilePhoto.png”只受other_condition的結果影響.

Cloud Storage 安全規則不會級聯,並且僅當請求路徑與指定規則的路徑匹配時才會評估規則。

版本 1

Firebase 安全規則默認使用版本 1。在版本 1 中,遞歸通配符匹配一個或多個文件名元素,而不是零個或多個元素。因此, match /images/{filenamePrefixWildcard}/{imageFilename=**}匹配像 /images/profilePics/profile.png 這樣的文件名,但不匹配 /images/badge.png。改用/images/{imagePrefixorFilename=**}

遞歸通配符必須出現在匹配語句的末尾。

我們建議您使用版本 2,因為它具有更強大的功能。

版本 2

在 Firebase 安全規則的第 2 版中,遞歸通配符匹配零個或多個路徑項。因此, /images/{filenamePrefixWildcard}/{imageFilename=**}匹配文件名 /images/profilePics/profile.png 和 /images/badge.png。

您必須通過添加rules_version = '2';來選擇加入第 2 版rules_version = '2';在您的安全規則的頂部:

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

每個 match 語句最多可以有一個遞歸通配符,但在版本 2 中,您可以將此通配符放在 match 語句中的任何位置。例如:

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>;
   }
  }
}

細粒度操作

在某些情況下,將readwrite分解為更細粒度的操作很有用。例如,您的應用可能希望對文件創建和文件刪除強制執行不同的條件。

read操作可以分為getlist

write規則可以分為createupdatedelete

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single document 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 nonexistent files
      allow create: if <condition>;

      // Applies to writes to existing files
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

重疊匹配語句

一個文件名可能匹配多個match語句。在多個allow表達式匹配請求的情況下,如果任何條件為true ,則允許訪問:

service firebase.storage {
  match b/{bucket}/o {
    // Matches any filename containing string '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches all filenames containing string `/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';
    }
  }
}

Denied :此規則拒絕以下請求,因為結果集可能包含contentType不是image/png

網絡
filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

Cloud Storage 安全規則中的規則根據其潛在結果評估每個查詢,如果它可能返回客戶端無權讀取的文件,則請求失敗。訪問請求必須遵循您的規則設置的約束。

下一步

您可以加深對 Cloud Storage 的 Firebase 安全規則的理解:

  • 了解規則語言的下一個主要概念,即動態條件,它可以讓您的規則檢查用戶授權、比較現有數據和傳入數據、驗證傳入數據等。

  • 查看典型的安全用例和解決它們Firebase 安全規則定義

您可以探索特定於 Cloud Storage 的 Firebase 安全規則用例: