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

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

إعداد حزمة SDK للمشرف

للبدء في استخدام قاعدة بيانات Firebase في الوقت الفعلي على خادمك، عليك أولاً إعداد مدير SDK في Firebase باللغة التي تختارها.

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

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

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

مستويات الوصول إلى حزمة مدير 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())
Go
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 الذي تستخدمه قواعد قاعدة البيانات. في عنصر auth المخصّص هذا، اضبط الحقل uid على المعرّف الذي استخدمته لتمثيل خدمتك في قواعد الأمان.

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())
Go
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())
Go
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)

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