Admin SDK — это набор серверных библиотек, которые позволяют взаимодействовать с Firebase из привилегированных сред для выполнения таких действий, как:
- Выполняйте запросы и мутации в службе Firebase Data Connect для управления массовыми данными и других операций с полными правами администратора.
- Чтение и запись данных Realtime Database с полными правами администратора.
- Программная отправка сообщений Firebase Cloud Messaging с использованием простого альтернативного подхода к протоколам сервера Firebase Cloud Messaging .
- Сгенерируйте и проверьте токены аутентификации Firebase.
- Получите доступ к ресурсам Google Cloud , таким как хранилища Cloud Storage и базы данных Cloud Firestore , связанные с вашими проектами Firebase.
- Создайте собственную упрощенную консоль администратора для выполнения таких задач, как поиск данных пользователя или изменение адреса электронной почты пользователя для аутентификации.
Если вы заинтересованы в использовании Node.js SDK в качестве клиента для доступа конечного пользователя (например, в приложении Node.js для настольных компьютеров или Интернета вещей), а не в административном доступе из привилегированной среды (например, сервера), вам следует вместо этого следовать инструкциям по настройке клиентского JavaScript SDK .
Ниже представлена матрица функций, показывающая, какие функции Firebase поддерживаются на каждом языке:
Чтобы узнать больше об интеграции Admin SDK для этих целей, см. соответствующую документацию Realtime Database , FCM , Authentication , Remote Config и Cloud Storage . Остальная часть этой страницы посвящена базовой настройке Admin SDK .
Предпосылки
Убедитесь, что у вас есть серверное приложение.
Убедитесь, что на вашем сервере запущено следующее (в зависимости от используемого вами Admin SDK :
- Администрирование Node.js SDK — Node.js 18+
- Java SDK для администратора — Java 8+
- Admin Python SDK — Python 3.7+ (рекомендуется Python 3.8+)
Поддержка Python 3.7 устарела. - Admin Go SDK — Go 1.21+
- Admin .NET SDK — .NET Framework 4.6.2+ или .NET Standard 2.0 для .NET 6.0+
Настройте проект Firebase и учетную запись службы
Для использования Firebase Admin SDK вам понадобится следующее:
- Проект Firebase.
- Учетная запись службы Firebase Admin SDK для связи с Firebase. Эта учетная запись службы создается автоматически при создании проекта Firebase или добавлении Firebase в проект Google Cloud.
- Файл конфигурации с учетными данными вашей учетной записи службы.
Если у вас еще нет проекта Firebase, вам нужно создать его в консоли Firebase . Посетите раздел Understand Firebase Projects , чтобы узнать больше о проектах Firebase.
Добавить SDK
Если вы создаете новый проект, вам необходимо установить SDK для выбранного вами языка.
Node.js
Firebase Admin Node.js SDK доступен на 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';
Ява
Firebase Admin Java SDK опубликован в центральном репозитории Maven. Чтобы установить библиотеку, объявите ее как зависимость в файле build.gradle
:
dependencies {
implementation 'com.google.firebase:firebase-admin:9.4.3'
}
Если вы используете Maven для сборки своего приложения, вы можете добавить следующую зависимость в свой pom.xml
:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.4.3</version>
</dependency>
Питон
Firebase Admin Python SDK доступен через 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.15.2
С#
.NET Admin SDK можно установить с помощью менеджера пакетов .NET:
Install-Package FirebaseAdmin -Version 3.2.0
Либо установите его с помощью утилиты командной строки dotnet
:
dotnet add package FirebaseAdmin --version 3.2.0
Или вы можете установить его, добавив следующую ссылку на пакет в ваш файл .csproj
:
<ItemGroup>
<PackageReference Include="FirebaseAdmin" Version="3.2.0" />
</ItemGroup>
Инициализируйте SDK
После создания проекта Firebase вы можете инициализировать SDK с помощью учетных данных Google 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();
Ява
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 для выполнения следующих типов задач:
- Внедрить индивидуальную аутентификацию
- Управляйте пользователями 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'
});
Ява
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 в средах, отличных от 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"
Окна
С 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'
});
Ява
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 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);
Ява
// 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 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, полученными путем запуска gcloud auth application-default login
, необходимы дополнительные изменения для использования Firebase Authentication по следующим причинам:
- Firebase Authentication не принимает учетные данные конечного пользователя gcloud, сгенерированные с использованием идентификатора клиента gcloud OAuth.
- Для Firebase Authentication при инициализации таких учетных данных конечного пользователя требуется указать идентификатор проекта.
В качестве обходного пути вы можете сгенерировать учетные данные Google Application Default в gcloud , используя собственный идентификатор клиента OAuth 2.0 . Идентификатор клиента OAuth должен быть типом приложения Desktop app .
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 или данные больших двоичных объектов в Cloud Storage .
- Получайте уведомления с помощью Cloud Messaging .