瞭解即時資料庫安全性規則語言的核心語法

Firebase 即時資料庫安全性規則可讓您控管資料庫中儲存的資料存取權。靈活的規則語法可讓您建立任何符合的規則，從資料庫的所有寫入作業，到個別節點上的作業皆可。

即時資料庫安全性規則是資料庫的宣告式設定。也就是說，規則與產品邏輯分開定義。這有許多優點：用戶端不必負責強制執行安全性，有瑕疵的實作不會影響您的資料，而最重要的是，您不需要透過中介裁判 (例如伺服器) 來保護資料。

本主題說明即時資料庫安全性規則的基本語法和結構，用於建立完整的規則集。

建立安全性規則

即時資料庫安全性規則是由 JSON 文件內含的類似 JavaScript 運算式組成。規則的結構應遵循資料庫中儲存的資料結構。

基本規則會識別一組要保護的節點、涉及的存取方法 (例如讀取、寫入)，以及允許或拒絕存取權的「條件」。在以下範例中，我們的條件將是簡單的 true 和 false 陳述式，但在下一節中，我們將介紹更具動態性的條件表達方式。

舉例來說，如果我們嘗試在 parent_node 下保護 child_node，一般語法如下：

{
  "rules": {
    "parent_node": {
      "child_node": {
        ".read": <condition>,
        ".write": <condition>,
        ".validate": <condition>,
      }
    }
  }
}

讓我們套用這個模式。舉例來說，假設您要追蹤一長串訊息，並擁有如下所示的資料：

{
  "messages": {
    "message0": {
      "content": "Hello",
      "timestamp": 1405704370369
    },
    "message1": {
      "content": "Goodbye",
      "timestamp": 1405704395231
    },
    ...
  }
}

您的規則結構必須相似。以下是適用於此資料結構的唯讀安全性規則。本範例說明如何指定要套用規則的資料庫節點，以及在這些節點評估規則的條件。

{
  "rules": {
    // For requests to access the 'messages' node...
    "messages": {
      // ...and the individual wildcarded 'message' nodes beneath
      // (we'll cover wildcarding variables more a bit later)....
      "$message": {

        // For each message, allow a read operation if <condition>. In this
        // case, we specify our condition as "true", so read access is always granted.
        ".read": "true",

        // For read-only behavior, we specify that for write operations, our
        // condition is false.
        ".write": "false"
      }
    }
  }
}

基本規則操作

根據在資料上執行的作業類型，有三種強制執行安全性的規則：.write、.read 和 .validate。以下簡要說明這些目的：

規則類型
.read 說明是否允許使用者讀取資料，以及允許讀取的時間。
.write 說明是否允許寫入資料，以及允許寫入資料的時間。
.validate 定義正確格式的值會長什麼樣子、是否有子項屬性，以及資料類型。

萬用字元擷取變數

所有規則陳述式都會指向節點。陳述式可以指向特定節點，或使用 $ 萬用字元擷取變數，指向階層中某個層級的節點組合。使用這些擷取變數來儲存節點鍵的值，以供後續的規則陳述式使用。這項技巧可讓您編寫更複雜的 Rules 條件，我們會在下一主題中進一步說明。

{
  "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 }
    }
  }
}

讀取及寫入規則串聯

.read 和 .write 規則會由上而下運作，較淺層的規則會覆寫較深層的規則。如果規則授予特定路徑的讀取或寫入權限，則也會授予該路徑下所有子節點的存取權。請考慮採用下列結構：

{
  "rules": {
     "foo": {
        // allows read to /foo/*
        ".read": "data.child('baz').val() === true",
        "bar": {
          /* ignored, since read was allowed already */
          ".read": false
        }
     }
  }
}

這個安全架構可讓您在 /foo/ 包含值為 true 的子項 baz 時，讀取 /bar/。/foo/bar/ 底下的 ".read": false 規則在此不會生效，因為子項路徑無法撤銷存取權。

雖然聽起來看似直觀，但這是規則語言中重要的一環，而且能讓您以最輕鬆的方式實作非常複雜的存取權限。我們稍後會在本指南的「使用者層級安全性」一節中說明這點。

請注意，.validate 規則不會層層套用。必須在階層的所有層級滿足所有驗證規則，才能允許寫入。

規則不是篩選器

規則會以整體化的方式套用。也就是說，如果該位置或父項位置沒有授予存取權的規則，讀取或寫入作業就會立即失敗。即使每個受影響的子項路徑都可存取，在父項位置讀取作業也會完全失敗請參考以下結構：

{
  "rules": {
    "records": {
      "rec1": {
        ".read": true
      },
      "rec2": {
        ".read": false
      }
    }
  }
}

如果不瞭解系統是以不可分割的方式評估規則，擷取 /records/ 路徑時可能會傳回 rec1，而不是 rec2。但實際結果是錯誤：

JavaScript
var db = firebase.database();
db.ref("records").once("value", function(snap) {
  // success method is not called
}, function(err) {
  // error callback triggered with PERMISSION_DENIED
});
Objective-C
注意：這項 Firebase 產品不適用於 App Clip 目標。
FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[_ref child:@"records"] observeSingleEventOfType:FIRDataEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
  // success block is not called
} withCancelBlock:^(NSError * _Nonnull error) {
  // cancel block triggered with PERMISSION_DENIED
}];
Swift
注意：這項 Firebase 產品不適用於 App Clip 目標。
var ref = FIRDatabase.database().reference()
ref.child("records").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // success block is not called
}, withCancelBlock: { error in
    // cancel block triggered with PERMISSION_DENIED
})
Java
FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // success method is not called
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback triggered with PERMISSION_DENIED
  });
});
REST
curl https://docs-examples.firebaseio.com/rest/records/
# response returns a PERMISSION_DENIED error

由於 /records/ 的讀取作業不可拆分，且沒有讀取規則授予 /records/ 下所有資料的存取權，因此這會擲回 PERMISSION_DENIED 錯誤。如果在 Firebase 主控台的安全模擬器中評估這項規則，我們會發現讀取作業遭到拒絕，因為沒有任何讀取規則允許存取 /records/ 路徑。不過，請注意，由於 rec1 不在我們要求的路徑中，因此系統從未評估 rec1 的規則。如要擷取 rec1，我們需直接存取：

JavaScript
var db = firebase.database();
db.ref("records/rec1").once("value", function(snap) {
  // SUCCESS!
}, function(err) {
  // error callback is not called
});
Objective-C
注意：這項 Firebase 產品不適用於 App Clip 目標。
FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[ref child:@"records/rec1"] observeSingleEventOfType:FEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
    // SUCCESS!
}];
Swift
注意：這項 Firebase 產品不適用於 App Clip 目標。
var ref = FIRDatabase.database().reference()
ref.child("records/rec1").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // SUCCESS!
})
Java
FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records/rec1");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // SUCCESS!
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback is not called
  }
});
REST
curl https://docs-examples.firebaseio.com/rest/records/rec1
# SUCCESS!

重疊陳述式

節點可套用多個規則。如果多個規則運算式可用於識別節點，如果「任何」條件為 false，則會拒絕存取方法：

{
  "rules": {
    "messages": {
      // A rule expression that applies to all nodes in the 'messages' node
      "$message": {
        ".read": "true",
        ".write": "true"
      },
      // A second rule expression applying specifically to the 'message1` node
      "message1": {
        ".read": "false",
        ".write": "false"
      }
    }
  }
}

在上述範例中，即使第一個規則一律為 true，但第二個規則一律為 false，因此系統會拒絕對 message1 節點的讀取作業。

後續步驟

您可以進一步瞭解 Firebase 即時資料庫安全性規則：