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 или приложении для Интернета вещей), а не для административного доступа из привилегированной среды (например, сервера), вам следует следовать инструкциям по настройке клиентского JavaScript SDK .
Ниже представлена таблица с описанием поддерживаемых функций Firebase на каждом языке:
Чтобы узнать больше об интеграции Admin SDK для этих целей, см. соответствующую документацию Realtime Database , FCM , Authentication , Remote Config и Cloud Storage . Остальная часть этой страницы посвящена базовой настройке Admin SDK .
Предварительные требования
Убедитесь, что у вас есть серверное приложение.
Убедитесь, что на вашем сервере запущены следующие компоненты в зависимости от используемой Admin SDK :
- Admin Node.js SDK — Node.js 18+
- Admin Java SDK — Java 8+
- Admin Python SDK — Python 3.9+ (рекомендуется Python 3.10+)
Поддержка Python 3.9 устарела. - Административный SDK Go — Go 1.23+
- Административный .NET SDK — .NET Framework 4.6.2+ или .NET Standard 2.0 или .NET 6.0+ (рекомендуется .NET 8.0+)
Поддержка .NET 6.0 и 7.0 устарела.
Настройте проект Firebase и учетную запись службы.
Для использования Firebase Admin SDK вам потребуется следующее:
- Проект Firebase.
- Сервисная учетная запись Firebase Admin SDK для взаимодействия с Firebase. Эта сервисная учетная запись создается автоматически при создании проекта Firebase или добавлении Firebase в проект Google Cloud.
- Файл конфигурации, содержащий учетные данные вашей служебной учетной записи.
Если у вас еще нет проекта Firebase, вам необходимо создать его в консоли Firebase . Подробнее о проектах Firebase можно узнать в разделе «Понимание проектов Firebase».
Добавьте SDK
При создании нового проекта необходимо установить SDK для выбранного вами языка программирования.
Node.js
SDK Firebase Admin для Node.js доступен в npm. Если у вас еще нет файла package.json , создайте его с помощью npm init . Затем установите пакет firebase-admin npm и сохраните его в файле package.json :
npm install firebase-admin --save
Чтобы использовать модуль в своем приложении, require его из любого JavaScript-файла:
const { initializeApp } = require('firebase-admin/app');
Если вы используете ES2015, вы можете import модуль:
import { initializeApp } from 'firebase-admin/app';
Java
Java SDK для Firebase Admin опубликован в центральном репозитории 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>
Python
Пакет SDK для администрирования Firebase на Python доступен через pip . Вы можете установить библиотеку для всех пользователей с помощью sudo :
sudo pip install firebase-admin
Или же вы можете установить библиотеку только для текущего пользователя, передав флаг --user :
pip install --user firebase-admin
Идти
Пакет 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.18.0
C#
Пакет .NET Admin SDK можно установить с помощью менеджера пакетов .NET:
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, содержащему параметры.
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();
После инициализации вы можете использовать Admin SDK для выполнения следующих типов задач:
- Реализуйте пользовательскую аутентификацию
- Управляйте пользователями Firebase Authentication
- Выполняйте административные запросы и изменения данных в сервисе Firebase Data 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 = GoogleCredential.FromFile("path/to/refreshToken.json"),
});
Инициализация SDK в средах, отличных от Google.
Если вы работаете в среде, не относящейся к серверам Google, где поиск учетных данных по умолчанию не может быть полностью автоматизирован, вы можете инициализировать SDK с помощью экспортированного файла ключа учетной записи службы.
Проекты Firebase поддерживают сервисные учетные записи Google, которые можно использовать для вызова API сервера 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"
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()
Идти
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 с учетными данными Google 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, сгенерированные с использованием идентификатора клиента gcloud OAuth.
- Для 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>',
});
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 или большие двоичные объекты в Cloud Storage .
- Получайте уведомления через Cloud Messaging .