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

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

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

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

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

الميزة Node.js Java Python Go #C
إنشاء رموز مميّزة مخصّصة
إثبات صحة الرمز المميز لتعريف الهوية
إدارة المستخدمين
التحكّم في الوصول باستخدام المطالبات المخصّصة
إبطال الرمز المميز لإعادة التحميل
استيراد المستخدمين
إدارة ملفات تعريف الارتباط الخاصة بالجلسة
إنشاء روابط تؤدي إلى إجراءات في البريد الإلكتروني
إدارة إعدادات موفّر SAML/OIDC
إتاحة الاستخدام المتعدد
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM البث المتعدد
إدارة الاشتراكات في مواضيع FCM
Cloud Storage
Cloud Firestore
إضافة وظائف إلى قائمة الانتظار باستخدام Cloud Tasks
إدارة المشاريع
قواعد الأمان
إدارة نماذج تعلُّم الآلة
Firebase Remote Config
Firebase App Check
Firebase Extensions

لمزيد من المعلومات حول دمج Admin SDK في هذه الاستخدامات، يمكنك الاطّلاع على مستندات Realtime Database وFCM وAuthentication وRemote Config وCloud Storage ذات الصلة. تركز بقية هذه الصفحة على الإعداد الأساسي لـ Admin SDK.

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

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

  • تأكَّد من أنّ الخادم يشغّل ما يلي استنادًا إلى Admin SDK الذي تستخدمه:

    • ‫Admin Node.js SDK — Node.js 18+
    • ‫Admin Java SDK — الإصدار 8 من Java أو الإصدارات الأحدث
    • حزمة تطوير البرامج (SDK) الخاصة بالمشرف في Python‏: الإصدار 3.9 من Python أو الإصدارات الأحدث (ننصح باستخدام الإصدار 3.10 من Python أو الإصدارات الأحدث)
      تم إيقاف الإصدار 3.9 من Python نهائيًا.
    • حزمة تطوير البرامج (SDK) للمشرف في Go‏ (Go 1.23 والإصدارات الأحدث)
    • حزمة تطوير البرامج (SDK) للمشرف في ‎ .NET‏ — ‎.NET Framework 4.6.2‎ أو ‎ .NET Standard 2.0‎ للإصدار ‎6 .0 أو إصدار أحدث من ‎.NET

إعداد مشروع وحساب خدمة في Firebase

لاستخدام Firebase Admin SDK، ستحتاج إلى ما يلي:

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

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

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

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

Node.js

تتوفّر حزمة تطوير البرامج (SDK) لمدير Firebase Node.js على npm. إذا لم يكن لديك ملف package.json، أنشئ واحدًا من خلال npm init. بعد ذلك، ثبِّت حزمة npm الخاصة بـ firebase-admin واحفظها في 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 Admin Java في مستودع Maven المركزي. لتثبيت المكتبة، يجب تعريفها كمورد تابع في ملف build.gradle:

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

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

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

Python

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

sudo pip install firebase-admin

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

pip install --user firebase-admin

Go

يمكن تثبيت Go Admin SDK باستخدام الأداة 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.17.0

#C

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

Install-Package FirebaseAdmin -Version 3.3.0

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

dotnet add package FirebaseAdmin --version 3.3.0

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

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

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

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

لتحديد خيارات الإعداد لخدمات مثل Realtime Database أو Cloud Storage أو Cloud Functions بشكل اختياري، استخدِم متغيّر البيئة 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)
}
init.go

#C

FirebaseApp.Create();

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

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

يوفر Admin 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)
}
init.go

#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 الذي يحتوي على مفتاح حساب الخدمة. لا ينطبق هذا المتغيّر إلا على جلسة shell الحالية، لذا إذا فتحت جلسة جديدة، عليك ضبط المتغيّر مرة أخرى.

‫Linux أو macOS

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

Windows

باستخدام 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)
}
init.go

#C

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

FirebaseAppSnippets.cs

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

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

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)
}
init.go

#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;

تتطلّب بعض حالات الاستخدام إنشاء تطبيقات متعددة في الوقت نفسه. على سبيل المثال، قد تحتاج إلى قراءة البيانات من Realtime Database لمشروع واحد على 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)
}
init.go

#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);

ضبط النطاقات لـ Realtime Database وAuthentication

إذا كنت تستخدم جهازًا افتراضيًا على Google Compute Engine مع بيانات اعتماد Google التلقائية للتطبيق من أجل Realtime Database أو Authentication، احرص على ضبط نطاقات الوصول الصحيحة أيضًا. بالنسبة إلى Realtime Database وAuthentication، يجب أن تنتهي النطاقات بـ 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

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

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

كحلّ بديل، يمكنك إنشاء بيانات اعتماد تلقائية للتطبيق من 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 إلى تطبيقك:

  • كتابة برنامج خلفي بدون خادم باستخدام Cloud Functions
  • تخزين المعلومات باستخدام Realtime Database أو بيانات الكائنات الثنائية الكبيرة باستخدام Cloud Storage
  • تلقّي الإشعارات باستخدام Cloud Messaging