Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

在即時資料庫安全性規則中使用條件

本指南以瞭解核心 Firebase 安全性規則語言指南為基礎，說明如何將條件新增至 Firebase 即時資料庫安全性規則。

即時資料庫安全性規則的主要建構區塊是條件。條件是布林運算式，可決定是否應允許或拒絕特定作業。如果是基本規則，使用 true 和 false 常值做為條件的效果非常好。不過，即時資料庫安全性規則語言可讓您編寫更複雜的條件，例如：

檢查使用者驗證
根據新提交的資料評估現有資料
存取及比較資料庫的不同部分
驗證傳入資料
使用傳入查詢的結構來建立安全性邏輯

使用 $ 變數擷取路徑區隔

您可以宣告前置字元為 $ 的擷取變數，擷取部分路徑來進行讀取或寫入。這會做為萬用字元，並儲存該鍵的值，以便在規則條件中使用：

{
  "rules": {
    "rooms": {
      // this rule applies to any child of /rooms/, the key for each room id
      // is stored inside $room_id variable for reference
      "$room_id": {
        "topic": {
          // the room's topic can be changed if the room id has "public" in it
          ".write": "$room_id.contains('public')"
        }
      }
    }
  }
}

動態 $ 變數也可以與常數路徑名稱並行使用。在本範例中，我們使用 $other 變數宣告 .validate 規則，確保 widget 除了 title 和 color 之外沒有其他子項。任何會導致建立額外子項的寫入作業都會失敗。

{
  "rules": {
    "widget": {
      // a widget can have a title or color attribute
      "title": { ".validate": true },
      "color": { ".validate": true },

      // but no other child paths are allowed
      // in this case, $other means any key excluding "title" and "color"
      "$other": { ".validate": false }
    }
  }
}

驗證

最常見的安全規則模式之一，是根據使用者的驗證狀態控管存取權。舉例來說，您的應用程式可能只允許登入的使用者寫入資料。

如果應用程式使用 Firebase 驗證，request.auth 變數會包含要求資料的用戶端驗證資訊。如要進一步瞭解 request.auth，請參閱參考文件。

Firebase Authentication 與 Firebase Realtime Database 整合，可讓您使用條件控管個別使用者的資料存取權。使用者通過驗證後，即時資料庫安全性規則中的 auth 變數就會填入使用者資訊。這項資訊包括專屬 ID (uid) 和連結的帳戶資料 (例如 Facebook ID 或電子郵件地址) 等。如果您導入自訂驗證供應商，可以在使用者的驗證酬載中新增自己的欄位。

本節說明如何將 Firebase 即時資料庫安全性規則語言與使用者的驗證資訊結合。結合這兩項概念，即可根據使用者身分控管資料存取權。

`auth` 變數

在驗證之前，規則中預先定義的 auth 變數為空值。

使用者通過 Firebase 驗證後，會包含下列屬性：

供應商	使用的驗證方式 (「password」、「anonymous」、「facebook」、「github」、「google」或「twitter」)。
uid	不重複的使用者 ID，保證在所有供應商中不重複。
token	Firebase 驗證 ID 權杖的內容。詳情請參閱 `auth.token` 的參考文件。

以下範例規則使用 auth 變數，確保每位使用者只能寫入使用者專屬路徑：

{
  "rules": {
    "users": {
      "$user_id": {
        // grants write access to the owner of this user account
        // whose uid must exactly match the key ($user_id)
        ".write": "$user_id === auth.uid"
      }
    }
  }
}

建構資料庫以支援驗證條件

通常，以更容易寫入的方式建構資料庫會很有幫助。Security Rules在 Realtime Database 中儲存使用者資料的常見模式，是將所有使用者儲存在單一 users 節點中，其子節點是每位使用者的 uid 值。如要限制這項資料的存取權，讓只有登入的使用者能查看自己的資料，規則會像這樣。

{
  "rules": {
    "users": {
      "$uid": {
        ".read": "auth !== null && auth.uid === $uid"
      }
    }
  }
}

使用驗證自訂宣告

如果應用程式需要為不同使用者自訂存取控管，Firebase Authentication 可讓開發人員設定 Firebase 使用者的宣告。您可以在規則的 auth.token 變數中存取這些宣告。以下是使用 hasEmergencyTowel 自訂聲明的規則範例：

{
  "rules": {
    "frood": {
      // A towel is about the most massively useful thing an interstellar
      // hitchhiker can have
      ".read": "auth.token.hasEmergencyTowel === true"
    }
  }
}

開發人員建立自訂驗證權杖時，可以選擇在權杖中加入聲明。您可以在規則的 auth.token 變數中找到這些宣告。

現有資料與新資料

預先定義的 data 變數用於參照寫入作業發生前的資料。相反地，newData 變數包含寫入作業成功後會存在的新資料。newData 代表新寫入資料和現有資料的合併結果。

舉例來說，這項規則允許我們建立新記錄或刪除現有記錄，但無法變更現有的非空值資料：

// we can write as long as old data or new data does not exist
// in other words, if this is a delete or a create, but not an update
".write": "!data.exists() || !newData.exists()"

參照其他路徑中的資料

任何資料都能做為規則條件。使用預先定義的變數 root、data 和 newData，我們就能存取寫入事件前後存在的任何路徑。

請參考以下範例，只要 /allow_writes/ 節點的值為 true、父節點未設定 readOnly 旗標，且新寫入的資料中有一個名為 foo 的子節點，就允許寫入作業：

".write": "root.child('allow_writes').val() === true &&
          !data.parent().child('readOnly').exists() &&
          newData.child('foo').exists()"

驗證資料

強制執行資料結構，以及驗證資料格式和內容，都應使用 .validate 規則完成，這些規則只有在 .write 規則成功授予存取權後才會執行。以下是 .validate 規則定義範例，僅允許 1900 年至 2099 年之間採用 YYYY-MM-DD 格式的日期，並使用規則運算式檢查。

".validate": "newData.isString() &&
              newData.val().matches(/^(19|20)[0-9][0-9][-\\/. ](0[1-9]|1[012])[-\\/. ](0[1-9]|[12][0-9]|3[01])$/)"

.validate 規則是唯一不會串聯的安全規則。如果任何子記錄未通過驗證規則，整個寫入作業都會遭到拒絕。此外，刪除資料時 (也就是寫入的新值為 null 時)，系統會忽略驗證定義。

這些看似微不足道，但實際上是編寫強大 Firebase 即時資料庫安全性規則的重要功能。請考量下列規則：

{
  "rules": {
    // write is allowed for all paths
    ".write": true,
    "widget": {
      // a valid widget must have attributes "color" and "size"
      // allows deleting widgets (since .validate is not applied to delete rules)
      ".validate": "newData.hasChildren(['color', 'size'])",
      "size": {
        // the value of "size" must be a number between 0 and 99
        ".validate": "newData.isNumber() &&
                      newData.val() >= 0 &&
                      newData.val() <= 99"
      },
      "color": {
        // the value of "color" must exist as a key in our mythical
        // /valid_colors/ index
        ".validate": "root.child('valid_colors/' + newData.val()).exists()"
      }
    }
  }
}

請記住這個變體，並查看下列寫入作業的結果：

JavaScript

var ref = db.ref("/widget");

// PERMISSION_DENIED: does not have children color and size
ref.set('foo');

// PERMISSION DENIED: does not have child color
ref.set({size: 22});

// PERMISSION_DENIED: size is not a number
ref.set({ size: 'foo', color: 'red' });

// SUCCESS (assuming 'blue' appears in our colors list)
ref.set({ size: 21, color: 'blue'});

// If the record already exists and has a color, this will
// succeed, otherwise it will fail since newData.hasChildren(['color', 'size'])
// will fail to validate
ref.child('size').set(99);

Objective-C

注意：這項 Firebase 產品不適用於 App Clip 目標。

FIRDatabaseReference *ref = [[[FIRDatabase database] reference] child: @"widget"];

// PERMISSION_DENIED: does not have children color and size
[ref setValue: @"foo"];

// PERMISSION DENIED: does not have child color
[ref setValue: @{ @"size": @"foo" }];

// PERMISSION_DENIED: size is not a number
[ref setValue: @{ @"size": @"foo", @"color": @"red" }];

// SUCCESS (assuming 'blue' appears in our colors list)
[ref setValue: @{ @"size": @21, @"color": @"blue" }];

// If the record already exists and has a color, this will
// succeed, otherwise it will fail since newData.hasChildren(['color', 'size'])
// will fail to validate
[[ref child:@"size"] setValue: @99];

Swift

注意：這項 Firebase 產品不適用於 App Clip 目標。

var ref = FIRDatabase.database().reference().child("widget")

// PERMISSION_DENIED: does not have children color and size
ref.setValue("foo")

// PERMISSION DENIED: does not have child color
ref.setValue(["size": "foo"])

// PERMISSION_DENIED: size is not a number
ref.setValue(["size": "foo", "color": "red"])

// SUCCESS (assuming 'blue' appears in our colors list)
ref.setValue(["size": 21, "color": "blue"])

// If the record already exists and has a color, this will
// succeed, otherwise it will fail since newData.hasChildren(['color', 'size'])
// will fail to validate
ref.child("size").setValue(99);

Java

FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("widget");

// PERMISSION_DENIED: does not have children color and size
ref.setValue("foo");

// PERMISSION DENIED: does not have child color
ref.child("size").setValue(22);

// PERMISSION_DENIED: size is not a number
Map<String,Object> map = new HashMap<String, Object>();
map.put("size","foo");
map.put("color","red");
ref.setValue(map);

// SUCCESS (assuming 'blue' appears in our colors list)
map = new HashMap<String, Object>();
map.put("size", 21);
map.put("color","blue");
ref.setValue(map);

// If the record already exists and has a color, this will
// succeed, otherwise it will fail since newData.hasChildren(['color', 'size'])
// will fail to validate
ref.child("size").setValue(99);

REST

# PERMISSION_DENIED: does not have children color and size
curl -X PUT -d 'foo' \
https://docs-examples.firebaseio.com/rest/securing-data/example.json

# PERMISSION DENIED: does not have child color
curl -X PUT -d '{"size": 22}' \
https://docs-examples.firebaseio.com/rest/securing-data/example.json

# PERMISSION_DENIED: size is not a number
curl -X PUT -d '{"size": "foo", "color": "red"}' \
https://docs-examples.firebaseio.com/rest/securing-data/example.json

# SUCCESS (assuming 'blue' appears in our colors list)
curl -X PUT -d '{"size": 21, "color": "blue"}' \
https://docs-examples.firebaseio.com/rest/securing-data/example.json

# If the record already exists and has a color, this will
# succeed, otherwise it will fail since newData.hasChildren(['color', 'size'])
# will fail to validate
curl -X PUT -d '99' \
https://docs-examples.firebaseio.com/rest/securing-data/example/size.json

現在來看看相同的結構，但使用 .write 規則而非 .validate：

{
  "rules": {
    // this variant will NOT allow deleting records (since .write would be disallowed)
    "widget": {
      // a widget must have 'color' and 'size' in order to be written to this path
      ".write": "newData.hasChildren(['color', 'size'])",
      "size": {
        // the value of "size" must be a number between 0 and 99, ONLY IF WE WRITE DIRECTLY TO SIZE
        ".write": "newData.isNumber() && newData.val() >= 0 && newData.val() <= 99"
      },
      "color": {
        // the value of "color" must exist as a key in our mythical valid_colors/ index
        // BUT ONLY IF WE WRITE DIRECTLY TO COLOR
        ".write": "root.child('valid_colors/'+newData.val()).exists()"
      }
    }
  }
}

在這個變體中，下列任一作業都會成功：

JavaScript

var ref = new Firebase(URL + "/widget");

// ALLOWED? Even though size is invalid, widget has children color and size,
// so write is allowed and the .write rule under color is ignored
ref.set({size: 99999, color: 'red'});

// ALLOWED? Works even if widget does not exist, allowing us to create a widget
// which is invalid and does not have a valid color.
// (allowed by the write rule under "color")
ref.child('size').set(99);

Objective-C

注意：這項 Firebase 產品不適用於 App Clip 目標。

Firebase *ref = [[Firebase alloc] initWithUrl:URL];

// ALLOWED? Even though size is invalid, widget has children color and size,
// so write is allowed and the .write rule under color is ignored
[ref setValue: @{ @"size": @9999, @"color": @"red" }];

// ALLOWED? Works even if widget does not exist, allowing us to create a widget
// which is invalid and does not have a valid color.
// (allowed by the write rule under "color")
[[ref childByAppendingPath:@"size"] setValue: @99];

Swift

注意：這項 Firebase 產品不適用於 App Clip 目標。

var ref = Firebase(url:URL)

// ALLOWED? Even though size is invalid, widget has children color and size,
// so write is allowed and the .write rule under color is ignored
ref.setValue(["size": 9999, "color": "red"])

// ALLOWED? Works even if widget does not exist, allowing us to create a widget
// which is invalid and does not have a valid color.
// (allowed by the write rule under "color")
ref.childByAppendingPath("size").setValue(99)

Java

Firebase ref = new Firebase(URL + "/widget");

// ALLOWED? Even though size is invalid, widget has children color and size,
// so write is allowed and the .write rule under color is ignored
Map<String,Object> map = new HashMap<String, Object>();
map.put("size", 99999);
map.put("color", "red");
ref.setValue(map);

// ALLOWED? Works even if widget does not exist, allowing us to create a widget
// which is invalid and does not have a valid color.
// (allowed by the write rule under "color")
ref.child("size").setValue(99);

REST

# ALLOWED? Even though size is invalid, widget has children color and size,
# so write is allowed and the .write rule under color is ignored
curl -X PUT -d '{size: 99999, color: "red"}' \
https://docs-examples.firebaseio.com/rest/securing-data/example.json

# ALLOWED? Works even if widget does not exist, allowing us to create a widget
# which is invalid and does not have a valid color.
# (allowed by the write rule under "color")
curl -X PUT -d '99' \
https://docs-examples.firebaseio.com/rest/securing-data/example/size.json

這張圖說明 .write 和 .validate 規則之間的差異。如上所示，所有這些規則都應使用 .validate 編寫，但 newData.hasChildren() 規則可能例外，這取決於是否應允許刪除。

查詢式規則

雖然無法將規則當做篩選器使用，但您可以在規則中使用查詢參數，限制對資料子集的存取權。在規則中使用 query. 運算式，根據查詢參數授予讀取或寫入權限。

舉例來說，下列查詢規則使用使用者安全性規則和查詢規則，限制只有目前使用者擁有的購物籃，才能存取 baskets 集合中的資料：

"baskets": {
  ".read": "auth.uid !== null &&
            query.orderByChild === 'owner' &&
            query.equalTo === auth.uid" // restrict basket access to owner of basket
}

下列查詢包含規則中的查詢參數，因此會成功：

db.ref("baskets").orderByChild("owner")
                 .equalTo(auth.currentUser.uid)
                 .on("value", cb)                 // Would succeed

不過，如果查詢不含規則中的參數，就會失敗並傳回 PermissionDenied 錯誤：

db.ref("baskets").on("value", cb)                 // Would fail with PermissionDenied

您也可以使用查詢式規則，限制用戶端透過讀取作業下載的資料量。

舉例來說，下列規則會限制讀取權限，只允許讀取查詢結果中優先順序最高的前 1000 個結果：

messages: {
  ".read": "query.orderByKey &&
            query.limitToFirst <= 1000"
}

// Example queries:

db.ref("messages").on("value", cb)                // Would fail with PermissionDenied

db.ref("messages").limitToFirst(1000)
                  .on("value", cb)                // Would succeed (default order by key)

即時資料庫安全性規則支援下列 query. 運算式。

查詢型規則運算式
運算式	類型	說明
query.orderByKey query.orderByPriority query.orderByValue	布林值	如果查詢依鍵、優先順序或值排序，則為 True。否則傳回「false」。
query.orderByChild	string null	請使用字串代表子節點的相對路徑。例如：`query.orderByChild === "address/zip"`。如果查詢未依子節點排序，這個值會是空值。
query.startAt query.endAt query.equalTo	string number boolean null	擷取執行中查詢的繫結，如果未設定繫結，則傳回空值。
query.limitToFirst query.limitToLast	number null	擷取執行中查詢的限制，如果未設定限制，則傳回空值。

後續步驟

討論完條件後，您對 Security Rules 有更深入的瞭解，並準備好：

瞭解如何處理核心用途，以及開發、測試和部署 Security Rules 的工作流程：

瞭解可用於建構條件的完整預先定義 Security Rules 變數。
編寫規則來因應常見情境。
請複習必須找出並避免不安全規則的情況，進一步鞏固知識。
瞭解 Firebase 本機模擬器套件，以及如何使用該套件測試 Security Rules。
查看部署 Security Rules 的可用方法。

瞭解 Realtime Database 專屬的 Security Rules 功能：

瞭解如何為Realtime Database建立索引。
查看用於部署 Security Rules 的 REST API。

在即時資料庫安全性規則中使用條件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用 $ 變數擷取路徑區隔

驗證

auth 變數

建構資料庫以支援驗證條件

使用驗證自訂宣告

現有資料與新資料

參照其他路徑中的資料

驗證資料

JavaScript

Objective-C

Swift

Java

REST

JavaScript

Objective-C

Swift

Java

REST

查詢式規則

後續步驟

在即時資料庫安全性規則中使用條件

`auth` 變數