Admin SDK — это набор серверных библиотек, который позволяет вам взаимодействовать с Firebase из привилегированных сред для выполнения таких действий, как:
- Чтение и запись данных базы данных в реальном времени с полными правами администратора.
- Программно отправляйте сообщения 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 для этих целей, см. соответствующую документацию по базе данных реального времени , FCM , аутентификации , удаленной настройке и облачному хранилищу . Остальная часть этой страницы посвящена базовой настройке Admin SDK.
Предпосылки
Убедитесь, что у вас есть серверное приложение.
Убедитесь, что на вашем сервере работает следующее, в зависимости от того, какой Admin SDK вы используете:
- Администратор Node.js SDK — Node.js 14+
- Администратор Java SDK — Java 8+
- Администратор Python SDK — Python 3.6+ (рекомендуется Python 3.7+)
- Админ Go SDK — Go 1.17+
- Admin .NET SDK — .NET Framework 4.6.1+ или .NET Standard 2.0 для .Net Core 2.0+
Настройте проект Firebase и сервисный аккаунт
Чтобы использовать Firebase Admin SDK, вам потребуется следующее:
- Проект Firebase.
- Сервисный аккаунт Firebase Admin SDK для связи с Firebase. Этот сервисный аккаунт создается автоматически, когда вы создаете проект Firebase или добавляете Firebase в проект Google Cloud.
- Файл конфигурации с учетными данными вашей учетной записи службы.
Если у вас еще нет проекта Firebase, вам нужно создать его в консоли Firebase . Посетите страницу Understand Firebase Projects , чтобы узнать больше о проектах Firebase.
Добавьте SDK
Если вы настраиваете новый проект, вам необходимо установить SDK для выбранного вами языка.
Node.js
SDK Firebase Admin Node.js доступен на 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';
Джава
Пакет Firebase Admin Java SDK публикуется в центральном репозитории Maven. Чтобы установить библиотеку, объявите ее как зависимость в файле build.gradle
:
dependencies {
implementation 'com.google.firebase:firebase-admin:9.2.0'
}
Если вы используете Maven для создания своего приложения, вы можете добавить следующую зависимость в свой pom.xml
:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.2.0</version>
</dependency>
Питон
Пакет Firebase Admin Python SDK доступен через pip . Вы можете установить библиотеку для всех пользователей через sudo
:
sudo pip install firebase-admin
Или вы можете установить библиотеку только для текущего пользователя, передав флаг --user
:
pip install --user firebase-admin
Идти
Go Admin SDK можно установить с помощью утилиты go install
:
# Install the latest version:
go install firebase.google.com/go/v4@latest
# Or install a specific version:
go install firebase.google.com/go/v4@4.12.1
С#
.NET Admin SDK можно установить с помощью диспетчера пакетов .NET:
Install-Package FirebaseAdmin -Version 2.4.0
Кроме того, установите его с помощью утилиты командной строки dotnet
:
dotnet add package FirebaseAdmin --version 2.4.0
Или вы можете установить его, добавив следующую запись ссылки на пакет в свой файл .csproj
:
<ItemGroup>
<PackageReference Include="FirebaseAdmin" Version="2.4.0" />
</ItemGroup>
Инициализировать SDK
Создав проект Firebase, вы можете инициализировать SDK с учетными данными приложения Google по умолчанию . Поскольку поиск учетных данных по умолчанию полностью автоматизирован в средах Google и не требует указания переменных среды или другой конфигурации, этот способ инициализации SDK настоятельно рекомендуется для приложений, работающих в средах Google, таких как Cloud Run, App Engine и 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 Cloud Messaging
Использование токена обновления OAuth 2.0
Административный 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, содержащему ключ вашей учетной записи службы. Эта переменная применяется только к вашему текущему сеансу оболочки, поэтому, если вы открываете новый сеанс, установите переменную снова.
Линукс или макОС
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.
Инициализируйте 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;
В некоторых случаях использования требуется создать несколько приложений одновременно. Например, вы можете захотеть прочитать данные из базы данных реального времени одного проекта 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);
Установите области для базы данных в реальном времени и проверки подлинности
Если вы используете виртуальную машину Google Compute Engine с учетными данными приложения Google по умолчанию для базы данных в реальном времени или проверки подлинности, обязательно установите правильные области доступа . Для базы данных в реальном времени и проверки подлинности вам потребуются области, оканчивающиеся на 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 необходимы дополнительные изменения по следующим причинам:
- 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>',
});
Джава
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 .
- Храните информацию в базе данных реального времени или данные BLOB-объектов в облачном хранилище .
- Получайте уведомления с помощью Cloud Messaging .