Admin SDK היא קבוצה של ספריות שרת שמאפשרות לכם ליצור אינטראקציה עם Firebase מסביבות עם הרשאות מיוחדות כדי לבצע פעולות כמו:
- ביצוע שאילתות ושינויים בשירות Firebase Data Connect לניהול נתונים בכמות גדולה ולפעולות אחרות עם הרשאות אדמין מלאות.
- קריאה וכתיבה של נתוני Realtime Database עם הרשאות אדמין מלאות.
- שליחת הודעות Firebase Cloud Messaging באופן פרוגרמטי באמצעות גישה פשוטה וחלופית לפרוטוקולי השרתים Firebase Cloud Messaging.
- יצירה ואימות של אסימוני אימות ב-Firebase.
- גישה למשאבי Google Cloud כמו קטגוריות Cloud Storage ומסדי נתונים Cloud Firestore שמשויכים לפרויקטים שלכם ב-Firebase.
- אתם יכולים ליצור מסוף Admin פשוט משלכם כדי לבצע פעולות כמו חיפוש נתוני משתמש או שינוי כתובת האימייל של משתמש לצורך אימות.
אם אתם רוצים להשתמש ב-SDK של Node.js כלקוח לגישת משתמשי קצה (לדוגמה, באפליקציית Node.js למחשב או ל-IoT), ולא כגישת אדמין מסביבה עם הרשאות (כמו שרת), אתם צריכים לפעול לפי ההוראות להגדרת ה-SDK של JavaScript ללקוח.
בטבלה הבאה מפורטות התכונות של Firebase שנתמכות בכל שפה:
מידע נוסף על שילוב של Admin SDK לשימושים האלה זמין במסמכי התיעוד המתאימים של Realtime Database, FCM, Authentication, Remote Config ו-Cloud Storage. שאר הדף הזה מתמקד בהגדרה בסיסית של Admin SDK.
דרישות מוקדמות
מוודאים שיש לכם אפליקציית שרת.
חשוב לוודא שהשרת מריץ את הפקודות הבאות בהתאם לAdmin SDK שבו אתם משתמשים:
- Admin Node.js SDK — Node.js 18+
- Admin Java SDK — Java 8+
- Admin Python SDK – Python 3.9 ואילך (מומלץ להשתמש ב-Python 3.10 ואילך)
התמיכה ב-Python 3.9 הוצאה משימוש. - Admin Go SDK — Go 1.23+
- Admin .NET SDK – .NET Framework 4.6.2 ואילך או .NET Standard 2.0 ל- .NET 6.0 ואילך
הגדרה של פרויקט Firebase וחשבון שירות
כדי להשתמש ב-Firebase Admin SDK, צריך:
- פרויקט Firebase.
- חשבון שירות של Firebase Admin SDK לתקשורת עם Firebase. חשבון השירות הזה נוצר באופן אוטומטי כשיוצרים פרויקט Firebase או כשמוסיפים את Firebase לפרויקט Google Cloud.
- קובץ הגדרות עם פרטי הכניסה של חשבון השירות.
אם עדיין אין לכם פרויקט 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.5.0'
}
אם אתם משתמשים ב-Maven כדי ליצור את האפליקציה, אתם יכולים להוסיף את יחסי התלות הבאים לקובץ pom.xml
:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.5.0</version>
</dependency>
Python
Firebase Admin Python SDK זמין דרך 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#
אפשר להתקין את .NET Admin SDK באמצעות מנהל החבילות של .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)
}
C#
FirebaseApp.Create();
אחרי שמאתחלים אותו, אפשר להשתמש ב-Admin SDK כדי לבצע את סוגי המשימות הבאים:
- הטמעה של אימות בהתאמה אישית
- ניהול המשתמשים ב-Firebase Authentication
- ביצוע שאילתות אדמיניסטרטיביות ושינויים בFirebase Data 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 = GoogleCredential.FromFile("path/to/refreshToken.json"),
});
אתחול ה-SDK בסביבות שאינן של Google
אם אתם עובדים בסביבת שרת שאינה של Google, שבה אי אפשר לבצע חיפוש של פרטי כניסה שמוגדרים כברירת מחדל באופן אוטומטי לחלוטין, אתם יכולים לאתחל את ה-SDK באמצעות קובץ מפתח של חשבון שירות שיוצא.
פרויקטים ב-Firebase תומכים בחשבונות שירות של Google, שאפשר להשתמש בהם כדי לקרוא ל-Firebase Server APIs משרת האפליקציות או מסביבה מהימנה. אם אתם מפתחים קוד באופן מקומי או פורסים את האפליקציה שלכם בשרת מקומי, אתם יכולים להשתמש בפרטי הכניסה שהתקבלו דרך חשבון השירות הזה כדי לאשר בקשות לשרת.
כדי לאמת חשבון שירות ולאשר לו גישה לשירותי 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="/home/user/Downloads/service-account-file.json"
Windows
עם PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
אחרי שתשלימו את השלבים שלמעלה, השירות 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 עם אישורי ברירת מחדל של אפליקציית 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 Application Default Credentials שהתקבלו מהרצת 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:
אפשר לעיין בקוד הפתוח ב-GitHub עבור Node.js, Java ו-Python.
אפשר לקרוא פוסטים בבלוג שקשורים ל-Admin SDK של אחד מהיוצרים של Admin SDK. לדוגמה: גישה ל-Firestore ול-Firebase דרך שרת proxy.
הוספת תכונות של Firebase לאפליקציה:
- כתיבת קצה עורפי ללא שרת באמצעות Cloud Functions.
- אחסון מידע באמצעות Realtime Database או נתוני blob באמצעות Cloud Storage.
- קבלת התראות באמצעות Cloud Messaging.