Admin SDK مجموعهای از کتابخانههای سرور است که به شما امکان میدهد از محیطهای ممتاز با Firebase تعامل داشته باشید تا اقداماتی مانند موارد زیر را انجام دهید:
- پُرسمانها و تغییرات را در سرویس Firebase SQL Connect برای مدیریت انبوه دادهها و سایر عملیات با امتیازات کامل سرپرست انجام دهید.
- خواندن و نوشتن دادههای Realtime Database با امتیازهای کامل سرپرست.
- بااستفاده از رویکردی ساده و جایگزین برای پروتکلهای سرور Firebase Cloud Messaging، پیامهای Firebase Cloud Messaging را بهصورت برنامهنویسیشده ارسال کنید.
- تولید و درستیسنجی کردن کدهای اصالتسنجی Firebase.
- دسترسی به منابع Google Cloud مانند سطلهای Cloud Storage و پایگاههای داده Cloud Firestore مرتبط با پروژههای Firebase شما.
- کنسول سرپرست سادهشده خودتان را ایجاد کنید تا کارهایی مثل جستجوی دادههای کاربر یا تغییر نشانی ایمیل کاربر برای اصالتسنجی را انجام دهید.
اگر میخواهید از Node.js SDK بهعنوان کارخواه برای دسترسی کاربر نهایی استفاده کنید (برای مثال، در برنامه IoT یا رایانه Node.js)، برخلاف دسترسی سرپرست از محیطی با امتیاز ویژه (مانند سرور)، باید بهجای آن دستورالعملهای راهاندازی کیت توسعه نرمافزار جاوا اسکریپت کارخواه را دنبال کنید.
در اینجا ماتریس ویژگیای وجود دارد که نشان میدهد کدام ویژگیهای Firebase در هر زبان پشتیبانی میشوند:
برای کسب اطلاعات بیشتر درباره ادغام 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+ (recommend Python 3.10+)
Python 3.9 support is deprecated. - Admin Go SDK — Go 1.25+
- Admin .NET SDK — .NET Framework 4.6.2+ or .NET Standard 2.0 or .NET 6.0+ (recommend .NET 8.0+)
.NET 6.0 and 7.0 support is deprecated. - کیت توسعه نرمافزار Dart Admin آزمایشی — مطمئن شوید که سرورتان کیت توسعه نرمافزار Dart نسخه ۳.۹ یا بالاتر را اجرا میکند.
- Admin Node.js SDK — Node.js 22+
راهاندازی پروژه Firebase و حساب سرویس
برای استفاده از Firebase Admin SDK، به موارد زیر نیاز دارید:
- پروژه Firebase.
- یک حساب سرویس Firebase Admin SDK برای برقراری ارتباط با Firebase. این حساب سرویس بهطور خودکار هنگام ایجاد پروژه Firebase یا افزودن Firebase به پروژه Google Cloud ایجاد میشود.
- فایل پیکربندی با اعتبارنامه حساب سرویس شما.
اگر ازقبل پروژه Firebase ندارید، باید پروژهای در کنسول Firebase ایجاد کنید. برای کسب اطلاعات بیشتر درباره پروژههای Firebase، به آشنایی با پروژههای Firebase مراجعه کنید.
افزودن کیت توسعه نرمافزار
اگر پروژه جدیدی راهاندازی میکنید، باید کیت توسعه نرمافزار را برای زبان انتخابیتان نصب کنید.
Node.js
کیت توسعه نرمافزار Firebase Admin Node.js در npm دردسترس است. اگر ازقبل فایل package.json ندارید،
یکی ازطریق npm init ایجاد کنید. سپس، بسته npm
firebase-admin را نصب کنید و آن را در package.json ذخیره کنید:
npm install firebase-admin --save
برای استفاده از این ماژول در برنامهتان، آن را از هر فایل جاوا اسکریپت require کنید:
const { initializeApp } = require('firebase-admin/app');
اگر از ES2015 استفاده میکنید، میتوانید واحد را import کنید:
import { initializeApp } from 'firebase-admin/app';
جاوا
کیت توسعه نرمافزار Firebase Admin Java در مخزن مرکزی 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>
پایتون
کیت توسعه نرمافزار Firebase Admin Python ازطریق
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
سی شارپ
.NET Admin SDK را میتوان بااستفاده از مدیر بسته .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';
مقداردهی اولیه کیت توسعه نرمافزار
پساز ایجاد پروژه Firebase، میتوانید کیت توسعه نرمافزار را با اعتبارنامههای پیشفرض برنامه Google مقداردهی اولیه کنید. ازآنجاییکه جستجوی اطلاعات کاربری پیشفرض در محیطهای Google کاملاً خودکار است، بدون نیاز به ارائه متغیرهای محیطی یا پیکربندیهای دیگر، این روش مقداردهی اولیه کیت توسعه نرمافزار برای برنامههایی که در محیطهای Google اجرا میشوند، مانند Firebase App Hosting، Cloud Run، App Engine، و Cloud Functions for Firebase، بهشدت توصیه میشود.
برای مشخص کردن اختیاری گزینههای مقداردهی اولیه برای سرویسهایی مثل Realtime Database،
Cloud Storage، یا Cloud Functions، از متغیر محیطی FIREBASE_CONFIG
استفاده کنید. اگر محتوای متغیر FIREBASE_CONFIG با { شروع شود، بهعنوان شیء JSON تجزیه خواهد شد. درغیراینصورت، کیت توسعه نرمافزار فرض میکند که
رشته مسیر فایل JSON حاوی گزینهها است.
Node.js
const app = initializeApp();
جاوا
FirebaseApp.initializeApp();
پایتون
default_app = firebase_admin.initialize_app()
رفتن
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
سی شارپ
FirebaseApp.Create();
Dart (آزمایشی)
final admin = FirebaseApp.initializeApp();
پساز مقداردهی اولیه، میتوانید از Admin SDK برای انجام دادن انواع تکالیف زیر استفاده کنید:
- پیادهسازی اصالتسنجی سفارشی
- مدیریت کاربران Firebase Authentication
- انجام پُرسمانهای مدیریتی و تغییرات در سرویس Firebase SQL 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'
});
جاوا
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);
پایتون
cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)
رفتن
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)
}
سی شارپ
FirebaseApp.Create(new AppOptions()
{
Credential = CredentialFactory.FromFile<UserCredential>("path/to/refreshToken.json").ToGoogleCredential(),
});
مقداردهی اولیه کیت توسعه نرمافزار در محیطهای غیرGoogle
اگر در محیط سرور غیرGoogle کار میکنید که در آن جستجوی اطلاعات کاربری پیشفرض نمیتواند کاملاً خودکارسازی شود، میتوانید SDK را با فایل کلید حساب سرویس صادرشده مقداردهی اولیه کنید.
پروژههای Firebase از حسابهای سرویس Google پشتیبانی میکنند که میتوانید از آنها برای فراخوانی میاناهای برنامهسازی کاربردی سرور Firebase از سرور برنامه یا محیط مورداعتماد خود استفاده کنید. اگر کد را بهصورت محلی توسعه میدهید یا برنامهتان را در محل مستقر میکنید، میتوانید از اطلاعات اعتباری بهدستآمده بااستفاده از این حساب خدماتی برای مجاز کردن درخواستهای سرور استفاده کنید.
میتوانید همه حسابهای سرویس پروژه Firebase خود را در
برای اصالتسنجی حساب خدمات و صدور مجوز برای آن جهت دسترسی به سرویسهای Firebase، باید فایل کلید خصوصی را در قالب JSON تولید کنید.
برای ایجاد فایل کلید خصوصی برای حساب سرویس خود:
در کنسول Firebase، به
تنظیمات > زبانه حسابهای سرویس بروید.روی تولید کلید خصوصی جدید کلیک کنید، سپس با کلیک کردن روی تولید کلید تأیید کنید.
فایل JSON حاوی کلید را بهطور ایمن ذخیره کنید.
هنگام صدور مجوز ازطریق حساب سرویس، دو گزینه برای ارائه اعتبارنامه به برنامهتان دارید. میتوانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید یا میتوانید مسیر کلید حساب سرویس را بهطور صریح در کد ارسال کنید. گزینه اول ایمنتر است و اکیداً توصیه میشود.
برای تنظیم متغیر محیطی:
متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل JSON که حاوی کلید حساب سرویس شما است تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال میشود، بنابراین اگر جلسه جدیدی باز کردید، متغیر را دوباره تنظیم کنید.
Linux یا macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
پنجره
با PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
پساز تکمیل مراحل بالا، «اعتبارنامههای پیشفرض برنامه» (ADC) میتواند بهطور ضمنی اعتبارنامههای شما را تعیین کند و به شما اجازه دهد هنگام آزمایش یا اجرا در محیطهای غیرGoogle، از اعتبارنامههای حساب سرویس استفاده کنید.
کیت توسعه نرمافزار را همانطور که نشان داده شده است مقداردهی اولیه کنید:
Node.js
initializeApp({
credential: applicationDefault(),
databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});
جاوا
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
.build();
FirebaseApp.initializeApp(options);
پایتون
default_app = firebase_admin.initialize_app()
رفتن
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
سی شارپ
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();
جاوا
// 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();
پایتون
# 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(...)
رفتن
// 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)
}
سی شارپ
// 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 به شما امکان میدهد چندین برنامه را بهطور همزمان ایجاد کنید که هرکدام اطلاعات پیکربندی خود را دارند.
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);
جاوا
// 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);
پایتون
# 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)
رفتن
// 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)
}
سی شارپ
// 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 VM با اعتبارنامههای پیشفرض برنامه 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
که با اجرای 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>',
});
جاوا
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setProjectId("<FIREBASE_PROJECT_ID>")
.build();
FirebaseApp.initializeApp(options);
پایتون
app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)
رفتن
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)
}
سی شارپ
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
ProjectId = "<FIREBASE_PROJECT_ID>",
});
مراحل بعدی
با Firebase آشنا شوید:
نمونه برنامههای Firebase را کاوش کنید.
کد منبعباز را در GitHub برای Node.js، Java، و Python کاوش کنید.
پستهای وبلاگ مرتبط با Admin SDK را که یکی از سازندگان Admin SDK نوشته است بخوانید. برای مثال: دسترسی به Firestore و Firebase ازطریق پراکسی سرور.
افزودن ویژگیهای Firebase به برنامه:
- با Cloud Functions، یک پسای بدون سرور بنویسید.
- اطلاعات فروشگاه با Realtime Database یا دادههای blob با Cloud Storage.
- با Cloud Messaging اعلان دریافت کنید.