تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إدارة قواعد أمان Firebase ونشرها

توفّر لك منصة Firebase عدة أدوات لإدارة Security Rules، وكل أداة منها مفيدة في حالات معيّنة، وتستخدم كل أداة واجهة برمجة التطبيقات نفسها لإدارة قواعد أمان Firebase في الخلفية.

بغض النظر عن الأداة المستخدَمة لاستدعاء Management API، فإنّها:

يتم استيعاب مصدر القواعد: مجموعة من القواعد، عادةً ما تكون ملف رمز برمجي يحتوي على عبارات Firebase Security Rules.
يخزّن المصدر الذي تم استيراده على شكل مجموعة قواعد غير قابلة للتغيير.
يتتبّع نشر كل مجموعة قواعد في إصدار. تبحث الخدمات التي تم تفعيل قواعد أمان Firebase فيها عن الإصدار الخاص بمشروع ما لتقييم كل طلب لمورد آمن.
توفّر إمكانية إجراء اختبارات نحوية ودلالية لمجموعة قواعد.

استخدام واجهة سطر الأوامر (CLI) في Firebase

باستخدام واجهة سطر الأوامر في Firebase، يمكنك تحميل المصادر المحلية ونشر الإصدارات. يتيح لك الأمر Firebase Local Emulator Suite في واجهة سطر الأوامر إجراء اختبار محلي كامل للمصادر.

يتيح لك استخدام واجهة سطر الأوامر (CLI) الاحتفاظ بقواعدك ضمن التحكّم في الإصدارات باستخدام الرمز البرمجي للتطبيق ونشر القواعد كجزء من عملية النشر الحالية.

إنشاء ملف إعداد

عند ضبط مشروع Firebase الخاص بك باستخدام واجهة سطر أوامر Firebase، يتم إنشاء ملف إعداد .rules في دليل مشروعك. استخدِم الأمر التالي لبدء ضبط مشروع Firebase:

Cloud Firestore

// Set up Firestore in your project directory, creates a .rules file
firebase init firestore

Realtime Database

// Set up Realtime Database in your project directory, creates a .rules file
firebase init database

Cloud Storage

// Set up Storage in your project directory, creates a .rules file
firebase init storage

تعديل القواعد وتحديثها

عدِّل مصدر القواعد مباشرةً في ملف إعداد .rules.

تأكَّد من أنّ أي تعديلات تجريها في واجهة سطر أوامر Firebase تظهر في وحدة تحكّم Firebase، أو أنّك تُجري التعديلات باستمرار باستخدام وحدة تحكّم Firebase أو Firebase CLI. وإلا، قد يتم استبدال أي تعديلات تم إجراؤها في وحدة تحكّم "Firebase".

اختبار التعديلات

توفّر Local Emulator Suite محاكيات لجميع المنتجات التي تم تفعيل قواعد الأمان فيها. يُجري محرّك "قواعد الأمان" لكل محاكي تقييمًا نحويًا ودلاليًا للقواعد، وبالتالي يتجاوز الاختبار النحوي الذي توفّره واجهة برمجة التطبيقات لإدارة "قواعد الأمان".

إذا كنت تعمل مع واجهة سطر الأوامر، فإنّ المجموعة هي أداة ممتازة Firebase Security Rules للاختبار. استخدِم Local Emulator Suite لاختبار التحديثات محليًا والتأكّد من أنّ Security Rules في تطبيقك تعمل بالشكل المطلوب.

نشر التحديثات

بعد تعديل Security Rules واختباره، يمكنك نشر المصادر في بيئة الإنتاج.

بالنسبة إلى Cloud Firestore Security Rules، يمكنك ربط ملفات .rules بقواعد البيانات التلقائية والإضافية المسمّاة من خلال مراجعة ملف firebase.json وتعديله.

استخدِم الأوامر التالية لنشر Security Rules بشكل انتقائي بمفرده أو نشره كجزء من عملية النشر العادية.

Cloud Firestore

// Deploy rules for all databases configured in your firebase.json
firebase deploy --only firestore:rules

// Deploy rules for the specified database configured in your firebase.json
firebase deploy --only firestore:<databaseId>

Realtime Database

// Deploy your .rules file
firebase deploy --only database

Cloud Storage

// Deploy your .rules file
firebase deploy --only storage

استخدام وحدة تحكّم Firebase

يمكنك أيضًا تعديل Security Rules المصادر ونشرها على شكل إصدارات من وحدة تحكّم Firebase. يتم إجراء الاختبار النحوي أثناء التعديل في واجهة مستخدم وحدة تحكّم Firebase، ويتوفّر الاختبار الدلالي باستخدام Security Rules Playground.

تعديل القواعد وتحديثها

افتح وحدة تحكّم Firebase واختَر مشروعك.
بعد ذلك، اختَر Realtime Database أو Cloud Firestore أو Storage من قائمة التنقّل في المنتج، ثم انقر على القواعد للانتقال إلى محرِّر Security Rules.
عدِّل قواعدك مباشرةً في المحرِّر.

اختبار التعديلات

بالإضافة إلى اختبار البنية في واجهة مستخدم المحرِّر، يمكنك اختبار سلوك Security Rules الدلالي باستخدام قاعدة بيانات مشروعك وموارد التخزين، مباشرةً في وحدة تحكّم Firebase، باستخدام Security Rules Playground. افتح شاشة Rules Playground في محرِّر "Security Rules"، وعدِّل الإعدادات وانقر على تشغيل. ابحث عن رسالة التأكيد في أعلى المحرِّر.

نشر التحديثات

بعد التأكّد من أنّ التعديلات هي ما تتوقّعه، انقر على نشر.

استخدام Admin SDK

يمكنك استخدام Admin SDK لـ Node.js rulesets. من خلال هذا الوصول الآلي، يمكنك إجراء ما يلي:

تنفيذ أدوات مخصّصة ونصوص برمجية ولوحات بيانات ومسارات CI/CD لإدارة القواعد
إدارة القواعد بسهولة أكبر في مشاريع Firebase المتعدّدة

عند تعديل القواعد آليًا، من المهم جدًا تجنُّب إجراء تغييرات غير مقصودة على عناصر التحكّم في الوصول إلى تطبيقك. اكتب رمز Admin SDK مع وضع الأمان في الاعتبار، خاصةً عند تعديل القواعد أو نشرها.

هناك أمر آخر مهم يجب مراعاته وهو أنّ إصدارات Firebase Security Rules تستغرق بضع دقائق ليتم نشرها بالكامل. عند استخدام Admin SDK لنشر القواعد، احرص على تجنُّب حالات السباق التي يعتمد فيها تطبيقك على القواعد التي لم يكتمل نشرها بعد. إذا كانت حالة الاستخدام تتطلّب تعديلات متكرّرة على قواعد التحكّم في الوصول، ننصحك باستخدام حلول Cloud Firestore، المصمَّمة للحدّ من حالات السباق على الرغم من التعديلات المتكرّرة.

يُرجى أيضًا مراعاة الحدود التالية:

يجب أن تكون القواعد أصغر من 256 كيلوبايت من النص بترميز UTF-8 عند تسلسلها.
يمكن أن يحتوي المشروع على 2500 مجموعة قواعد منشورة كحد أقصى. بعد بلوغ هذا الحدّ، عليك حذف بعض مجموعات القواعد القديمة قبل إنشاء مجموعات جديدة.

إنشاء مجموعات قواعد Cloud Storage أو Cloud Firestore ونشرها

يمكن أن يتضمّن سير العمل النموذجي لإدارة قواعد الأمان باستخدام Admin SDK ثلاث خطوات منفصلة:

إنشاء مصدر ملف قواعد (اختياري)
إنشاء مجموعة قواعد
إصدار مجموعة القواعد الجديدة أو نشرها

توفّر حزمة تطوير البرامج (SDK) طريقة لدمج هذه الخطوات في طلب بيانات من واجهة برمجة التطبيقات واحد لقواعد الأمان Cloud Storage وCloud Firestore. على سبيل المثال:

    const source = `service cloud.firestore {
      match /databases/{database}/documents {
        match /carts/{cartID} {
          allow create: if request.auth != null && request.auth.uid == request.resource.data.ownerUID;
          allow read, update, delete: if request.auth != null && request.auth.uid == resource.data.ownerUID;
        }
      }
    }`;
    // Alternatively, load rules from a file
    // const fs = require('fs');
    // const source = fs.readFileSync('path/to/firestore.rules', 'utf8');

    await admin.securityRules().releaseFirestoreRulesetFromSource(source);

ينطبق هذا النمط نفسه على قواعد Cloud Storage التي تتضمّن releaseFirestoreRulesetFromSource().

بدلاً من ذلك، يمكنك إنشاء ملف القواعد كعنصر في الذاكرة، وإنشاء مجموعة القواعد، ونشرها بشكل منفصل للتحكّم في هذه الأحداث بشكل أدق. على سبيل المثال:

    const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
    const rs = await admin.securityRules().createRuleset(rf);
    await admin.securityRules().releaseFirestoreRuleset(rs);

تعديل مجموعات القواعد في "Realtime Database"

لتعديل مجموعات قواعد Realtime Database باستخدام Admin SDK، استخدِم الطريقتَين getRules() وsetRules() في admin.database. يمكنك استرداد مجموعات القواعد بتنسيق JSON أو كسلسلة تتضمّن تعليقات.

لتعديل مجموعة قواعد:

    const source = `{
      "rules": {
        "scores": {
          ".indexOn": "score",
          "$uid": {
            ".read": "$uid == auth.uid",
            ".write": "$uid == auth.uid"
          }
        }
      }
    }`;
    await admin.database().setRules(source);

إدارة مجموعات القواعد

للمساعدة في إدارة مجموعات القواعد الكبيرة، تتيح لك Admin SDK عرض جميع القواعد الحالية باستخدام admin.securityRules().listRulesetMetadata. على سبيل المثال:

    const allRulesets = [];
    let pageToken = null;
    while (true) {
      const result = await admin.securityRules().listRulesetMetadata(pageToken: pageToken);
      allRulesets.push(...result.rulesets);
      pageToken = result.nextPageToken;
      if (!pageToken) {
        break;
      }
    }

    const thirtyDays = new Date(Date.now() - THIRTY_DAYS_IN_MILLIS);
    const promises = [];
    allRulesets.forEach((rs) => {
      if (new Date(rs.createTime) < thirtyDays) {
        promises.push(admin.securityRules().deleteRuleset(rs.name));
      }
    });
    await Promise.all(promises);
    console.log(`Deleted ${promises.length} rulesets.`);

استخدام REST API

إنّ الأدوات الموضّحة أعلاه مناسبة لمختلف مهام سير العمل، بما في ذلك إدارة Firebase Security Rules لقواعد بيانات Cloud Firestore متعدّدة في مشروعك، ولكن قد تحتاج إلى إدارة Firebase Security Rules ونشرها باستخدام Management API نفسها. تمنحك Management API أكبر قدر من المرونة.

يُرجى أيضًا مراعاة الحدود التالية:

يجب أن تكون القواعد أصغر من 256 كيلوبايت من النص بترميز UTF-8 عند تسلسلها.
يمكن أن يحتوي المشروع على 2500 مجموعة قواعد منشورة كحد أقصى. بعد بلوغ هذا الحدّ، عليك حذف بعض مجموعات القواعد القديمة قبل إنشاء مجموعات جديدة.

إنشاء مجموعات قواعد Cloud Firestore أو Cloud Storage ونشرها باستخدام REST

تستخدم الأمثلة في هذا القسم Firestore Security Rules، على الرغم من أنّها تنطبق على Cloud Storage Security Rules أيضًا.

تستخدم الأمثلة أيضًا cURL لطلب بيانات من واجهة برمجة التطبيقات. تم حذف خطوات إعداد رموز المصادقة وتمريرها. يمكنك تجربة واجهة برمجة التطبيقات هذه باستخدام "مستكشف واجهات برمجة التطبيقات" المدمج مع المستندات المرجعية.

في ما يلي الخطوات المعتادة لإنشاء مجموعة قواعد ونشرها باستخدام Management API:

إنشاء مصادر ملفات القواعد
إنشاء مجموعة قواعد
انشر مجموعة القواعد الجديدة.

إنشاء مصدر

لنفترض أنّك تعمل على مشروع Firebase باسم secure_commerce وتريد نشر Cloud Firestore Security Rules مقفلة في قاعدة بيانات في مشروعك باسم east_store.

يمكنك تنفيذ هذه القواعد في ملف firestore.rules.

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

إنشاء مجموعة قواعد

بعد ذلك، أنشئ ملفًا مرجعيًا بترميز base64 لهذا الملف. يمكنك بعد ذلك استخدام المصدر في هذا الملف لتعبئة الحمولة اللازمة لإنشاء مجموعة قواعد باستخدام طلب REST projects.rulesets.create. هنا، استخدِم الأمر cat لإدراج محتوى firestore.rules في حمولة REST.

للتتبُّع، من أجل ربط هذا بقاعدة بيانات "east_store"، اضبط "attachment_point" على "east_store".

curl -X POST -d '{
  "source": {
    "files": [
      {
        "content": "' $(cat storage.rules) '",
        "name": "firestore.rules",
        "fingerprint": <sha fingerprint>
      },
    "attachment_point": "firestore.googleapis.com/databases/east_store"
    ]
  }
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets'

تعرض واجهة برمجة التطبيقات استجابة تحقّق واسم مجموعة قواعد، على سبيل المثال projects/secure_commerce/rulesets/uuid123.

إصدار (نشر) مجموعة قواعد

إذا كانت مجموعة القواعد صالحة، فإن الخطوة الأخيرة هي نشر مجموعة القواعد الجديدة في إصدار مسمى.

curl -X POST -d '{
  "name": "projects/secure_commerce/releases/cloud.firestore/east_store"  ,
  "rulesetName": "projects/secure_commerce/rulesets/uuid123"
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/releases'

يُرجى العِلم أنّ إصدارات Firebase Security Rules تستغرق بضع دقائق ليتم نشرها بالكامل. عند استخدام REST API للإدارة في عملية النشر، تأكَّد من تجنُّب حالات السباق التي يعتمد فيها تطبيقك على الفور على قواعد لم يكتمل نشرها بعد.

تعديل مجموعات قواعد "Realtime Database" باستخدام REST

يوفّر Realtime Database واجهة REST الخاصة به لإدارة Security Rules. يُرجى الاطّلاع على إدارة Realtime Database Security Rules في Firebase عبر REST.

إدارة مجموعات القواعد باستخدام REST

للمساعدة في إدارة عمليات نشر القواعد الكبيرة، بالإضافة إلى طريقة REST لإنشاء مجموعات القواعد والإصدارات، توفّر واجهة برمجة التطبيقات Management API طرقًا لإجراء ما يلي:

إدراج مجموعات القواعد والحصول عليها وحذفها
إدراج إصدارات القواعد والحصول عليها وحذفها

بالنسبة إلى عمليات النشر الكبيرة جدًا التي تصل إلى الحد الأقصى البالغ 2500 مجموعة قواعد بمرور الوقت، يمكنك إنشاء منطق لحذف أقدم القواعد في دورة زمنية ثابتة. على سبيل المثال، لحذف جميع مجموعات القواعد التي تم نشرها لأكثر من 30 يومًا، يمكنك استدعاء طريقة projects.rulesets.list، وتحليل قائمة JSON لكائنات Ruleset على مفاتيح createTime، ثم استدعاء project.rulesets.delete على مجموعات القواعد المقابلة بواسطة ruleset_id.

اختبار التعديلات باستخدام REST

أخيرًا، تتيح لك Management API إجراء اختبارات نحوية ودلالية على موارد Cloud Firestore وCloud Storage في مشاريع الإنتاج.

يتألف الاختبار باستخدام هذا المكوّن من واجهة برمجة التطبيقات مما يلي:

تحديد عنصر JSON من النوع TestSuite لتمثيل مجموعة من عناصر TestCase
جارٍ إرسال TestSuite
أدّى التحليل إلى عرض TestResult عنصر.

لنحدّد عنصر TestSuite باستخدام TestCase واحد في ملف testcase.json. في هذا المثال، نمرّر مصدر لغة Security Rules مضمّنًا مع حمولة REST، إلى جانب الحزمة الاختبارية التي سيتم تشغيلها على هذه القواعد. نحدّد توقّع تقييم القواعد، وطلب العميل الذي سيتم اختبار مجموعة القواعد وفقًا له. يمكنك أيضًا تحديد مدى اكتمال تقرير الاختبار باستخدام القيمة "FULL" للإشارة إلى أنّه يجب تضمين نتائج جميع تعبيرات لغة Security Rules في التقرير، بما في ذلك التعبيرات التي لم تتطابق مع الطلب.

 {
  "source":
  {
    "files":
    [
      {
        "name": "firestore.rules",
        "content": "service cloud.firestore {
          match /databases/{database}/documents {
            match /users/{userId}{
              allow read: if (request.auth.uid == userId);
            }
            function doc(subpath) {
              return get(/databases/$(database)/documents/$(subpath)).data;
            }
            function isAccountOwner(accountId) {
              return request.auth.uid == accountId 
                  || doc(/users/$(request.auth.uid)).accountId == accountId;
            }
            match /licenses/{accountId} {
              allow read: if isAccountOwner(accountId);
            }
          }
        }"
      }
    ]
  },
  "testSuite":
  {
    "testCases":
    [
      {
        "expectation": "ALLOW",
        "request": {
           "auth": {"uid": "123"},
           "path": "/databases/(default)/documents/licenses/abcd",
           "method": "get"},
        "functionMocks": [
            {
            "function": "get",
            "args": [{"exact_value": "/databases/(default)/documents/users/123"}],
            "result": {"value": {"data": {"accountId": "abcd"}}}
            }
          ]
      }
    ]
  }
}

يمكننا بعد ذلك إرسال هذا TestSuite للتقييم باستخدام طريقة projects.test.

curl -X POST -d '{
    ' $(cat testcase.json) '
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets/uuid123:test'

The returned TestReport (containing test SUCCESS/FAILURE status, lists of debug messages, lists of visited Rules expressions and their evaluation reports) would confirm with status SUCCESS that access is properly allowed.

إدارة أذونات Cloud Storage Security Rules في جميع الخدمات

إذا أنشأت Cloud Storage Security Rules تستخدم محتوى مستندات Cloud Firestore لتقييم شروط الأمان، سيُطلب منك في وحدة تحكّم Firebase أو واجهة سطر أوامر Firebase تفعيل الأذونات لربط المنتجَين.

إذا قرّرت إيقاف ميزة الأمان هذه على مستوى الخدمات:

أولاً، قبل إيقاف الميزة، عليك تعديل قواعدك وإزالة جميع العبارات التي تستخدم دوال Security Rules للوصول إلى Cloud Firestore. وإلا، بعد إيقاف الميزة، ستؤدي تقييمات Security Rules إلى تعذُّر تنفيذ طلبات Storage.
استخدِم صفحة إدارة الهوية وإمكانية الوصول في Google Cloud Console لحذف دور "وكيل خدمة Firestore لقواعد Firebase" باتّباع دليل Cloud لإبطال الأدوار.

ملاحظة: في صفحة إدارة الهوية وإمكانية الوصول، ضَع علامة في المربّع "تضمين عمليات منح الأدوار التي تقدّمها Google" للاطّلاع على جميع الأدوار.
ملاحظة: في صفحة إدارة الهوية وإمكانية الوصول، من المفترض أن يظهر لك حساب خدمة "مساحة تخزين Firebase" الذي ينتهي معرّفه بـ @gcp-sa-firebasestorage.iam.gserviceaccount.com. إذا كانت قواعد الخدمات المتعددة مفعَّلة، سيظهر لك دور "وكيل خدمة Firestore لقواعد Firebase" مُدرجًا.

سيُطلب منك إعادة تفعيل الميزة في المرة التالية التي تحفظ فيها قواعد مشتركة بين الخدمات من واجهة سطر الأوامر في Firebase أو وحدة تحكّم Firebase.

إدارة قواعد أمان Firebase ونشرها تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

استخدام واجهة سطر الأوامر (CLI) في Firebase

إنشاء ملف إعداد

Cloud Firestore

Realtime Database

Cloud Storage

تعديل القواعد وتحديثها

اختبار التعديلات

نشر التحديثات

Cloud Firestore

Realtime Database

Cloud Storage

استخدام وحدة تحكّم Firebase

تعديل القواعد وتحديثها

اختبار التعديلات

نشر التحديثات

استخدام Admin SDK

إنشاء مجموعات قواعد Cloud Storage أو Cloud Firestore ونشرها

تعديل مجموعات القواعد في "Realtime Database"

إدارة مجموعات القواعد

استخدام REST API

إنشاء مجموعات قواعد Cloud Firestore أو Cloud Storage ونشرها باستخدام REST

إنشاء مصدر

إنشاء مجموعة قواعد

إصدار (نشر) مجموعة قواعد

تعديل مجموعات قواعد "Realtime Database" باستخدام REST

إدارة مجموعات القواعد باستخدام REST

اختبار التعديلات باستخدام REST

إدارة أذونات Cloud Storage Security Rules في جميع الخدمات

إدارة قواعد أمان Firebase ونشرها