מוסיפים את 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 Admin עבור Python דרך pip. אפשר להתקין את הספרייה לכל המשתמשים דרך sudo:

sudo pip install firebase-admin

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

pip install --user firebase-admin

Go

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

C#‎

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

Install-Package FirebaseAdmin -Version 3.0.1

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

dotnet add package FirebaseAdmin --version 3.0.1

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

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.0.1" />
</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)
}

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, שאפשר להשתמש בהם כדי לקרוא לממשקי ה-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)
}

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

  • Firebase Authentication לא מקבל פרטי כניסה של משתמשי קצה ב-gcloud שנוצרו באמצעות מזהה הלקוח של gcloud OAuth.
  • כדי להשתמש בפרטי הכניסה האלה של משתמשי קצה, צריך לספק את מזהה הפרויקט בזמן האתחול של 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: