מוסיפים את 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.
  • אתם יכולים ליצור מסוף ניהול פשוט משלכם כדי לבצע פעולות כמו חיפוש נתוני משתמשים או שינוי כתובת האימייל של משתמש לצורך אימות.

אם אתם רוצים להשתמש ב-SDK של Node.js כלקוח לגישה של משתמשי קצה (לדוגמה, באפליקציית Node.js למחשב או ל-IoT), בניגוד לגישה של אדמין מסביבה בעלת הרשאות (כמו שרת), עליכם לפעול לפי ההוראות להגדרת ה-SDK של JavaScript ללקוח.

בטבלה הבאה מפורטות התכונות של Firebase שנתמכות בכל שפה:

תכונה Node.js Java Python Go C#‎
טביעת אסימונים בהתאמה אישית
אימות אסימון מזהה
ניהול משתמשים
בקרה על הגישה באמצעות הצהרות מותאמות אישית
ביטול של טוקן רענון
ייבוא משתמשים
ניהול של קובצי cookie זמניים
יצירת קישורי פעולה באימייל
ניהול ההגדרות של ספקי SAML/OIDC
תמיכה בריבוי דיירים (multi-tenancy)
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
ניהול FCM מינויים לנושאים
Cloud Storage
Cloud Firestore
הוספת פונקציות לתור באמצעות Cloud Tasks
ניהול פרויקטים
כללי אבטחה
ניהול מודלים של למידת מכונה
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 מגרסה 14 ואילך (מומלץ Node.js מגרסה 18 ואילך)
      התמיכה ב-Node.js בגרסאות 14 ו-16 הוצאה משימוש.
    • Admin Java SDK –‏ Java 8 ואילך
    • Admin Python SDK –‏ Python 3.7 ואילך (מומלץ Python 3.8 ואילך)
      התמיכה ב-Python 3.7 הוצאה משימוש.
    • Admin Go SDK — Go 1.20+
    • Admin .NET SDK — .NET Framework 4.6.2+ או .NET Standard 2.0 ל- .NET 6.0+

הגדרת פרויקט וחשבון שירות ב-Firebase

כדי להשתמש ב-Firebase Admin SDK, צריך את הפריטים הבאים:

  • יש לכם פרויקט Firebase.
  • חשבון שירות של SDK של Firebase לאדמינים, לצורך תקשורת עם Firebase. חשבון השירות הזה נוצר באופן אוטומטי כשיוצרים פרויקט ב-Firebase או מוסיפים את Firebase לפרויקט ב-Google Cloud.
  • קובץ תצורה עם פרטי הכניסה של חשבון השירות.

אם עדיין אין לכם פרויקט Firebase, תצטרכו ליצור פרויקט במסוף Firebase. למידע נוסף על פרויקטים ב-Firebase, אפשר לעיין במאמר הסבר על פרויקטים ב-Firebase.

הוספת ה-SDK

אם אתם מגדירים פרויקט חדש, עליכם להתקין את ה-SDK בשפה שבחרתם.

Node.js

ה-SDK של Firebase Admin עבור Node.js זמין ב-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 של Firebase Admin עבור Java מפורסם במאגר המרכזי של Maven. כדי להתקין את הספרייה, מגדירים אותה כיחס תלות בקובץ build.gradle:

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.4.1'
}

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

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

Python

ה-SDK של Firebase לאדמינים ב-Python זמין דרך 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.15.0

C#‎

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

Install-Package FirebaseAdmin -Version 3.1.0

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

dotnet add package FirebaseAdmin --version 3.1.0

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

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.1.0" />
</ItemGroup>

אתחול ה-SDK

אחרי שיוצרים פרויקט Firebase, אפשר לאתחל את ה-SDK באמצעות Google Application Default Credentials. חיפוש פרטי הכניסה שמוגדר כברירת מחדל הוא אוטומטי לחלוטין בסביבות Google, ואין צורך לספק משתני סביבה או הגדרות אחרות. לכן, מומלץ מאוד לאתחל את ה-SDK באפליקציות שפועלות בסביבות של Google כמו Cloud Run, App Engine ו-Cloud Functions.

כדי לציין אפשרויות אתחול לשירותים כמו 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)
}
init.go

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)
}
init.go

C#‎

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

איך מאתחלים את ה-SDK בסביבות שאינן של Google

אם אתם עובדים בסביבת שרת שאינה של Google, שבה אי אפשר להפוך את החיפוש של פרטי הכניסה שמוגדרים כברירת מחדל לאוטומטי לחלוטין, תוכלו לאתחל את ה-SDK באמצעות קובץ מפתח של חשבון שירות שיוצאו.

פרויקטים ב-Firebase תומכים בחשבונות שירות של Google, שבאמצעותם אפשר לבצע קריאה ל-API של שרת Firebase משרת האפליקציה או מסביבה מהימנה. אם אתם מפתחים קוד באופן מקומי או פורסים את האפליקציה בארגון, תוכלו להשתמש בפרטי הכניסה שהתקבלו דרך חשבון השירות הזה כדי לאשר בקשות מהשרת.

כדי לאמת חשבון שירות ולאשר לו גישה לשירותי 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)
}
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;

בתרחישי שימוש מסוימים צריך ליצור כמה אפליקציות בו-זמנית. לדוגמה, יכול להיות שתרצו לקרוא נתונים מ-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)
}
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);

הגדרת היקפים ל-Realtime Database ול-Authentication

אם אתם משתמשים במכונה וירטואלית של Google Compute Engine עם פרטי הכניסה שמוגדרים כברירת מחדל של Google App ל-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, צריך לספק את מזהה הפרויקט בזמן האתחול בפרטי הכניסה של משתמש הקצה מהסוג הזה.

כפתרון עקיף, אפשר ליצור את פרטי הכניסה של Google Application Default Credentials ב-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: