Firebase Admin SDK را به سرور خود اضافه کنید

Admin SDK مجموعه‌ای از کتابخانه‌های سرور است که به شما امکان می‌دهد از محیط‌های دارای امتیاز بالا با Firebase تعامل داشته باشید تا اقداماتی مانند موارد زیر را انجام دهید:

  • انجام کوئری‌ها و جهش‌ها روی سرویس Firebase Data Connect برای مدیریت داده‌های حجیم و سایر عملیات با دسترسی کامل ادمین.
  • خواندن و نوشتن داده‌های Realtime Database با امتیازات کامل ادمین.
  • با استفاده از یک رویکرد ساده و جایگزین برای پروتکل‌های سرور Firebase Cloud Messaging ، پیام‌های Firebase Cloud Messaging به صورت برنامه‌نویسی شده ارسال کنید.
  • توکن‌های احراز هویت Firebase را تولید و تأیید کنید.
  • به منابع Google Cloud مانند Cloud Storage buckets و پایگاه‌های داده Cloud Firestore مرتبط با پروژه‌های Firebase خود دسترسی پیدا کنید.
  • کنسول مدیریت ساده‌شده‌ی خودتان را ایجاد کنید تا کارهایی مانند جستجوی داده‌های کاربر یا تغییر آدرس ایمیل کاربر برای احراز هویت را انجام دهید.

اگر علاقه‌مند به استفاده از SDK Node.js به عنوان یک کلاینت برای دسترسی کاربر نهایی (به عنوان مثال، در یک برنامه دسکتاپ Node.js یا IoT) هستید، به جای دسترسی ادمین از یک محیط ممتاز (مانند یک سرور)، باید دستورالعمل‌های راه‌اندازی SDK جاوا اسکریپت کلاینت را دنبال کنید.

در اینجا یک ماتریس ویژگی وجود دارد که نشان می‌دهد چه ویژگی‌های Firebase در هر زبان پشتیبانی می‌شوند:

ویژگی نود جی اس جاوا پایتون برو سی شارپ
ضرب توکن سفارشی
تأیید شناسه توکن
مدیریت کاربر
کنترل دسترسی با ادعاهای سفارشی
ابطال توکن به‌روزرسانی
وارد کردن کاربران
مدیریت کوکی‌های جلسه
ایجاد لینک‌های اقدام ایمیلی
مدیریت پیکربندی‌های ارائه‌دهنده SAML/OIDC
پشتیبانی از چند مستاجری
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
چندپخشی FCM
مدیریت اشتراک‌های موضوعی 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 که استفاده می‌کنید، موارد زیر را اجرا می‌کند:

    • کیت توسعه نرم‌افزار (SDK) برای مدیریت Node.js — Node.js 18+
    • کیت توسعه نرم‌افزار (SDK) مدیریت جاوا - جاوا ۸+
    • کیت توسعه نرم‌افزار (SDK) پایتون برای ادمین - پایتون ۳.۹+ (پایتون ۳.۱۰+ توصیه می‌شود)
      پشتیبانی از پایتون ۳.۹ منسوخ شده است.
    • کیت توسعه نرم‌افزار (SDK) برای مدیریت Go — نسخه ۱.۲۳+
    • کیت توسعه نرم‌افزاری دات‌نت برای ادمین — دات‌نت فریم‌ورک ۴.۶.۲+ یا دات‌نت استاندارد ۲.۰ یا دات‌نت ۶.۰+ (دات‌نت ۸.۰+ توصیه می‌شود)
      پشتیبانی از دات‌نت ۶.۰ و ۷.۰ منسوخ شده است.

یک حساب کاربری پروژه و سرویس Firebase راه‌اندازی کنید

برای استفاده از Firebase Admin SDK ، به موارد زیر نیاز دارید:

  • یک پروژه فایربیس.
  • یک حساب کاربری سرویس Firebase Admin SDK برای ارتباط با Firebase. این حساب کاربری سرویس به طور خودکار هنگام ایجاد یک پروژه Firebase یا اضافه کردن Firebase به یک پروژه Google Cloud ایجاد می‌شود.
  • یک فایل پیکربندی حاوی اطلاعات حساب کاربری سرویس شما.

اگر از قبل پروژه Firebase ندارید، باید یکی را در کنسول Firebase ایجاد کنید. برای کسب اطلاعات بیشتر در مورد پروژه‌های Firebase، به بخش «درک پروژه‌های Firebase» مراجعه کنید.

اضافه کردن SDK

اگر در حال راه‌اندازی یک پروژه جدید هستید، باید SDK مربوط به زبان مورد نظر خود را نصب کنید.

نود جی اس

کیت توسعه نرم‌افزار (SDK) مربوط به 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';

جاوا

کیت توسعه نرم‌افزاری جاوای فایربیس ادمین در مخزن مرکزی Maven منتشر شده است. برای نصب این کتابخانه، آن را به عنوان یک وابستگی در فایل build.gradle خود اعلام کنید:

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

اگر از Maven برای ساخت برنامه خود استفاده می‌کنید، می‌توانید وابستگی زیر را به pom.xml خود اضافه کنید:

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

پایتون

کیت توسعه نرم‌افزار (SDK) پایتون برای فایربیس ادمین از طریق pip در دسترس است. می‌توانید این کتابخانه را برای همه کاربران از طریق sudo نصب کنید:

sudo pip install firebase-admin

یا می‌توانید با قرار دادن پرچم --user ، کتابخانه را فقط برای کاربر فعلی نصب کنید:

pip install --user firebase-admin

برو

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.18.0

سی شارپ

کیت توسعه نرم‌افزاری مدیریت دات‌نت (.NET Admin SDK می‌توان با استفاده از مدیر بسته دات‌نت نصب کرد:

Install-Package FirebaseAdmin -Version 3.4.0

روش دیگر، نصب آن با استفاده از ابزار خط فرمان dotnet است:

dotnet add package FirebaseAdmin --version 3.4.0

یا می‌توانید آن را با اضافه کردن ورودی مرجع بسته زیر به فایل .csproj خود نصب کنید:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.4.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 حاوی گزینه‌ها است.

نود جی اس

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();

پس از مقداردهی اولیه، می‌توانید از Admin SDK برای انجام انواع وظایف زیر استفاده کنید:

استفاده از توکن به‌روزرسانی OAuth 2.0

Admin SDK همچنین یک اعتبارنامه ارائه می‌دهد که به شما امکان می‌دهد با یک توکن به‌روزرسانی Google OAuth2 احراز هویت کنید:

نود جی اس

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 = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

مقداردهی اولیه SDK در محیط‌های غیر گوگلی

اگر در یک محیط سرور غیر گوگل کار می‌کنید که در آن جستجوی پیش‌فرض اعتبارنامه‌ها نمی‌تواند کاملاً خودکار باشد، می‌توانید SDK را با یک فایل کلید حساب سرویس صادر شده، مقداردهی اولیه کنید.

پروژه‌های فایربیس از حساب‌های سرویس گوگل پشتیبانی می‌کنند که می‌توانید از آن‌ها برای فراخوانی APIهای سرور فایربیس از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی هستید یا برنامه خود را در محل مستقر می‌کنید، می‌توانید از اعتبارنامه‌های به دست آمده از طریق این حساب سرویس برای تأیید درخواست‌های سرور استفاده کنید.

برای تأیید اعتبار یک حساب کاربری سرویس و اجازه دسترسی آن به سرویس‌های Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.

برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:

  1. در کنسول Firebase ، تنظیمات > حساب‌های سرویس ( Settings > Service Accounts) را باز کنید.

  2. روی «ایجاد کلید خصوصی جدید» کلیک کنید، سپس با کلیک روی «ایجاد کلید» تأیید کنید.

  3. فایل JSON حاوی کلید را به طور ایمن ذخیره کنید.

هنگام تأیید اعتبار از طریق یک حساب کاربری سرویس، دو گزینه برای ارائه اعتبارنامه به برنامه خود دارید. می‌توانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید، یا می‌توانید مسیر کلید حساب کاربری سرویس را به صورت کد به صراحت ارسال کنید. گزینه اول امن‌تر است و اکیداً توصیه می‌شود.

برای تنظیم متغیر محیطی:

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل JSON که حاوی کلید حساب سرویس شماست، تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می‌شود، بنابراین اگر یک جلسه جدید باز کردید، دوباره متغیر را تنظیم کنید.

لینوکس یا macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

ویندوز

با پاورشل:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

پس از تکمیل مراحل فوق، اعتبارنامه‌های پیش‌فرض برنامه (ADC) قادر است به‌طور ضمنی اعتبارنامه‌های شما را تعیین کند و به شما امکان می‌دهد هنگام آزمایش یا اجرا در محیط‌های غیر گوگلی، از اعتبارنامه‌های حساب سرویس استفاده کنید.

SDK را مطابق شکل مقداردهی اولیه کنید:

نود جی اس

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",
});

مقداردهی اولیه چندین برنامه

در بیشتر موارد، شما فقط باید یک برنامه پیش‌فرض را راه‌اندازی کنید. می‌توانید به دو روش معادل به سرویس‌های آن برنامه دسترسی داشته باشید:

نود جی اس

// 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 SDK به شما امکان می‌دهد چندین برنامه را همزمان ایجاد کنید که هر کدام اطلاعات پیکربندی خاص خود را دارند.

نود جی اس

// 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 با اعتبارنامه‌های پیش‌فرض برنامه Google برای Realtime Database یا Authentication استفاده می‌کنید، مطمئن شوید که محدوده‌های دسترسی صحیح را نیز تنظیم کرده‌اید. برای Realtime Database و Authentication ، به محدوده‌هایی نیاز دارید که به userinfo.email و cloud-platform یا firebase.database ختم شوند. برای بررسی محدوده‌های دسترسی موجود و تغییر آنها، دستورات زیر را با استفاده از 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 به صورت محلی با اعتبارنامه‌های پیش‌فرض برنامه گوگل که با اجرای gcloud auth application-default login به دست آمده‌اند، به دلایل زیر، تغییرات اضافی برای استفاده Firebase Authentication مورد نیاز است:

  • Firebase Authentication اعتبارنامه‌های کاربر نهایی gcloud که با استفاده از شناسه کلاینت OAuth gcloud تولید می‌شوند را نمی‌پذیرد.
  • Firebase Authentication مستلزم آن است که شناسه پروژه در هنگام مقداردهی اولیه برای این نوع اعتبارنامه‌های کاربر نهایی ارائه شود.

به عنوان یک راه حل، می‌توانید اعتبارنامه‌های پیش‌فرض برنامه گوگل را در gcloud با استفاده از شناسه کلاینت OAuth 2.0 خود ایجاد کنید. شناسه کلاینت OAuth باید از نوع برنامه دسکتاپ باشد.

جی‌کلاود

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

می‌توانید شناسه پروژه را به طور صریح در هنگام مقداردهی اولیه برنامه مشخص کنید یا فقط از متغیر محیطی GOOGLE_CLOUD_PROJECT استفاده کنید. مورد دوم از نیاز به ایجاد تغییرات اضافی برای آزمایش کد شما جلوگیری می‌کند.

برای مشخص کردن صریح شناسه پروژه:

نود جی اس

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>",
});

مراحل بعدی

آشنایی با فایربیس:

ویژگی‌های فایربیس را به برنامه خود اضافه کنید: