דף זה תורגם על ידי Cloud Translation API.

שימוש בתנאים בכללי האבטחה של מסדי נתונים בזמן אמת

המדריך הזה מבוסס על המדריך ללמד את שפת כללי האבטחה של Firebase, ומסביר איך להוסיף תנאים לכללי האבטחה של מסדי נתונים בזמן אמת ב-Firebase.

אבן הבניין העיקרית של כללי האבטחה של מסדי נתונים בזמן אמת הוא התנאי. תנאי הוא ביטוי בוליאני שקובע אם צריך לאפשר או לדחות פעולה מסוימת. לכללים בסיסיים, השימוש ב-literals של true ו-false בתור תנאים עובד מצוין. עם זאת, השפה של כללי האבטחה של Realtime Database מאפשרת לכתוב תנאים מורכבים יותר, שיכולים:

בדיקת אימות המשתמשים
השוואה בין הנתונים הקיימים לנתונים החדשים שנשלחו
גישה לחלקים שונים של מסד הנתונים והשוואה ביניהם
אימות נתונים נכנסים
שימוש במבנה של שאילתות נכנסות ללוגיקה של אבטחה

שימוש במשתני $ כדי לתעד קטעי נתיב

כדי לתעד חלקים מהנתיב בקריאה או כתיבה, צריך להצהיר (declare) על משתנים עם הקידומת $. הוא משמש כתו כללי לחיפוש, ומאחסן את הערך של המפתח הזה לשימוש בתנאי הכללים:

{
  "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 בכללי האבטחה של מסדי נתונים בזמן אמת יאוכלס בפרטי המשתמש. המידע הזה כולל את המזהה הייחודי שלהם (uid) וגם נתוני חשבון מקושרים, כמו מזהה Facebook או כתובת אימייל, ומידע נוסף. אם מטמיעים ספק אימות מותאם אישית, אפשר להוסיף שדות משלכם לעומס העבודה של האימות של המשתמש.

בקטע הזה מוסבר איך לשלב את שפת כללי האבטחה של מסד הנתונים בזמן אמת ב-Firebase עם פרטי אימות של המשתמשים. שילוב של שני המושגים האלה מאפשר לכם לשלוט בגישה לנתונים על סמך זהות המשתמש.

המשתנה `auth`

המשתנה auth שהוגדר מראש בכללים הוא null לפני שמתבצע האימות.

אחרי שמשתמש מאומת באמצעות אימות ב-Firebase, הוא מכיל את המאפיינים הבאים:

ספק	שיטת האימות שבה נעשה שימוש ('password', 'anonymous', 'facebook', 'github', 'google' או 'twitter').
Uid	מזהה משתמש ייחודי, שמבטיח להיות ייחודי בכל הספקים.
token	תוכן האסימון המזהה של Firebase Auth. פרטים נוספים זמינים במסמכי העזרה של `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 מייצג את תוצאת המיזוג של הנתונים החדשים שנכתבים והנתונים הקיימים.

לדוגמה, הכלל הזה יאפשר לנו ליצור רשומות חדשות או למחוק רשומות קיימות, אבל לא לבצע שינויים בנתונים קיימים שאינם null:

// 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 שמאפשרת תאריכים רק בפורמט YYYY-MM-DD, בין השנים 1900-2099, שנבדקת באמצעות ביטוי רגולרי.

".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 Realtime Database. כדאי להביא בחשבון את הכללים הבאים:

{
  "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 הזה לא זמין ביעד של קטע מקדים לאפליקציה.

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 הזה לא זמין ביעד של קטע מקדים לאפליקציה.

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 הזה לא זמין ביעד של קטע מקדים לאפליקציה.

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 הזה לא זמין ביעד של קטע מקדים לאפליקציה.

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

אפשר גם להשתמש בכללים שמבוססים על שאילתות כדי להגביל את כמות הנתונים שהלקוח מוריד באמצעות פעולות קריאה.

לדוגמה, הכלל הבא מגביל את גישת הקריאה רק ל-1,000 התוצאות הראשונות של שאילתה, לפי סדר העדיפות:

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. זמינים בכללי האבטחה של Realtime Database.

ביטויים של כללים מבוססי-שאילתות
ביטוי	סוג	תיאור
query.orderByKey query.orderByPriority query.orderByValue	בוליאני	הערך הזה נכון לשאילתות שממוינות לפי מפתח, עדיפות או ערך. אחרת, הערך יהיה False.
query.orderByChild	מחרוזת null	משתמשים במחרוזת כדי לייצג את הנתיב היחסי לצומת צאצא. לדוגמה, `query.orderByChild === "address/zip"`. אם השאילתה לא ממוינת לפי צומת צאצא, הערך הזה הוא null.
query.startAt query.endAt query.equalTo	string number boolean null	מאחזר את הגבולות של השאילתה שמבצעת או מחזירה null אם לא הוגדר גבולות.
query.limitToFirst query.limitToLast	מספר null	הפונקציה מאחזרת את המגבלה על השאילתה שמופעלת, או מחזירה ערך null אם לא מוגדרת מגבלה.

השלבים הבאים

אחרי הדיון על התנאים תבינו טוב יותר את Rules ואתם מוכנים:

איך מטפלים בתרחישי לדוגמה מרכזיים, ומה תהליך העבודה לפיתוח, בדיקה ופריסה של Rules:

מידע נוסף על כל המשתנים Rules שהוגדרו מראש שאפשר להשתמש בהם כדי ליצור תנאים
כתבו כללים שמתייחסים לתרחישים נפוצים.
כדי להרחיב את הידע שלכם, כדאי לקרוא על מצבים שבהם צריך לזהות כללים לא מאובטחים ולהימנע מהם.
מידע על Firebase Local Emulator Suite ועל האופן שבו אפשר להשתמש בו כדי לבדוק את Rules
כאן מפורטות השיטות הזמינות לפריסה של Rules.

מידע על תכונות Rules ספציפיות ל-Realtime Database:

איך מוסיפים את Realtime Database לאינדקס
לעיין ב-API ל-REST לפריסה של Rules.

שימוש בתנאים בכללי האבטחה של מסדי נתונים בזמן אמת

שימוש במשתני $ כדי לתעד קטעי נתיב

אימות

המשתנה auth

בניית מסד הנתונים שלך כך שיתמוך בתנאי האימות

עבודה עם הצהרות בהתאמה אישית של אימות

נתונים קיימים לעומת נתונים חדשים

הפניה לנתונים בנתיב אחר

אימות נתונים

JavaScript

Objective-C

Swift

Java

REST

JavaScript

Objective-C

Swift

Java

REST

כללים מבוססי-שאילתות

השלבים הבאים

המשתנה `auth`