إضافة حزمة تطوير البرامج (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 الذي تستخدمه:

    • حزمة تطوير البرامج (SDK) لنظام التشغيل Node.js للمشرف - الإصدار 18 من Node.js والإصدارات الأحدث
    • ‫Admin Java SDK: الإصدار 8 من Java والإصدارات الأحدث
    • حزمة تطوير البرامج (SDK) لإدارة Python: الإصدار 3.7 من Python والإصدارات الأحدث (ننصح باستخدام الإصدار 3.8 والإصدارات الأحدث)
      تم إيقاف الإصدار 3.7 من Python نهائيًا.
    • حزمة تطوير البرامج (SDK) لمشرف Go‏: الإصدار 1.21 من Go والإصدارات الأحدث
    • حزمة تطوير البرامج (SDK) لإدارة ‎ .NET: الإصدار 4.6.2 أو إصدار أحدث من ‎.NET Framework أو الإصدار 2 .0 من ‎.NET Standard لإصدار 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) لنظام Java في Firebase Admin في مستودع 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) لنظام التشغيل Python في Firebase Admin من خلال 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.16.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

إذا كنت تستخدم جهازًا افتراضيًا (VM) من 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