Admin SDK عبارة عن مجموعة من مكتبات الخوادم التي تتيح لك التفاعل مع Firebase من بيئات مميزة لتنفيذ إجراءات مثل:
- يمكنك إجراء طلبات بحث وتعديلات على خدمة Firebase SQL Connect لإدارة البيانات المجمّعة والعمليات الأخرى باستخدام امتيازات المشرف الكاملة.
- قراءة بيانات "Realtime Database" وكتابتها باستخدام امتيازات المشرف الكاملة
- إرسال رسائل Firebase Cloud Messaging آليًا باستخدام نهج بديل لبروتوكولات خادم Firebase Cloud Messaging
- إنشاء رموز مصادقة Firebase والتحقّق منها
- الوصول إلى موارد Google Cloud، مثل حِزم Cloud Storage وقواعد بيانات Cloud Firestore المرتبطة بمشاريع Firebase.
- يمكنك إنشاء وحدة تحكّم إدارية خاصة بك لتنفيذ إجراءات مثل البحث عن بيانات المستخدمين أو تغيير عنوان البريد الإلكتروني لمستخدم من أجل المصادقة.
إذا أردت استخدام حزمة تطوير البرامج (SDK) لـ Node.js كبرنامج لوصول المستخدم النهائي (على سبيل المثال، في تطبيق Node.js لسطح المكتب أو تطبيق إنترنت الأشياء)، بدلاً من إذن الوصول الإداري من بيئة مميزة (مثل الخادم)، عليك بدلاً من ذلك اتّباع تعليمات إعداد JavaScript SDK.
في ما يلي مصفوفة ميزات تعرض ميزات Firebase المتوافقة مع كل لغة:
لمزيد من المعلومات حول دمج Admin SDK لهذه الاستخدامات، يُرجى الاطّلاع على المستندات ذات الصلة: Realtime Database وFCM وAuthentication وRemote Config وCloud Storage. يركّز الجزء المتبقي من هذه الصفحة على الإعداد الأساسي لـ Admin SDK.
المتطلبات الأساسية
تأكَّد من أنّ لديك تطبيق خادم.
تأكَّد من أنّ الخادم يشغّل ما يلي استنادًا إلى Admin SDK الذي تستخدمه:
- Admin Node.js SDK — الإصدار 22 من Node.js أو الإصدارات الأحدث
- Admin Java SDK — الإصدار 8 من Java أو الإصدارات الأحدث
- حزمة تطوير البرامج (SDK) لمشرف Python: الإصدار 3.10 من Python أو إصدار أحدث (يُنصح باستخدام الإصدار 3.11 من Python أو إصدار أحدث)
تم إيقاف الإصدار 3.10 من Python نهائيًا. - Admin Go SDK — الإصدار 1.26 من Go أو الإصدارات الأحدث
- حزمة تطوير البرامج (SDK) الخاصة بالمشرف لـ .NET: الإصدار .NET Framework 4.6.2 أو إصدار أحدث، أو الإصدار .NET Standard 2.0، أو الإصدار .NET 6.0 أو إصدار أحدث (يُنصح باستخدام الإصدار .NET 8.0 أو إصدار أحدث)
تم إيقاف الإصدارَين .NET 6.0 و7.0 نهائيًا. - حزمة SDK التجريبية لمشرف Dart: تأكَّد من أنّ الخادم يشغّل الإصدار 3.9 من حزمة SDK لمشرف Dart أو إصدارًا أحدث.
- Admin Node.js SDK — الإصدار 22 من Node.js أو الإصدارات الأحدث
إعداد مشروع Firebase وحساب خدمة
لاستخدام Firebase Admin SDK، ستحتاج إلى ما يلي:
- مشروع Firebase
- حساب خدمة SDK في Firebase Admin للتواصل مع 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 في Java في مستودع Maven المركزي.
لتثبيت المكتبة، يجب تحديدها كاعتمادية في ملف build.gradle:
dependencies {
implementation 'com.google.firebase:firebase-admin:9.12.0'
}
إذا كنت تستخدم Maven لإنشاء تطبيقك، يمكنك إضافة التبعية التالية إلى pom.xml:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.12.0</version>
</dependency>
Python
تتوفّر حزمة تطوير البرامج (SDK) لمشرف Firebase بلغة Python من خلال
pip.
يمكنك تثبيت المكتبة لجميع المستخدمين من خلال sudo:
sudo pip install firebase-admin
أو يمكنك تثبيت المكتبة للمستخدم الحالي فقط من خلال تمرير العلامة --user:
pip install --user firebase-admin
متابعة
يمكنك تثبيت حزمة Go Admin SDK باستخدام الأداة المساعدة go get. لتثبيت
أحدث إصدار:
go get firebase.google.com/go/v4@latest
لتثبيت إصدار معيّن، اتّبِع الخطوات التالية:
go get firebase.google.com/go/v4@v4.23.0
#C
يمكن تثبيت حزمة Admin SDK في .NET باستخدام أداة إدارة حِزم .NET:
Install-Package FirebaseAdmin -Version 3.7.1
بدلاً من ذلك، يمكنك تثبيته باستخدام أداة سطر الأوامر dotnet:
dotnet add package FirebaseAdmin --version 3.7.1
أو يمكنك تثبيتها من خلال إضافة إدخال مرجع الحزمة التالي إلى ملف .csproj:
<ItemGroup>
<PackageReference Include="FirebaseAdmin"
Version="3.7.1" />
</ItemGroup>
Dart (تجريبية)
dart pub add firebase_admin_sdk
لاستخدام الوحدة في تطبيقك، استورِدها كما هو موضّح:
import 'package:firebase_admin_sdk';
// Also import the separate Firestore package if you're interacting with
// Firestore.
import 'package:google_cloud_firestore/google_cloud_firestore.dart';
إعداد حزمة تطوير البرامج (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()
متابعة
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
#C
FirebaseApp.Create();
Dart (تجريبية)
final admin = FirebaseApp.initializeApp();
بعد إعداد Admin SDK، يمكنك استخدامه لإنجاز المهام التالية:
- تنفيذ المصادقة المخصّصة
- إدارة مستخدمي Firebase Authentication
- إجراء طلبات بحث وتغييرات إدارية على خدمة "Firebase SQL Connect"
- قراءة البيانات وكتابتها من Realtime Database
- إرسال رسائل Firebase Cloud Messaging
استخدام رمز مميّز لإعادة التحميل في 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)
متابعة
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 = CredentialFactory.FromFile<UserCredential>("path/to/refreshToken.json").ToGoogleCredential(),
});
إعداد حزمة تطوير البرامج (SDK) في بيئات غير تابعة لـ Google
إذا كنت تعمل في بيئة خادم غير تابعة لـ Google ولا يمكن فيها إجراء عملية البحث عن بيانات الاعتماد التلقائية بشكل آلي بالكامل، يمكنك إعداد حزمة تطوير البرامج (SDK) باستخدام ملف مفتاح حساب خدمة تم تصديره.
تتيح مشاريع Firebase استخدام حسابات خدمة Google، والتي يمكنك استخدامها لطلب واجهات برمجة تطبيقات خادم Firebase من خادم التطبيق أو البيئة الموثوق بها. إذا كنت تطوّر رمزًا برمجيًا محليًا أو تنشر تطبيقك في المؤسسة، يمكنك استخدام بيانات الاعتماد التي تم الحصول عليها باستخدام حساب الخدمة هذا لمنح الإذن لطلبات الخادم.
يمكنك الاطّلاع على جميع حسابات الخدمة لمشروعك على Firebase في علامة التبويب
لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase، يجب إنشاء ملف مفتاح خاص بتنسيق JSON.
لإنشاء ملف مفتاح خاص لحساب الخدمة:
في وحدة تحكّم Firebase، انتقِل إلى
الإعدادات > علامة التبويب حسابات الخدمة.انقر على إنشاء مفتاح خاص جديد، ثم أكِّد ذلك بالنقر على إنشاء مفتاح.
خزِّن ملف JSON الذي يحتوي على المفتاح بشكل آمن.
عند التفويض عبر حساب خدمة، يتوفّر لك خياران لتقديم بيانات الاعتماد إلى تطبيقك. يمكنك ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS أو يمكنك تمرير المسار بشكل صريح إلى مفتاح حساب الخدمة في الرمز البرمجي.
الخيار الأول أكثر أمانًا وننصح به بشدة.
لضبط متغيّر البيئة:
اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS
على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة.
ينطبق هذا المتغيّر فقط على جلسة واجهة الأوامر الحالية، لذا إذا فتحت
جلسة جديدة، اضبط المتغيّر مرة أخرى.
Linux أو macOS
export GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"
Windows
باستخدام PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"
بعد إكمال الخطوات المذكورة أعلاه، يمكن لبيانات الاعتماد التلقائية للتطبيق (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()
متابعة
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(...)
متابعة
// 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;
تتطلّب بعض حالات الاستخدام إنشاء تطبيقات متعددة في الوقت نفسه. على سبيل المثال، قد تريد قراءة البيانات من 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)
متابعة
// 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);
ضبط النطاقات لـ Realtime Database وAuthentication
إذا كنت تستخدم جهازًا افتراضيًا في Google Compute Engine مع
بيانات الاعتماد التلقائية لتطبيق Google
لـ Realtime Database أو Authentication، تأكَّد أيضًا من ضبط
نطاقات الوصول الصحيحة.
بالنسبة إلى Realtime Database وAuthentication، تحتاج إلى نطاقات تنتهي بـ userinfo.email و
إما cloud-platform أو firebase.database. للتحقّق من نطاقات الوصول الحالية وتغييرها، أكمِل الخطوات التالية باستخدام gcloud:
تحقَّق من حساب الخدمة الحالي للجهاز الافتراضي ونطاقات الوصول:
gcloud compute instances describe \ INSTANCE_NAME \ --format=jsonابحث عن قسم
serviceAccountsفي الناتج وسجِّل عنوان البريد الإلكتروني لحساب الخدمة. على سبيل المثال:{ "serviceAccounts": [ { "email": "SERVICE_ACCOUNT_EMAIL", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/userinfo.email" ] } ] }أوقِف الجهاز الافتراضي، ثم عدِّل نطاقات الوصول إليه باستخدام عنوان البريد الإلكتروني لحساب الخدمة من الخطوة السابقة:
gcloud compute instances set-service-account \ INSTANCE_NAME \ --service-account "SERVICE_ACCOUNT_EMAIL" \ --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 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: 'PROJECT_ID',
});
Java
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setProjectId("PROJECT_ID")
.build();
FirebaseApp.initializeApp(options);
Python
app_options = {'projectId': 'PROJECT_ID'}
default_app = firebase_admin.initialize_app(options=app_options)
متابعة
config := &firebase.Config{ProjectID: "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 = "PROJECT_ID",
});
الخطوات التالية
مزيد من المعلومات عن Firebase:
اطّلِع على نماذج تطبيقات Firebase.
يمكنك استكشاف الرمز المفتوح المصدر في GitHub للغات Node.js وJava وPython.
يمكنك قراءة منشورات المدوّنة ذات الصلة بـ Admin SDK من أحد منشئي Admin SDK. على سبيل المثال: الوصول إلى Firestore وFirebase من خلال خادم وكيل
أضِف ميزات Firebase إلى تطبيقك:
- كتابة خلفية بدون خادم باستخدام Cloud Functions
- يمكنك تخزين المعلومات باستخدام Realtime Database أو بيانات blob باستخدام Cloud Storage.
- تلقّي الإشعارات من خلال Cloud Messaging