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 כלקוח לגישה של משתמשי קצה (לדוגמה, באפליקציית IoT או באפליקציה למחשב של Node.js), במקום גישת אדמין מסביבה עם הרשאות (כמו שרת), אתם צריכים לפעול לפי ההוראות להגדרת ה-JavaScript SDK ללקוח.
בטבלה הבאה מפורטות התכונות של Firebase שנתמכות בכל שפה:
מידע נוסף על שילוב Admin SDK לשימושים האלה זמין במסמכי התיעוד המתאימים של Realtime Database, FCM, Authentication, Remote Config ו-Cloud Storage. שאר הדף הזה מתמקד בהגדרה הבסיסית של Admin SDK.
דרישות מוקדמות
מוודאים שיש לכם אפליקציית שרת.
חשוב לוודא שהשרת מריץ את הפקודה הבאה, בהתאם ל-Admin SDK שבו משתמשים:
- Admin Node.js SDK — Node.js 22+
- Admin Java SDK — Java 8+
- Admin Python SDK — Python 3.10 ואילך (מומלץ Python 3.11 ואילך)
התמיכה ב-Python 3.10 הוצאה משימוש. - Admin Go SDK — Go 1.26+
- Admin .NET SDK — .NET Framework 4.6.2+ או .NET Standard 2.0 או .NET 6.0+ (מומלץ .NET 8.0+)
התמיכה ב-.NET 6.0 ו-7.0 הוצאה משימוש. - Admin Dart SDK ניסיוני – ודאו שהשרת שלכם מריץ את Dart SDK בגרסה 3.9 ואילך.
- Admin Node.js SDK — Node.js 22+
הגדרת פרויקט ב-Firebase וחשבון שירות
כדי להשתמש ב-Firebase Admin SDK, צריך:
- יש לכם פרויקט Firebase.
- חשבון שירות של Firebase Admin SDK כדי לתקשר עם Firebase. חשבון השירות הזה נוצר באופן אוטומטי כשיוצרים פרויקט ב-Firebase או כשמוסיפים את Firebase לפרויקט בענן של Google.
- קובץ תצורה עם פרטי הכניסה של חשבון השירות.
אם עדיין אין לכם פרויקט ב-Firebase, אתם צריכים ליצור פרויקט במסוף Firebase. במאמר הסבר על פרויקטים ב-Firebase תוכלו לקרוא מידע נוסף על פרויקטים ב-Firebase.
הוספת ה-SDK
אם אתם מגדירים פרויקט חדש, אתם צריכים להתקין את ה-SDK בשפה שבחרתם.
Node.js
Firebase Admin Node.js SDK זמין ב-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
Firebase Admin Java SDK מתפרסם במאגר המרכזי של 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
אפשר להוריד את Firebase Admin Python SDK באמצעות 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 באמצעות Application Default Credentials. בסביבות של 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)
}
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)
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 = CredentialFactory.FromFile<UserCredential>("path/to/refreshToken.json").ToGoogleCredential(),
});
אתחול ה-SDK בסביבות שהן לא של Google
אם אתם עובדים בסביבת שרת שאינה של Google, שבה אי אפשר להפוך את החיפוש של פרטי הכניסה שמוגדרים כברירת מחדל לאוטומטי באופן מלא, אתם יכולים להפעיל את ה-SDK באמצעות קובץ מפתח של חשבון שירות שיוצא.
פרויקטים ב-Firebase תומכים בחשבונות שירות של Google, שבהם אפשר להשתמש כדי לקרוא לממשקי API של שרת Firebase משרת האפליקציה או מסביבה מהימנה. אם אתם מפתחים קוד באופן מקומי או פורסים את האפליקציה באופן מקומי, אתם יכולים להשתמש בפרטי הכניסה שקיבלתם באמצעות חשבון השירות הזה כדי לאשר בקשות לשרת.
אתם יכולים לראות את כל חשבונות השירות של הפרויקט ב-Firebase בכרטיסייה
כדי לאמת חשבון שירות ולתת לו הרשאת גישה לשירותי Firebase, צריך ליצור קובץ מפתח פרטי בפורמט JSON.
כדי ליצור קובץ מפתח פרטי לחשבון השירות:
במסוף Firebase, נכנסים לכרטיסייה
Settings > Service accounts.לוחצים על Generate New Private Key ואז על Generate Key כדי לאשר.
שומרים באופן מאובטח את קובץ ה-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"
אחרי שתבצעו את הפעולות שלמעלה, Application Default Credentials (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;
יש תרחישים לדוגמה שבהם צריך ליצור כמה אפליקציות בו-זמנית. לדוגמה, יכול להיות שתרצו לקרוא נתונים מ-Realtime Database של פרויקט Firebase אחד ולהנפיק אסימונים בהתאמה אישית לפרויקט אחר. או שאתם רוצים לאמת שתי אפליקציות עם פרטי כניסה נפרדים. בעזרת Firebase SDK אפשר ליצור כמה אפליקציות בו-זמנית, שלכל אחת מהן יש פרטי הגדרה משלה.
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);
הגדרת היקפים ל-Realtime Database ול-Authentication
אם אתם משתמשים במכונה וירטואלית של Google Compute Engine עם Application Default Credentials בשביל 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 באופן מקומי עם Application Default Credentials של Google, שמתקבלים על ידי הפעלת gcloud auth application-default login, צריך לבצע שינויים נוספים כדי להשתמש ב-Firebase Authentication מהסיבות הבאות:
- ב-Firebase Authentication אי אפשר להשתמש בפרטי כניסה של משתמשי קצה ב-gcloud שנוצרו באמצעות מזהה הלקוח של OAuth ב-gcloud.
- ב-Firebase Authentication צריך לספק את מזהה הפרויקט במהלך האתחול של פרטי הכניסה האלה של משתמשי הקצה.
כדי לעקוף את הבעיה, אתם יכולים ליצור פרטי כניסה ב-Application Default Credentials של 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)
Go
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:
עיינו בקוד המקור הפתוח ב-GitHub ל-Node.js, ל-Java ול-Python.
פוסטים בבלוג שקשורים ל-Admin SDK, שנכתבו על ידי אחד מהיוצרים של Admin SDK. לדוגמה: גישה ל-Firestore ול-Firebase דרך שרת proxy.
הוספת תכונות של Firebase לאפליקציה:
- כותבים קצה עורפי ללא שרת (serverless) באמצעות Cloud Functions.
- אחסון מידע באמצעות Realtime Database או נתוני blob באמצעות Cloud Storage.
- קבלת התראות באמצעות Cloud Messaging.