מוסיפים את Firebase Admin SDK לשרת

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 שנתמכות בכל שפה:

תכונה Node.js Java Python Go C#‎
יצירת אסימונים בהתאמה אישית
אימות של אסימון מזהה
ניהול משתמשים
שליטה בגישה באמצעות טענות בהתאמה אישית
ביטול של טוקן רענון
ייבוא משתמשים
ניהול קובצי Cookie זמניים
יצירת קישורים לפעולות באימייל
ניהול הגדרות של ספקי SAML/OIDC
תמיכה בריבוי דיירים (multitenancy)
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
ניהול מינויים לנושאיםFCM
Cloud Storage
Cloud Firestore
הוספת פונקציות לתור באמצעות Cloud Tasks
ניהול פרויקטים
כללי אבטחה
ניהול מודלים של ML
Firebase Remote Config
Firebase App Check
Firebase Extensions

מידע נוסף על שילוב של 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 כדי לבצע את סוגי המשימות הבאים:

שימוש בטוקן רענון של 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.

כדי ליצור קובץ מפתח פרטי לחשבון השירות:

  1. במסוף Firebase, פותחים את Settings > Service Accounts.

  2. לוחצים על Generate New Private Key (יצירת מפתח פרטי חדש) ואז על Generate Key (יצירת מפתח) כדי לאשר.

  3. מאחסנים את קובץ ה-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:

הוספת תכונות של Firebase לאפליקציה: