本頁面由 Cloud Translation API 翻譯而成。

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

本指南將延續「瞭解 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 驗證驗證後，系統會包含下列屬性：

供應商	使用的驗證方法 (「密碼」、「匿名」、「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"
      }
    }
  }
}

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

通常來說，以便於編寫 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	擷取執行查詢的邊界，如果沒有設定邊界，則傳回 null。
query.limitToFirst query.limitToLast	數字 null	擷取執行查詢的限制，如果未設定限制，則傳回 null。

後續步驟

在討論條件後，您對 Rules 的瞭解將更為深入，並可進行以下操作：

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

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

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

瞭解如何為 Realtime Database 建立索引。
請參閱部署 Rules 的 REST API。

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

使用 $ 變數擷取路徑區段

驗證

auth 變數

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

使用驗證自訂權利要求

現有資料與新資料

參照其他路徑中的資料

驗證資料

JavaScript

Objective-C

Swift

Java

REST

JavaScript

Objective-C

Swift

Java

REST

以查詢為準規則

後續步驟

`auth` 變數