Admin SDK to zestaw bibliotek serwera, który umożliwia interakcję z Firebase z prywatnych środowisk w celu wykonywania takich działań jak:
- Wykonuj zapytania i mutacje w usłudze Firebase Data Connect w celu zbiorczego zarządzania danymi i innych operacji z pełnymi uprawnieniami administratora.
- Odczytywanie i zapisywanie danych Realtime Database z pełnymi uprawnieniami administratora.
- Automatycznie wysyłaj wiadomości Firebase Cloud Messaging, korzystając z prostej, alternatywnej metody obsługi protokołów serwera Firebase Cloud Messaging.
- generować i weryfikować tokeny uwierzytelniania Firebase.
- Dostęp do zasobów typu Google Cloud, takich jak zasobniki Cloud Storage i bazy danych Cloud Firestore powiązane z Twoimi projektami Firebase.
- Utwórz własną uproszczoną konsolę administracyjną, aby wykonywać takie czynności jak wyszukiwanie danych użytkownika lub zmiana adresu e-mail użytkownika na potrzeby uwierzytelniania.
Jeśli chcesz używać pakietu Node.js SDK jako klienta do uzyskiwania dostępu przez użytkowników końcowych (np. w aplikacji Node.js na komputer lub IoT), zamiast dostępu administracyjnego z otoczenia uprzywilejowanego (np. serwera), wykonaj instrukcje konfigurowania pakietu SDK JavaScript dla klienta.
Oto tabela funkcji z funkcjami Firebase obsługiwanymi w poszczególnych językach:
Aby dowiedzieć się więcej o integracji Admin SDK w tych zastosowaniach, zapoznaj się z odpowiednimi dokumentami Realtime Database, FCM, Authentication, Remote Config i Cloud Storage. Pozostała część tej strony dotyczy podstawowej konfiguracji urządzenia Admin SDK.
Wymagania wstępne
Upewnij się, że masz aplikację serwera.
W zależności od używanego serwera Admin SDKupewnij się, że serwer działa w taki sposób:
- Admin Node.js SDK – Node.js 14 lub nowszy (zalecany Node.js 18 lub nowszy)
Obsługa Node.js 14 i 16 została wycofana. - Admin Java SDK – Java 8 lub nowsza
- Pakiet SDK Python dla administratora – Python 3.7 lub nowszy (zalecamy Pythona 3.8 lub nowszego)
Obsługa Pythona 3.7 została wycofana. - Pakiet Admin Go SDK – Go 1.20 lub nowszy
- Pakiet .NET SDK dla administratora – .NET Framework w wersji 4.6.2 lub nowszej albo .NET Standard 2.0 w przypadku .NET 6.0 lub nowszej.
- Admin Node.js SDK – Node.js 14 lub nowszy (zalecany Node.js 18 lub nowszy)
Konfigurowanie projektu i konta usługi Firebase
Aby korzystać z Firebase Admin SDK, musisz mieć:
- Masz projekt Firebase.
- Konto usługi pakietu Firebase Admin SDK do komunikacji z Firebase. To konto usługi jest tworzone automatycznie, gdy tworzysz projekt Firebase lub dodajesz Firebase do projektu Google Cloud.
- Plik konfiguracji z danymi logowania do konta usługi.
Jeśli nie masz jeszcze projektu Firebase, utwórz go w konsoli Firebase. Więcej informacji o projektach Firebase znajdziesz w artykule [EN] Understanding Firebase Projects.
Dodawanie SDK
Jeśli konfigurujesz nowy projekt, musisz zainstalować pakiet SDK dla wybranego języka.
Node.js
Pakiet Firebase Admin SDK dla Node.js jest dostępny w npm. Jeśli nie masz jeszcze pliku package.json
, utwórz go za pomocą npm init
. Następnie zainstaluj pakiet firebase-admin
npm i zapisz go w package.json
:
npm install firebase-admin --save
Aby użyć modułu w swojej aplikacji, require
z dowolnego pliku JavaScript:
const { initializeApp } = require('firebase-admin/app');
Jeśli używasz ES2015, możesz import
moduł:
import { initializeApp } from 'firebase-admin/app';
Java
Pakiet SDK Firebase Admin Java jest publikowany w centralnym repozytorium Maven.
Aby zainstalować bibliotekę, zadeklaruj ją jako zależność w pliku build.gradle
:
dependencies {
implementation 'com.google.firebase:firebase-admin:9.4.1'
}
Jeśli do kompilowania aplikacji używasz Maven, możesz dodać do pliku pom.xml
tę zależność:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.4.1</version>
</dependency>
Python
Pakiet Firebase Admin Python SDK jest dostępny przez pip.
Możesz zainstalować bibliotekę dla wszystkich użytkowników za pomocą sudo
:
sudo pip install firebase-admin
Możesz też zainstalować bibliotekę tylko dla bieżącego użytkownika, przekazując flagę --user
:
pip install --user firebase-admin
Go
Go Admin SDK można zainstalować za pomocą narzędzia 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.0
C#
Bibliotekę .NET Admin SDK można zainstalować za pomocą menedżera pakietów .NET:
Install-Package FirebaseAdmin -Version 3.1.0
Możesz też zainstalować go za pomocą narzędzia wiersza poleceń dotnet
:
dotnet add package FirebaseAdmin --version 3.1.0
Możesz też zainstalować pakiet, dodając do pliku .csproj
ten wpis referencyjny pakietu:
<ItemGroup>
<PackageReference Include="FirebaseAdmin" Version="3.1.0" />
</ItemGroup>
Inicjowanie pakietu SDK
Po utworzeniu projektu Firebase możesz zainicjować pakiet SDK za pomocą domyślnych danych logowania do aplikacji Google. W środowiskach Google wyszukiwanie domyślnych danych logowania jest w pełni zautomatyzowane i nie trzeba podawać zmiennych środowiskowych ani innej konfiguracji, dlatego zdecydowanie zalecamy ten sposób inicjowania pakietu SDK w przypadku aplikacji działających w środowiskach Google, takich jak Cloud Run, App Engine i Cloud Functions.
Aby opcjonalnie określić opcje inicjalizacji usług takich jak Realtime Database, Cloud Storage lub Cloud Functions, użyj zmiennej środowiskowej FIREBASE_CONFIG
. Jeśli zawartość zmiennej FIREBASE_CONFIG
zaczyna się od {
, zostanie przeanalizowana jako obiekt JSON. W przeciwnym razie SDK zakłada, że ciąg znaków to ścieżka do pliku JSON zawierającego opcje.
Node.js
const app = initializeApp();
Java
FirebaseApp.initializeApp();
Python
default_app = firebase_admin.initialize_app()
Go
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
C#
FirebaseApp.Create();
Po zainicjowaniu możesz używać funkcji Admin SDK do wykonywania tych typów zadań:
- Implementowanie niestandardowego uwierzytelniania
- Zarządzanie użytkownikami Firebase Authentication
- Wykonywanie zapytań administracyjnych i mutacji w usłudze Firebase Data Connect.
- Odczytywanie i zapisywanie danych z Realtime Database
- Wyślij Firebase Cloud Messaging wiadomości
Korzystanie z tokena odświeżania OAuth 2.0
Admin SDK udostępnia też dane logowania, które umożliwiają uwierzytelnianie się za pomocą tokena odświeżania 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)
Go
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"),
});
Inicjowanie pakietu SDK w środowiskach innych niż Google
Jeśli pracujesz w środowisku serwera spoza Google, w którym wyszukiwanie domyślnych danych logowania nie może być w pełni zautomatyzowane, możesz zainicjować pakiet SDK za pomocą wyeksportowanego pliku klucza konta usługi.
.Projekty Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub zaufanego środowiska. Jeśli programujesz kod lokalnie lub wdrażasz aplikację lokalnie, możesz autoryzować żądania do serwera za pomocą danych logowania uzyskanych z tego konta usługi.
Aby uwierzytelnić konto usługi i zezwolić mu na dostęp do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.
Aby wygenerować plik klucza prywatnego dla konta usługi:
W konsoli Firebase otwórz Ustawienia > Konta usługi.
Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.
Bezpiecznie przechowuj plik JSON zawierający klucz.
Podczas autoryzacji za pomocą konta usługi masz 2 możliwości przekazania danych logowania do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub bezpośrednio przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.
Aby ustawić zmienną środowiskową:
Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi. Ta zmienna dotyczy tylko bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, musisz ponownie ustawić zmienną.
Linux lub macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
Za pomocą PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
Po wykonaniu powyższych czynności aplikacja domyślne dane logowania (ADC) może domyślnie określić Twoje dane logowania, co pozwoli Ci używać danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.
Zainicjuj pakiet SDK w ten sposób:
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()
Go
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",
});
Inicjowanie wielu aplikacji
W większości przypadków wystarczy zainicjować jedną aplikację domyślną. Dostęp do usług z tej aplikacji możesz uzyskać na 2 sposoby:
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(...)
Go
// 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;
W niektórych przypadkach musisz utworzyć kilka aplikacji jednocześnie. Możesz na przykład odczytać dane z Realtime Database jednego projektu Firebase i wyemitować tokeny niestandardowe dla innego projektu. Możesz też chcieć uwierzytelniać 2 aplikacje za pomocą osobnych danych logowania. Pakiet SDK Firebase umożliwia tworzenie wielu aplikacji jednocześnie, z własnymi informacjami konfiguracyjnymi.
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)
Go
// 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);
Ustaw zakresy dostępu dla usług Realtime Database i Authentication
Jeśli używasz maszyny wirtualnej Google Compute Engine z domyślnymi danymi logowania Google Application Default Realtime Database lub Authentication, pamiętaj, aby ustawić też odpowiednie zakresy dostępu.
W przypadku Realtime Database i Authentication musisz ustawić zakresy userinfo.email
i cloud-platform
lub cloud-platform
lub firebase.database
. Aby sprawdzić i zmienić istniejące zakresy dostępu, uruchom te polecenia za pomocą 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"
Testowanie za pomocą danych logowania użytkownika gcloud
Podczas testowania usługi Admin SDK lokalnie przy użyciu domyślnych danych logowania do aplikacji Google uzyskanych przez uruchomienie gcloud auth application-default login
konieczne są dodatkowe zmiany, aby można było używać usługi Firebase Authentication. Wynika to z tego, że:
- Firebase Authentication nie akceptuje danych logowania użytkownika gcloud wygenerowanych za pomocą identyfikatora klienta OAuth w gcloud.
- Firebase Authentication wymaga podania identyfikatora projektu podczas inicjalizacji w przypadku tego typu danych logowania użytkownika.
Aby obejść ten problem, możesz wygenerować domyślne dane logowania aplikacji Google w gcloud przy użyciu własnego identyfikatora klienta OAuth 2.0. Identyfikator klienta OAuth musi być typem aplikacji Aplikacja na komputer.
gcloud
gcloud auth application-default login --client-id-file=[/path/to/client/id/file]
Identyfikator projektu możesz podać w sposób jawny podczas inicjalizacji aplikacji lub użyć zmiennej środowiskowej GOOGLE_CLOUD_PROJECT
. W tym drugim przypadku nie trzeba wprowadzać żadnych dodatkowych zmian, aby przetestować kod.
Aby wyraźnie określić identyfikator projektu:
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)
Go
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>",
});
Dalsze kroki
Więcej informacji o Firebase:
Zapoznaj się z przykładowymi aplikacjami Firebase.
Zapoznaj się z kodem open source na GitHubie dla Node.js, Java i Python.
Przeczytaj posty na blogu związane z Admin SDK, które napisał jeden z twórców Admin SDK. Na przykład: dostęp do Firestore i Firebase przez serwer proxy.
Dodaj do aplikacji funkcje Firebase:
- Zapisz bezserwerowy backend za pomocą Cloud Functions.
- Przechowuj informacje za pomocą Realtime Database lub danych blob w Cloud Storage.
- otrzymywać powiadomienia z urządzenia Cloud Messaging,