Dodawanie pakietu Firebase Admin SDK do serwera

Admin SDK to zestaw bibliotek serwera, które umożliwiają interakcję z Firebase z uprzywilejowanych środowisk w celu wykonywania takich działań jak:

  • Wykonywanie zapytań i mutacji w usłudze Firebase SQL Connect na potrzeby zbiorczego zarządzania danymi i innych operacji z pełnymi uprawnieniami administratora.
  • Odczytywanie i zapisywanie danych Realtime Database z pełnymi uprawnieniami administratora.
  • Wysyłaj wiadomości Firebase Cloud Messaging automatycznie, korzystając z prostego, alternatywnego podejścia do protokołów serwera Firebase Cloud Messaging.
  • Generowanie i weryfikowanie tokenów uwierzytelniania Firebase.
  • Uzyskaj dostęp do zasobów Google Cloud, takich jak zasobniki Cloud Storage i bazy danych Cloud Firestore powiązane z Twoimi projektami w 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 dostępu użytkownika (np. w aplikacji Node.js na komputer lub IoT), a nie dostępu administracyjnego z uprzywilejowanego środowiska (np. serwera), postępuj zgodnie z instrukcjami konfigurowania pakietu JavaScript SDK klienta.

Oto tabela funkcji Firebase obsługiwanych w poszczególnych językach:

Funkcja Node.js Java Python Go C# Dart 
Generowanie tokenów niestandardowych
Weryfikacja tokena identyfikacji
Zarządzanie użytkownikami
Kontrola dostępu za pomocą niestandardowych oświadczeń
Unieważnianie tokena odświeżania
Importowanie użytkowników
Zarządzanie plikami cookie sesji
Generowanie linków do działań w e-mailach
Zarządzanie konfiguracjami dostawców SAML/OIDC
Obsługa wielu najemców
Firebase SQL Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
Zarządzaj subskrypcjami tematów FCM
Cloud Storage
Cloud Firestore
Dodawanie funkcji do kolejki za pomocą Cloud Tasks
Zarządzanie projektami
Reguły zabezpieczeń
Zarządzanie modelami ML
Firebase Remote Config
Firebase App Check
Firebase Extensions
Firebase Phone Number Verification

Więcej informacji o integracji Admin SDK w tych zastosowaniach znajdziesz w odpowiedniej dokumentacji: Realtime Database, FCM, Authentication, Remote Config i Cloud Storage. W dalszej części tej strony skupimy się na podstawowej konfiguracji Admin SDK.

Wymagania wstępne

  • Upewnij się, że masz aplikację serwera.

  • Upewnij się, że na serwerze działa odpowiednia wersja Admin SDK:

    • Admin Node.js SDK – Node.js 22+
    • Admin Java SDK – Java 8 lub nowsza
    • Pakiet Admin Python SDK – Python 3.9 lub nowszy (zalecamy Pythona 3.10 lub nowszego)
      Obsługa Pythona 3.9 została wycofana.
    • Pakiet Admin Go SDK – Go 1.25 lub nowszy
    • Admin .NET SDK – .NET Framework 4.6.2 lub nowszy, .NET Standard 2.0 lub .NET 6.0 lub nowszy (zalecany .NET 8.0 lub nowszy)
      Obsługa .NET 6.0 i 7.0 została wycofana.
    • Eksperymentalny pakiet Admin Dart SDK – upewnij się, że na serwerze działa pakiet Dart SDK w wersji 3.9 lub nowszej.

Konfigurowanie projektu w Firebase i konta usługi

Aby korzystać z Firebase Admin SDK, musisz mieć:

  • Projekt w 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 w Firebase, musisz go utworzyć w konsoli Firebase. Więcej informacji o projektach w Firebase znajdziesz w artykule Informacje o projektach w Firebase.

Dodawanie SDK

Jeśli konfigurujesz nowy projekt, musisz zainstalować pakiet SDK dla wybranego języka.

Node.js

Pakiet SDK Firebase Admin 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 npm firebase-admin i zapisz go w pliku 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 Firebase Admin Java SDK 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.11.0'
}

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.11.0</version>
</dependency>

Python

Pakiet Firebase Admin Python SDK jest dostępny za pomocą 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

Pakiet Admin SDK dla Go 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.22.0

C#

Bibliotekę .NET Admin SDK można zainstalować za pomocą systemu zarządzania pakietami .NET:

Install-Package FirebaseAdmin -Version 3.7.0

Możesz też zainstalować go za pomocą narzędzia wiersza poleceń dotnet:

dotnet add package FirebaseAdmin --version 3.7.0

Możesz też zainstalować go, dodając do pliku .csproj ten wpis odwołania do pakietu:

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.7.0" />
</ItemGroup>

Dart (eksperymentalny)

dart pub add firebase_admin_sdk

Aby użyć modułu w aplikacji, zaimportuj go w ten sposób:

import 'package:firebase_admin_sdk';

// Also import the separate Firestore package if you're interacting with Firestore.
import 'package:google_cloud_firestore/google_cloud_firestore.dart';

Inicjowanie pakietu SDK

Po utworzeniu projektu w Firebase możesz zainicjować pakiet SDK za pomocą domyślnego uwierzytelniania aplikacji Google. Ponieważ wyszukiwanie domyślnych danych uwierzytelniających jest w pełni zautomatyzowane w środowiskach Google i nie wymaga podawania zmiennych środowiskowych ani innych konfiguracji, ten sposób inicjowania pakietu SDK jest zdecydowanie zalecany w przypadku aplikacji działających w środowiskach Google, takich jak Firebase App Hosting, Cloud Run, App Engine i Cloud Functions for Firebase.

Aby opcjonalnie określić opcje inicjowania 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 ona przeanalizowana jako obiekt JSON. W przeciwnym razie pakiet SDK zakłada, że ciąg znaków jest ścieżką 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();

Dart (eksperymentalny)

final admin = FirebaseApp.initializeApp();

Po zainicjowaniu możesz używać Admin SDK do wykonywania tych typów zadań:

Korzystanie z tokena odświeżania OAuth 2.0

Admin SDK udostępnia też dane uwierzytelniające, które umożliwiają uwierzytelnianie 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 = CredentialFactory.FromFile<UserCredential>("path/to/refreshToken.json").ToGoogleCredential(),
});

Inicjowanie pakietu SDK w środowiskach innych niż Google

Jeśli pracujesz w środowisku serwera innego niż Google, w którym nie można w pełni zautomatyzować wyszukiwania domyślnych danych logowania, możesz zainicjować pakiet SDK za pomocą wyeksportowanego pliku klucza konta usługi.

Projekty w Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów Firebase Server API z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz używać danych logowania uzyskanych za pomocą tego konta usługi do autoryzowania żądań serwera.

Wszystkie konta usługi w projekcie Firebase możesz wyświetlić na karcie Ustawienia > Konta usługi.

Aby uwierzytelnić konto usługi i autoryzować je do korzystania z usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

Aby wygenerować plik klucza prywatnego dla konta usługi:

  1. W konsoli Firebase otwórz kartę Ustawienia > Konta usługi.

  2. Kliknij Wygeneruj nowy klucz prywatny, a następnie potwierdź, klikając Wygeneruj klucz.

  3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pomocą konta usługi masz 2 możliwości podania 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ę, ustaw ją ponownie.

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 domyślne uwierzytelnianie aplikacji (ADC) może pośrednio określić Twoje dane logowania, co pozwala na używanie 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ą domyślną aplikację. Możesz uzyskać dostęp do usług z tej aplikacji na 2 równoważne 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;

Niektóre przypadki użycia wymagają utworzenia wielu aplikacji jednocześnie. Możesz na przykład odczytywać dane z Realtime Database jednego projektu Firebase i generować niestandardowe tokeny dla innego projektu. Możesz też uwierzytelnić 2 aplikacje za pomocą osobnych danych logowania. Pakiet SDK Firebase umożliwia jednoczesne tworzenie wielu aplikacji, z których każda ma własne informacje o konfiguracji.

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);

Ustawianie zakresów dla: Realtime Database i Authentication

Jeśli używasz maszyny wirtualnej Google Compute Engine z domyślnym uwierzytelnianiem aplikacji Google dla Realtime Database lub Authentication, pamiętaj, aby ustawić odpowiednie zakresy dostępu. W przypadku Realtime Database i Authentication potrzebujesz zakresów kończących się na userinfo.email oraz cloud-platform lub firebase.database. Aby sprawdzić istniejące zakresy dostępu i je zmienić, 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 z użyciem danych logowania użytkownika gcloud

Podczas testowania Admin SDK lokalnie z użyciem domyślnego uwierzytelniania aplikacji Google uzyskanego przez uruchomienie gcloud auth application-default login, aby używać Firebase Authentication, musisz wprowadzić dodatkowe zmiany z tych powodów:

  • Firebase Authentication nie akceptuje danych logowania użytkownika gcloud wygenerowanych przy użyciu identyfikatora klienta OAuth gcloud.
  • Firebase Authentication wymaga podania identyfikatora projektu podczas inicjowania tego typu danych logowania użytkownika.

Aby obejść ten problem, możesz wygenerować domyślne uwierzytelnianie aplikacji Google w gcloud przy użyciu własnego identyfikatora klienta OAuth 2.0. Identyfikator klienta OAuth musi być typu Aplikacja komputerowa.

gcloud

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

Możesz określić identyfikator projektu podczas inicjowania aplikacji lub po prostu użyć zmiennej środowiskowej GOOGLE_CLOUD_PROJECT. Dzięki temu nie musisz wprowadzać żadnych dodatkowych zmian, aby przetestować kod.

Aby jednoznacznie 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:

Dodaj do aplikacji funkcje Firebase: