مقدمة عن حزمة تطوير البرامج (SDK) لقاعدة بيانات المشرف

باستخدام مدير SDK، يمكنك قراءة بيانات قاعدة بيانات الوقت الفعلي وكتابتها بامتيازات مشرف كاملة أو بامتيازات محدودة أكثر دقة. في هذا المستند، سنرشدك خلال عملية إضافة مدير SDK في Firebase إلى مشروعك للوصول إلى Firebase Realtime Database.

يمكن إنشاء نُسخ Realtime Database في مناطق جغرافية مختلفة، باستخدام مخطّطات عناوين URL منفصلة لكل من firebaseio.com وfirebasedatabase.app. Admin SDK يمكن أن تستخدم طرق ضبط عناوين URL أيًا من المخططَين. للاطّلاع على المناطق ومخطّطات عناوين URL المتاحة حاليًا، يُرجى مراجعة موضوع الأدلة حول اختيار المواقع الجغرافية في مشاريع Firebase.

إعداد مدير SDK

لبدء استخدام "قاعدة بيانات Firebase في الوقت الفعلي" على خادمك، عليك أولاً إعداد حزمة تطوير البرامج (SDK) لمشرف Firebase باللغة التي تختارها.

إذا كنت مهتمًا باستخدام حزمة تطوير البرامج (SDK) لـ Node.js كعميل لوصول المستخدم النهائي (على سبيل المثال، في تطبيق Node.js لسطح المكتب أو تطبيق إنترنت الأشياء)، بدلاً من إذن الوصول الإداري من بيئة مميزة (مثل الخادم)، عليك بدلاً من ذلك اتباع تعليمات إعداد JavaScript SDK للعميل.

مصادقة مدير SDK

قبل الوصول إلى Firebase Realtime Database من خادم باستخدام "مدير SDK في Firebase"، عليك مصادقة الخادم باستخدام Firebase. عند مصادقة خادم، بدلاً من تسجيل الدخول باستخدام بيانات اعتماد حساب مستخدم كما تفعل في تطبيق عميل، يمكنك المصادقة باستخدام حساب خدمة يحدّد الخادم الخاص بك في Firebase.

يمكنك الحصول على مستويَين مختلفَين من الوصول عند المصادقة باستخدام مدير SDK في Firebase:

مستويات الوصول إلى مصادقة مدير SDK في Firebase
امتيازات المشرف	إذن كامل بالقراءة والكتابة في Realtime Database لمشروع معيّن يُرجى استخدام هذا الدور بحذر لإكمال المهام الإدارية، مثل نقل البيانات أو إعادة الهيكلة، التي تتطلّب وصولاً غير مقيّد إلى موارد مشروعك.
امتيازات محدودة	الوصول إلى Realtime Database الخاص بالمشروع، ويقتصر على الموارد التي يحتاجها الخادم فقط. استخدِم هذا المستوى لإكمال المهام الإدارية التي تتطلّب متطلبات وصول محدّدة. على سبيل المثال، عند تشغيل مهمة تلخيص تقرأ البيانات في قاعدة البيانات بأكملها، يمكنك الحماية من عمليات الكتابة غير المقصودة من خلال ضبط قاعدة أمان للقراءة فقط ثم إعداد حزمة SDK للمشرف بامتيازات محدودة بهذه القاعدة.

المصادقة باستخدام امتيازات المشرف

عند إعداد مدير SDK في Firebase باستخدام بيانات اعتماد حساب خدمة يتضمّن دور المحرِّر في مشروع Firebase، يكون لهذا المثيل إذن وصول كامل للقراءة والكتابة إلى Realtime Database في مشروعك.

Java

// Initialize the SDK with Application Default Credentials
FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    // The database URL depends on the location of the database
    .setDatabaseUrl("https://DATABASE_NAME.firebaseio.com")
    .build();
FirebaseApp.initializeApp(options);

// As an admin, the app has access to read and write all data, regardless of Security Rules
DatabaseReference ref = FirebaseDatabase.getInstance()
    .getReference("restricted_access/secret_document");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot dataSnapshot) {
    Object document = dataSnapshot.getValue();
    System.out.println(document);
  }

  @Override
  public void onCancelled(DatabaseError error) {
  }
});

Node.js

import { initializeApp } from 'firebase-admin/app';
import { getDatabase } from 'firebase-admin/database';

// Initialize the app with Application Default Credentials, granting admin privileges
initializeApp({
  // The database URL depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com"
});

// As an admin, the app has access to read and write all data, regardless of Security Rules
const db = getDatabase();
const ref = db.ref("restricted_access/secret_document");
ref.once("value", (snapshot) => {
  console.log(snapshot.val());
});

Python

import firebase_admin
from firebase_admin import credentials
from firebase_admin import db

# Fetch the service account key JSON file contents
cred = credentials.Certificate('path/to/serviceAccountKey.json')

# Initialize the app with a service account, granting admin privileges
firebase_admin.initialize_app(cred, {
    'databaseURL': 'https://databaseName.firebaseio.com'
})

# As an admin, the app has access to read and write all data, regradless of Security Rules
ref = db.reference('restricted_access/secret_document')
print(ref.get())

متابعة

ctx := context.Background()
conf := &firebase.Config{
	DatabaseURL: "https://databaseName.firebaseio.com",
}
// Fetch the service account key JSON file contents
opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")

// Initialize the app with a service account, granting admin privileges
app, err := firebase.NewApp(ctx, conf, opt)
if err != nil {
	log.Fatalln("Error initializing app:", err)
}

client, err := app.Database(ctx)
if err != nil {
	log.Fatalln("Error initializing database client:", err)
}

// As an admin, the app has access to read and write all data, regradless of Security Rules
ref := client.NewRef("restricted_access/secret_document")
var data map[string]interface{}
if err := ref.Get(ctx, &data); err != nil {
	log.Fatalln("Error reading from database:", err)
}
fmt.Println(data)

لا تملك خدمتك سوى إذن الوصول نفسه الذي يملكه حساب الخدمة المستخدَم للمصادقة عليها. على سبيل المثال، يمكنك حصر خدمتك في إذن بالقراءة فقط باستخدام حساب خدمة يتضمّن دور "القارئ" في مشروعك. وبالمثل، لا يمكن لحساب خدمة ليس له دور في المشروع قراءة أي بيانات أو كتابتها.

المصادقة باستخدام امتيازات محدودة

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

{
  "rules": {
    "public_resource": {
      ".read": true,
      ".write": true
    },
    "some_resource": {
      ".read": "auth.uid === 'my-service-worker'",
      ".write": false
    },
    "another_resource": {
      ".read": "auth.uid === 'my-service-worker'",
      ".write": "auth.uid === 'my-service-worker'"
    }
  }
}

بعد ذلك، على الخادم، عند إعداد تطبيق Firebase، استخدِم الخيار databaseAuthVariableOverride لإلغاء عنصر auth الذي تستخدمه قواعد قاعدة البيانات. In this custom auth object, set the uid field to the identifier you used to represent your service in your Security Rules.

Java

// Initialize the app with a custom auth variable, limiting the server's access
Map<String, Object> auth = new HashMap<String, Object>();
auth.put("uid", "my-service-worker");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    // The database URL depends on the location of the database
    .setDatabaseUrl("https://DATABASE_NAME.firebaseio.com")
    .setDatabaseAuthVariableOverride(auth)
    .build();
FirebaseApp.initializeApp(options);

// The app only has access as defined in the Security Rules
DatabaseReference ref = FirebaseDatabase
    .getInstance()
    .getReference("/some_resource");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        String res = dataSnapshot.getValue();
        System.out.println(res);
    }
});

Node.js

import { initializeApp } from 'firebase-admin/app';
import { getDatabase } from 'firebase-admin/database';

// Initialize the app with a custom auth variable, limiting the server's access
initializeApp({
  // The database URL depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com",
  databaseAuthVariableOverride: {
    uid: "my-service-worker"
  }
});

// The app only has access as defined in the Security Rules
const db = getDatabase();
const ref = db.ref("/some_resource");
ref.once("value", (snapshot) => {
  console.log(snapshot.val());
});

Python

import firebase_admin
from firebase_admin import credentials
from firebase_admin import db

# Fetch the service account key JSON file contents
cred = credentials.Certificate('path/to/serviceAccountKey.json')

# Initialize the app with a custom auth variable, limiting the server's access
firebase_admin.initialize_app(cred, {
    'databaseURL': 'https://databaseName.firebaseio.com',
    'databaseAuthVariableOverride': {
        'uid': 'my-service-worker'
    }
})

# The app only has access as defined in the Security Rules
ref = db.reference('/some_resource')
print(ref.get())

متابعة

ctx := context.Background()
// Initialize the app with a custom auth variable, limiting the server's access
ao := map[string]interface{}{"uid": "my-service-worker"}
conf := &firebase.Config{
	DatabaseURL:  "https://databaseName.firebaseio.com",
	AuthOverride: &ao,
}

// Fetch the service account key JSON file contents
opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")

app, err := firebase.NewApp(ctx, conf, opt)
if err != nil {
	log.Fatalln("Error initializing app:", err)
}

client, err := app.Database(ctx)
if err != nil {
	log.Fatalln("Error initializing database client:", err)
}

// The app only has access as defined in the Security Rules
ref := client.NewRef("/some_resource")
var data map[string]interface{}
if err := ref.Get(ctx, &data); err != nil {
	log.Fatalln("Error reading from database:", err)
}
fmt.Println(data)

في بعض الحالات، قد تحتاج إلى تقليص نطاق مدير SDK لتعمل كعميل غير مصادَق عليه. يمكنك إجراء ذلك من خلال تقديم قيمة null لتجاوز متغيّر مصادقة قاعدة البيانات.

Java

// Initialize the app with Application Default Credentials
FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    // The database URL depends on the location of the database
    .setDatabaseUrl("https://DATABASE_NAME.firebaseio.com")
    .setDatabaseAuthVariableOverride(null)
    .build();
FirebaseApp.initializeApp(options);

// The app only has access to public data as defined in the Security Rules
DatabaseReference ref = FirebaseDatabase
    .getInstance()
    .getReference("/public_resource");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        String res = dataSnapshot.getValue();
        System.out.println(res);
    }
});

Node.js

import { initializeApp } from 'firebase-admin/app';
import { getDatabase } from 'firebase-admin/database';

// Initialize the app with a null auth variable, limiting the server's access
initializeApp({
  // The database URL depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com",
  databaseAuthVariableOverride: null
});

// The app only has access to public data as defined in the Security Rules
const db = getDatabase();
const ref = db.ref("/public_resource");
ref.once("value", (snapshot) => {
  console.log(snapshot.val());
});

Python

import firebase_admin
from firebase_admin import credentials
from firebase_admin import db

# Fetch the service account key JSON file contents
cred = credentials.Certificate('path/to/serviceAccountKey.json')

# Initialize the app with a None auth variable, limiting the server's access
firebase_admin.initialize_app(cred, {
    'databaseURL': 'https://databaseName.firebaseio.com',
    'databaseAuthVariableOverride': None
})

# The app only has access to public data as defined in the Security Rules
ref = db.reference('/public_resource')
print(ref.get())

متابعة

ctx := context.Background()
// Initialize the app with a nil auth variable, limiting the server's access
var nilMap map[string]interface{}
conf := &firebase.Config{
	DatabaseURL:  "https://databaseName.firebaseio.com",
	AuthOverride: &nilMap,
}

// Fetch the service account key JSON file contents
opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")

app, err := firebase.NewApp(ctx, conf, opt)
if err != nil {
	log.Fatalln("Error initializing app:", err)
}

client, err := app.Database(ctx)
if err != nil {
	log.Fatalln("Error initializing database client:", err)
}

// The app only has access to public data as defined in the Security Rules
ref := client.NewRef("/some_resource")
var data map[string]interface{}
if err := ref.Get(ctx, &data); err != nil {
	log.Fatalln("Error reading from database:", err)
}
fmt.Println(data)

الخطوات التالية

• كيفية تنظيم البيانات لـ Realtime Database
• توسيع نطاق البيانات على مستوى نُسخ متعددة من قواعد البيانات:
• حفظ البيانات
• استرداد البيانات
• يمكنك الاطّلاع على قاعدة بياناتك في وحدة تحكّم Firebase.