إضافة حزمة تطوير البرامج (SDK) لمشرف Firebase إلى خادمك

SDK للمشرف هي مجموعة من مكتبات الخوادم التي تتيح لك التفاعل مع Firebase من البيئات المميّزة لتنفيذ إجراءات مثل:

  • قراءة بيانات قاعدة بيانات الوقت الفعلي وكتابتها مع امتيازات المشرف الكاملة
  • إرسال رسائل "المراسلة عبر السحابة الإلكترونية من Firebase" آليًا باستخدام منهج بسيط بديل لبروتوكولات خادم "المراسلة عبر السحابة الإلكترونية من Firebase".
  • يمكنك إنشاء رموز مصادقة Firebase والتحقّق منها.
  • يمكنك الوصول إلى موارد Google Cloud مثل حِزم Cloud Storage وقواعد بيانات Cloud Firestore المرتبطة بمشاريع Firebase.
  • يمكنك إنشاء وحدة تحكم المشرف المبسّطة الخاصة بك لإجراء إجراءات مثل البحث عن بيانات المستخدمين أو تغيير عنوان البريد الإلكتروني للمستخدم للمصادقة.

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

في ما يلي مصفوفة ميزات توضّح ميزات Firebase المتوافقة بكل لغة:

الميزة Node.js Java Python Go C#‎
استخراج الرموز المميّزة المخصّصة
إثبات صحة الرمز المميّز لرقم التعريف
إدارة المستخدِمين
التحكّم في الوصول من خلال المطالبات المخصَّصة
إعادة تحميل الرمز المميّز الذي تم إبطاله
استيراد المستخدمين
إدارة ملفات تعريف الارتباط للجلسة
إنشاء روابط الإجراءات عبر البريد الإلكتروني
إدارة إعدادات موفّر SAML/OIDC
دعم مواقع استئجار متعددة
قاعدة بيانات الوقت الفعلي *
المراسلة عبر السحابة الإلكترونية من Firebase
البث المتعدد "المراسلة عبر السحابة الإلكترونية من Firebase"
إدارة الاشتراكات حسب المواضيع في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
التخزين في السحابة الإلكترونية
Cloud Firestore
دوال الإدراج في قائمة الانتظار باستخدام "مهام Google"
إدارة المشاريع
قواعد الأمان
إدارة نماذج تعلُّم الآلة
الإعداد عن بُعد في Firebase
فحص التطبيقات من Firebase
إضافات Firebase

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

المتطلبات الأساسية

  • تأكَّد من توفّر تطبيق خادم لديك.

  • تأكَّد من أن خادمك يشغّل ما يلي بناءً على حزمة SDK للمشرف التي تستخدمها:

    • Admin Node.js SDK - إصدار Node.js 14 أو إصدار أحدث (ننصحك باستخدام Node.js 16+ )
      تم إيقاف دعم Node.js 14.
    • Admin Java SDK: الإصدار 8 أو أحدث من Java
    • Admin Python SDK — Python 3.7+ (ننصحك باستخدام Python 3.8+ )
      تم إيقاف Python 3.7 بشكل نهائي.
    • حزمة SDK لـ Admin Go: الإصدار 1.20 أو إصدار أحدث
    • Admin .NET SDK — الإصدار 4.6.2 من نظام التشغيل.NET أو أحدث أو NET Standard 2 .0 لنظام.NET 6 .0 أو أحدث.

إعداد مشروع وحساب خدمة على Firebase

لاستخدام حزمة تطوير البرامج (SDK) لمشرف Firebase، ستحتاج إلى ما يلي:

  • مشروع على Firebase
  • حساب خدمة SDK لمشرف Firebase من أجل التواصل مع Firebase. يتم إنشاء حساب الخدمة هذا تلقائيًا عند إنشاء مشروع على Firebase أو إضافة Firebase إلى مشروع على Google Cloud.
  • ملف إعداد يتضمّن بيانات اعتماد حساب الخدمة

إذا لم يكن لديك مشروع في Firebase، يجب إنشاء مشروع في وحدة تحكُّم Firebase. يمكنك الانتقال إلى مقالة فهم مشاريع Firebase للاطّلاع على مزيد من المعلومات عن مشاريع Firebase.

إضافة حزمة تطوير البرامج (SDK)

عند إعداد مشروع جديد، يجب تثبيت حزمة SDK باللغة التي تختارها.

Node.js

تتوفّر حزمة SDK Node.js للمشرف في Firebase في npm. إذا لم يكن لديك ملف package.json، يمكنك إنشاء ملف من خلال npm init. بعد ذلك، ثبِّت حزمة firebase-admin npm واحفظها في package.json:

npm install firebase-admin --save

لاستخدام الوحدة في تطبيقك، require من أي ملف JavaScript:

const { initializeApp } = require('firebase-admin/app');

إذا كنت تستخدم ES2015، يمكنك import الوحدة:

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

Java

تم نشر حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase في مستودع Maven المركزي. لتثبيت المكتبة، يجب تعريفها بأنّها أداة مستقلة في ملف build.gradle:

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.3.0'
}

إذا كنت تستخدم Maven لإنشاء تطبيقك، يمكنك إضافة البيانات التابعة التالية إلى pom.xml:

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.3.0</version>
</dependency>

Python

تتوفّر حزمة Python SDK لمشرف Firebase من خلال pip. يمكنك تثبيت المكتبة لجميع المستخدمين من خلال sudo:

sudo pip install firebase-admin

يمكنك أيضًا تثبيت المكتبة للمستخدم الحالي فقط عن طريق تمرير علامة --user:

pip install --user firebase-admin

Go

يمكن تثبيت حزمة تطوير البرامج (SDK) للمشرف في Go باستخدام الأداة المساعدة go get:

# Install the latest version:
go get firebase.google.com/go/v4@latest

# Or install a specific version:
go get firebase.google.com/go/v4@4.14.0

C#‎

يمكن تثبيت حزمة .NET Admin SDK باستخدام مدير الحزمة .NET:

Install-Package FirebaseAdmin -Version 3.0.0

يمكنك بدلاً من ذلك تثبيته باستخدام أداة سطر الأوامر dotnet:

dotnet add package FirebaseAdmin --version 3.0.0

أو يمكنك تثبيته من خلال إضافة الإدخال المرجعي للحزمة التالي إلى ملف .csproj الخاص بك:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.0.0" />
</ItemGroup>

إعداد حزمة تطوير البرامج (SDK)

بعد إنشاء مشروع Firebase، يمكنك إعداد حزمة SDK باستخدام بيانات الاعتماد التلقائية لتطبيقات Google. نظرًا لأن البحث عن بيانات الاعتماد التلقائية يتم بشكل تلقائي بالكامل في بيئات Google، ودون الحاجة إلى توفير متغيرات البيئة أو غيرها من التكوينات، ننصح بشدة باستخدام طريقة إعداد SDK هذه مع التطبيقات التي تعمل في بيئات Google مثل Cloud Run وApp Engine وCloud Functions.

لتحديد خيارات الإعداد اختياريًا لخدمات مثل "قاعدة بيانات الوقت الفعلي" أو Cloud Storage أو Cloud Functions (وظائف Cloud)، استخدِم متغيّر البيئة FIREBASE_CONFIG. إذا كان محتوى المتغير FIREBASE_CONFIG يبدأ بـ {، فسيتم تحليله ككائن JSON. بخلاف ذلك، تفترض حزمة SDK أن السلسلة هي مسار ملف JSON الذي يحتوي على الخيارات.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#‎

FirebaseApp.Create();

بمجرد أن يتم إعدادها، يمكنك استخدام SDK للمشرف لإنجاز أنواع المهام التالية:

استخدام رمز مميز لإعادة تحميل OAuth 2.0

توفر حزمة SDK للمشرف أيضًا بيانات اعتماد تتيح لك المصادقة باستخدام رمز تحديث Google OAuth2:

Node.js

const myRefreshToken = '...'; // Get refresh token from OAuth2 flow

initializeApp({
  credential: refreshToken(myRefreshToken),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(refreshToken))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)

Go

opt := option.WithCredentialsFile("path/to/refreshToken.json")
config := &firebase.Config{ProjectID: "my-project-id"}
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#‎

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

إعداد حزمة تطوير البرامج (SDK) في بيئات غير تابعة لشركة Google

إذا كنت تعمل في بيئة خادم غير تابعة لشركة Google يتعذّر فيها إجراء البحث التلقائي عن بيانات الاعتماد بالكامل، يمكنك إعداد حزمة تطوير البرامج (SDK) باستخدام ملف مفتاح حساب خدمة تم تصديره.

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

لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase، يجب إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة الخاص بك، عليك اتّباع الخطوات التالية:

  1. في وحدة تحكُّم Firebase، افتح الإعدادات > حسابات الخدمة.

  2. انقر على إنشاء مفتاح خاص جديد، ثم أكِّد بالنقر على إنشاء مفتاح.

  3. ويمكنك تخزين ملف JSON الذي يحتوي على المفتاح بأمان.

عند منح التفويض من خلال حساب خدمة، يتوفّر لك خياران لتقديم بيانات الاعتماد إلى تطبيقك. يمكنك ضبط متغيّر بيئة GOOGLE_APPLICATION_CREDENTIALS أو يمكنك تمرير المسار بوضوح إلى مفتاح حساب الخدمة في الرمز. الخيار الأول أكثر أمانًا ويُنصح به بشدة.

لضبط متغيّر البيئة:

اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة. لا ينطبق هذا المتغير إلا على جلسة الغلاف الحالية، لذا إذا فتحت جلسة جديدة، فقم بتعيين المتغير مرة أخرى.

نظام التشغيل Linux أو macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

شبابيك

باستخدام PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

بعد إكمال الخطوات الواردة أعلاه، ستتمكن "بيانات اعتماد التطبيق التلقائية" (ADC) من تحديد بيانات الاعتماد ضمنيًا، ما يسمح لك باستخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لشركة Google.

يُرجى إعداد حزمة SDK على النحو الموضّح:

Node.js

initializeApp({
    credential: applicationDefault(),
    databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#‎

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "my-project-id",
});

تهيئة تطبيقات متعددة

في معظم الحالات، لن تحتاج سوى إلى إعداد تطبيق تلقائي واحد. يمكنك الوصول إلى الخدمات من هذا التطبيق بطريقتين مكافئتين:

Node.js

// Initialize the default app
const defaultApp = initializeApp(defaultAppConfig);

console.log(defaultApp.name);  // '[DEFAULT]'

// Retrieve services via the defaultApp variable...
let defaultAuth = getAuth(defaultApp);
let defaultDatabase = getDatabase(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = getAuth();
defaultDatabase = getDatabase();

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

System.out.println(defaultApp.getName());  // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
FirebaseAuth defaultAuth = FirebaseAuth.getInstance(defaultApp);
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.getInstance();
defaultDatabase = FirebaseDatabase.getInstance();

Python

# Import the Firebase service
from firebase_admin import auth

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
print(default_app.name)  # "[DEFAULT]"

# Retrieve services via the auth package...
# auth.create_custom_token(...)

Go

// Initialize default app
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access auth service from the default app
client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#‎

// Initialize the default app
var defaultApp = FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
var defaultAuth = FirebaseAuth.GetAuth(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.DefaultInstance;

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

Node.js

// Initialize the default app
initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = initializeApp(otherAppConfig, 'other');

console.log(getApp().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
const defaultAuth = getAuth();
const defaultDatabase = getDatabase();

// Use the otherApp variable to retrieve the other app's services
const otherAuth = getAuth(otherApp);
const otherDatabase = getDatabase(otherApp);

Java

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

// Initialize another app with a different config
FirebaseApp otherApp = FirebaseApp.initializeApp(otherAppConfig, "other");

System.out.println(defaultApp.getName());  // "[DEFAULT]"
System.out.println(otherApp.getName());    // "other"

// Use the shorthand notation to retrieve the default app's services
FirebaseAuth defaultAuth = FirebaseAuth.getInstance();
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance();

// Use the otherApp variable to retrieve the other app's services
FirebaseAuth otherAuth = FirebaseAuth.getInstance(otherApp);
FirebaseDatabase otherDatabase = FirebaseDatabase.getInstance(otherApp);

Python

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)

#  Initialize another app with a different config
other_app = firebase_admin.initialize_app(cred, name='other')

print(default_app.name)    # "[DEFAULT]"
print(other_app.name)      # "other"

# Retrieve default services via the auth package...
# auth.create_custom_token(...)

# Use the `app` argument to retrieve the other app's services
# auth.create_custom_token(..., app=other_app)

Go

// Initialize the default app
defaultApp, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Initialize another app with a different config
opt := option.WithCredentialsFile("service-account-other.json")
otherApp, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access Auth service from default app
defaultClient, err := defaultApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

// Access auth service from other app
otherClient, err := otherApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

C#‎

// Initialize the default app
var defaultApp = FirebaseApp.Create(defaultOptions);

// Initialize another app with a different config
var otherApp = FirebaseApp.Create(otherAppConfig, "other");

Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
Console.WriteLine(otherApp.Name); // "other"

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = FirebaseAuth.DefaultInstance;

// Use the otherApp variable to retrieve the other app's services
var otherAuth = FirebaseAuth.GetAuth(otherApp);

تعيين نطاقات قاعدة البيانات والمصادقة في الوقت الفعلي

إذا كنت تستخدم جهاز افتراضي (VM) Google Compute Engine مع "بيانات الاعتماد التلقائية" لتطبيق Google لقاعدة البيانات أو المصادقة في الوقت الفعلي، احرص أيضًا على ضبط نطاقات الوصول الصحيحة. بالنسبة إلى قاعدة البيانات والمصادقة في الوقت الفعلي، تحتاج إلى نطاقات تنتهي بـ userinfo.email وإما cloud-platform أو firebase.database. للتحقق من نطاقات الوصول الحالية وتغييرها، شغِّل الأوامر التالية باستخدام gcloud.

gcloud

# Check the existing access scopes
gcloud compute instances describe [INSTANCE_NAME] --format json

# The above command returns the service account information. For example:
  "serviceAccounts": [
   {
    "email": "your.gserviceaccount.com",
    "scopes": [
     "https://www.googleapis.com/auth/cloud-platform",
     "https://www.googleapis.com/auth/userinfo.email"
     ]
    }
  ],

# Stop the VM, then run the following command, using the service account
# that gcloud returned when you checked the scopes.

gcloud compute instances set-service-account [INSTANCE_NAME] --service-account "your.gserviceaccount.com" --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"

الاختبار باستخدام بيانات اعتماد المستخدم النهائي في gcloud

عند اختبار SDK للمشرف محليًا باستخدام بيانات الاعتماد التلقائية لتطبيقات Google التي تم الحصول عليها من خلال تشغيل gcloud auth application-default login، يجب إجراء تغييرات إضافية لاستخدام مصادقة Firebase للأسباب التالية:

  • لا تقبل مصادقة Firebase بيانات اعتماد مستخدم gcloud النهائي التي تم إنشاؤها باستخدام معرّف عميل gcloud OAuth.
  • تتطلب مصادقة Firebase تقديم رقم تعريف المشروع عند التهيئة لهذا النوع من بيانات اعتماد المستخدم.

كحل بديل، يمكنك إنشاء بيانات اعتماد تلقائية لتطبيق Google في gcloud باستخدام معرِّف عميل OAuth 2.0 الخاص بك. يجب أن يكون معرّف عميل OAuth من نوع تطبيق تطبيق سطح المكتب.

gcloud

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

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

لتحديد رقم تعريف المشروع بشكل صريح:

Node.js

import { initializeApp, applicationDefault } from 'firebase-admin/app';

initializeApp({
  credential: applicationDefault(),
  projectId: '<FIREBASE_PROJECT_ID>',
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setProjectId("<FIREBASE_PROJECT_ID>")
    .build();

FirebaseApp.initializeApp(options);

Python

app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)

Go

config := &firebase.Config{ProjectID: "<FIREBASE_PROJECT_ID>"}
app, err := firebase.NewApp(context.Background(), config)
if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
}

C#‎

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "<FIREBASE_PROJECT_ID>",
});

الخطوات اللاحقة

معلومات عن Firebase:

إضافة ميزات Firebase إلى تطبيقك: