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

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

  • قراءة وكتابة بيانات قاعدة البيانات في الوقت الفعلي باستخدام امتيازات المشرف الكاملة
  • يمكنك إرسال رسائل "المراسلة عبر السحابة الإلكترونية من Firebase" آليًا باستخدام طريقة بسيطة وبديلة لبروتوكولات خادم "المراسلة عبر السحابة الإلكترونية من Firebase".
  • إنشاء رموز مصادقة 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
البث المتعدد عبر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
إدارة الاشتراكات في مواضيع "المراسلة عبر السحابة الإلكترونية من Firebase"
التخزين في السحابة الإلكترونية
Cloud Firestore
إضافة الدوال إلى قائمة الانتظار باستخدام "مهام Cloud"
إدارة المشروعات
قواعد الأمان
إدارة نماذج تعلُّم الآلة
الإعداد عن بُعد في Firebase
فحص التطبيقات من Firebase
إضافات Firebase

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

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

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

  • تأكَّد من أنّ خادمك يشغِّل ما يلي استنادًا إلى حزمة تطوير البرامج (SDK) الخاصة بالمشرف التي تستخدمها:

    • Node.js SDK للمشرف: Node.js 14+ (ننصح باستخدام Node.js 18+)
      تم إيقاف دعم Node.js 14 و16.
    • حزمة تطوير البرامج (SDK) للمشرفين في Java — إصدار Java 8 والإصدارات الأحدث
    • Admin Python SDK — Python 3.7+ (ننصح باستخدام Python 3.8+ )
      تم إيقاف دعم Python 3.7.
    • حزمة تطوير البرامج (SDK) للمشرفين Go: الإصدار 1.20 أو الإصدارات الأحدث
    • Admin .NET SDK — .NETframe 4.6.2+ أو .NET Standard 2.0 for .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. بعد ذلك، ثبِّت حزمة 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 في مستودع 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

تتوفّر حزمة 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.1

C#‎

يمكن تثبيت SDK لمشرف .NET باستخدام مدير حزمة .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، استخدِم متغيّر البيئة 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();

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

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

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

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

إذا كنت تستخدم جهاز 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 إلى تطبيقك: