Admin SDK to zestaw bibliotek serwera, który umożliwia interakcję z Firebase z prywatnych środowisk w celu wykonywania takich działań jak:
- Wykonywanie zapytań i mutacji w usłudze Firebase Data Connect w celu zarządzania zbiorczymi danymi i innych operacji z pełnymi uprawnieniami administratora.
- Odczytywanie i zapisywanie danych Realtime Database z pełnymi uprawnieniami administratora.
- Wysyłanie wiadomości Firebase Cloud Messaging za pomocą prostych, alternatywnych metod niż protokoły serwera Firebase Cloud Messaging.
- generować i weryfikować tokeny uwierzytelniania Firebase.
- Uzyskiwać dostęp do zasobów Google Cloud, takich jak zbiory 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, która pokazuje, które funkcje Firebase są obsługiwane 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 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 18+
- Admin Java SDK – Java 8+
- 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 SDK Admin Go – Go 1.21 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.
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 aplikacji, require
go 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 SDK na potrzeby Pythona jest dostępny za pomocą pip.
Bibliotekę możesz zainstalować dla wszystkich użytkowników za pomocą sudo
:
sudo pip install firebase-admin
Możesz też zainstalować bibliotekę tylko dla bieżącego użytkownika, podają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ć je 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, więc nie trzeba podawać zmiennych środowiskowych ani konfigurować innych ustawień. W przypadku aplikacji działających w środowiskach Google, takich jak Cloud Run, App Engine czy Cloud Functions, zdecydowanie zalecamy inicjowanie pakietu SDK w ten sposób.
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
- Wykonywać zapytania administracyjne i mutacje dotyczące usługi Firebase Data Connect.
- Odczytywanie i zapisywanie danych z Realtime Database
- Wysyłanie wiadomości Firebase Cloud Messaging
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 z zaufanego środowiska. Jeśli kod tworzysz lokalnie lub wdrażasz aplikację lokalnie, możesz użyć danych logowania uzyskanych za pomocą tego konta usługi, aby autoryzować żądania serwera.
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 w kodzie wyraźnie podać ścieżkę do klucza konta usługi. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.
Aby ustawić zmienną środowiskową:
Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do 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
W 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 mieć zakresy kończące się na userinfo.email
i 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 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, używając 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 za pomocą Cloud Storage.
- otrzymywać powiadomienia z urządzenia Cloud Messaging,