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 в качестве клиента для доступа конечных пользователей (например, в настольном приложении Node.js или приложении IoT), а не для доступа администратора из привилегированной среды (например, сервера), следуйте инструкциям по настройке клиентского JavaScript SDK.
В таблице ниже показано, какие функции 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 и более поздних версий (рекомендуется 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. Убедитесь, что на сервере установлен Dart SDK 3.9 или более поздней версии.
- Admin Node.js SDK – Node.js 22+
Как настроить проект Firebase и сервисный аккаунт
Чтобы использовать Firebase Admin SDK, вам понадобится следующее:
- Проект Firebase.
- Сервисный аккаунт Firebase Admin SDK для взаимодействия с Firebase. Этот сервисный аккаунт создается автоматически при создании проекта Firebase или добавлении Firebase в облачный проект Google Cloud.
- Файл конфигурации с учетными данными сервисного аккаунта.
Если у вас ещё нет проекта 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()
Проложить маршрут
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 для выполнения следующих типов задач:
- Как реализовать собственную аутентификацию
- Управление пользователями 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'
});
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)
Проложить маршрут
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, откройте раздел
Чтобы выполнить аутентификацию сервисного аккаунта и предоставить ему доступ к сервисам Firebase, необходимо создать файл закрытого ключа в формате JSON.
Чтобы создать файл закрытого ключа для сервисного аккаунта, выполните следующие действия:
В консоли Firebase перейдите в раздел
Settings (Настройки) > Service accounts (Сервисные аккаунты).Нажмите Создать новый закрытый ключ, а затем подтвердите действие, нажав Создать ключ.
Сохраните 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"
После выполнения описанных выше действий стандартные учетные данные приложения (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()
Проложить маршрут
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(...)
Проложить маршрут
// 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)
Проложить маршрут
// 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 с Google Application Default Credentials, полученными с помощью gcloud auth application-default login, требуются дополнительные изменения для использования Firebase Authentication по следующим причинам:
- Firebase Authentication не принимает учетные данные конечных пользователей gcloud, сгенерированные с помощью идентификатора клиента OAuth gcloud.
- Для инициализации учетных данных конечных пользователей этого типа в Firebase Authentication необходимо указать идентификатор проекта.
В качестве временного решения вы можете сгенерировать 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)
Проложить маршрут
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.
Изучите открытый исходный код на GitHub для Node.js, Java и Python.
Прочитайте записи в блоге, посвященные Admin SDK, от одного из создателей Admin SDK. Например, доступ к Firestore и Firebase через прокси-сервер.
Добавьте функции Firebase в приложение:
- Создайте бессерверный бэкенд с помощью Cloud Functions.
- Храните информацию с помощью Realtime Database или данные BLOB с помощью Cloud Storage.
- Получайте уведомления с помощью Cloud Messaging.