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

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

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

למידע נוסף על שילוב 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.9 ואילך (מומלץ Python 3.10 ואילך)
      התמיכה ב-Python 3.9 הוצאה משימוש.
    • ‫Admin Go SDK — ‏Go 1.25 ואילך
    • ‫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 ניסיוני – ודאו שבשרת פועלת גרסה 3.9 ומעלה של Dart SDK.

הגדרת פרויקט ב-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.11.0'
}

אם אתם משתמשים ב-Maven כדי ליצור את האפליקציה, אתם יכולים להוסיף את יחסי התלות הבאים לקובץ pom.xml:

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.11.0</version>
</dependency>

Python

‫Firebase Admin Python SDK זמין דרך pip. אפשר להתקין את הספרייה לכל המשתמשים באמצעות sudo:

sudo pip install firebase-admin

לחלופין, אפשר להתקין את הספרייה רק למשתמש הנוכחי על ידי העברת הדגל --user:

pip install --user firebase-admin

המשך

אפשר להתקין את Admin 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.22.0

C#‎

אפשר להתקין את Admin SDK של ‎ .NET באמצעות מנהל החבילות של ‎ .NET:

Install-Package FirebaseAdmin -Version 3.7.0

לחלופין, אפשר להתקין אותו באמצעות כלי שורת הפקודה dotnet:

dotnet add package FirebaseAdmin --version 3.7.0

אפשר גם להתקין אותו על ידי הוספת רשומת ההפניה הבאה לחבילה בקובץ .csproj:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.7.0" />
</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 כדי לבצע את המשימות הבאות:

שימוש בטוקן רענון מסוג 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 בכרטיסייה Settings > Service accounts.

כדי לאמת חשבון שירות ולתת לו הרשאת גישה לשירותי Firebase, צריך ליצור קובץ מפתח פרטי בפורמט JSON.

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

  1. במסוף Firebase, נכנסים לכרטיסייה Service accounts בקטע Settings.

  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"

אחרי שתבצעו את הפעולות שלמעלה, תוכלו להשתמש בפרטי הכניסה של חשבון השירות כשאתם בודקים או מריצים את האפליקציה בסביבות שהן לא של Google, כי השירות Application Default Credentials ‏ (ADC) יוכל לקבוע באופן משתמע את פרטי הכניסה שלכם.

מאתחלים את ה-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

# 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 באופן מקומי באמצעות Application Default Credentials של Google, שמתקבלים על ידי הפעלת gcloud auth application-default login, צריך לבצע שינויים נוספים כדי להשתמש ב-Firebase Authentication מהסיבות הבאות:

  • ב-Firebase Authentication אי אפשר להשתמש בפרטי כניסה של משתמשי קצה ב-gcloud שנוצרו באמצעות מזהה הלקוח של OAuth ב-gcloud.
  • ב-Firebase Authentication צריך לספק את מזהה הפרויקט במהלך ההפעלה של פרטי הכניסה האלה של משתמש הקצה.

כדי לעקוף את הבעיה, אתם יכולים ליצור פרטי כניסה ב-Application Default Credentials (ADC) ב-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 לאפליקציה: