Thêm SDK quản trị của Firebase vào máy chủ

Admin SDK là một bộ thư viện máy chủ cho phép bạn tương tác với Firebase từ các môi trường đặc quyền để thực hiện các hành động như:

  • Thực hiện các truy vấn và đột biến trên dịch vụ Firebase SQL Connect để quản lý dữ liệu hàng loạt và các thao tác khác với đầy đủ đặc quyền của quản trị viên.
  • Đọc và ghi dữ liệu Realtime Database với đầy đủ đặc quyền của quản trị viên.
  • Gửi thông báo Firebase Cloud Messaging theo phương thức lập trình bằng một phương pháp đơn giản, thay thế cho các giao thức máy chủ Firebase Cloud Messaging.
  • Tạo và xác minh mã thông báo xác thực Firebase.
  • Truy cập vào các tài nguyên Google Cloud như bộ chứa Cloud Storage và cơ sở dữ liệu Cloud Firestore liên kết với các dự án Firebase của bạn.
  • Tạo bảng điều khiển quản trị đơn giản của riêng bạn để thực hiện những việc như tra cứu dữ liệu người dùng hoặc thay đổi địa chỉ email của người dùng để xác thực.

Nếu bạn muốn sử dụng SDK Node.js làm ứng dụng cho quyền truy cập của người dùng cuối (ví dụ: trong ứng dụng IoT hoặc ứng dụng Node.js cho máy tính), thay vì quyền quản trị từ một môi trường có đặc quyền (như máy chủ), thì bạn nên làm theo hướng dẫn thiết lập SDK JavaScript của ứng dụng.

Dưới đây là bảng tính năng cho biết các tính năng của Firebase được hỗ trợ trong từng ngôn ngữ:

Tính năng Node.js Java Python Bắt đầu C# Dart
Tạo mã thông báo tuỳ chỉnh
Xác minh mã thông báo nhận dạng
Quản lý người dùng
Kiểm soát quyền truy cập bằng thông tin xác nhận tuỳ chỉnh
Thu hồi mã làm mới
Nhập người dùng
Quản lý cookie của phiên
Tạo đường liên kết hành động trong email
Quản lý cấu hình của nhà cung cấp SAML/OIDC
Hỗ trợ nhiều đối tượng thuê
Firebase SQL Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
Quản lý FCM gói thuê bao chủ đề
Cloud Storage
Cloud Firestore
Thêm hàm vào hàng đợi bằng Cloud Tasks
Quản lý dự án
Quy tắc bảo mật
Quản lý mô hình học máy
Firebase Remote Config
Firebase App Check
Firebase Extensions
Firebase Phone Number Verification

Để tìm hiểu thêm về cách tích hợp Admin SDK cho những mục đích sử dụng này, hãy xem tài liệu tương ứng về Realtime Database, FCM, Authentication, Remote Config, và Cloud Storage. Phần còn lại của trang này tập trung vào việc thiết lập cơ bản cho Admin SDK.

Điều kiện tiên quyết

  • Đảm bảo rằng bạn có một ứng dụng máy chủ.

  • Đảm bảo rằng máy chủ của bạn chạy các lệnh sau, tuỳ thuộc vào Admin SDK mà bạn sử dụng:

    • Admin Node.js SDK — Node.js 22 trở lên
    • Admin Java SDK — Java 8 trở lên
    • Admin Python SDK — Python 3.9 trở lên (nên dùng Python 3.10 trở lên)
      Ngừng hỗ trợ Python 3.9.
    • Admin Go SDK — Go 1.25 trở lên
    • Admin .NET SDK — .NET Framework 4.6.2 trở lên hoặc .NET Standard 2.0 hoặc .NET 6.0 trở lên (nên dùng .NET 8.0 trở lên)
      Ngừng hỗ trợ .NET 6.0 và 7.0.
    • SDK Dart quản trị thử nghiệm – Đảm bảo rằng máy chủ của bạn chạy SDK Dart 3.9 trở lên.

Thiết lập dự án Firebase và tài khoản dịch vụ

Để sử dụng Firebase Admin SDK, bạn cần có:

  • Một dự án Firebase.
  • Tài khoản dịch vụ SDK của Firebase dành cho quản trị viên để giao tiếp với Firebase. Tài khoản dịch vụ này được tạo tự động khi bạn tạo một dự án Firebase hoặc thêm Firebase vào một dự án trên đám mây của Google.
  • Tệp cấu hình có thông tin xác thực của tài khoản dịch vụ.

Nếu chưa có dự án Firebase, bạn cần tạo một dự án trong bảng điều khiển của Firebase. Hãy truy cập vào bài viết Tìm hiểu về các dự án Firebase để tìm hiểu thêm về các dự án Firebase.

Thêm SDK

Nếu đang thiết lập một dự án mới, bạn cần cài đặt SDK cho ngôn ngữ mà bạn chọn.

Node.js

SDK Node.js của Firebase Admin có trên npm. Nếu bạn chưa có tệp package.json, hãy tạo một tệp thông qua npm init. Tiếp theo, hãy cài đặt gói npm firebase-admin và lưu gói đó vào package.json:

npm install firebase-admin --save

Để sử dụng mô-đun trong ứng dụng, hãy require mô-đun đó từ bất kỳ tệp JavaScript nào:

const { initializeApp } = require('firebase-admin/app');

Nếu đang sử dụng ES2015, bạn có thể import mô-đun:

import { initializeApp } from 'firebase-admin/app';

Java

Firebase Admin Java SDK được phát hành lên kho lưu trữ trung tâm Maven. Để cài đặt thư viện, hãy khai báo thư viện đó dưới dạng phần phụ thuộc trong tệp build.gradle:

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.11.0'
}

Nếu sử dụng Maven để xây dựng ứng dụng, bạn có thể thêm phần phụ thuộc sau vào pom.xml:

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.11.0</version>
</dependency>

Python

Bạn có thể sử dụng Firebase Admin Python SDK thông qua pip. Bạn có thể cài đặt thư viện cho tất cả người dùng thông qua sudo:

sudo pip install firebase-admin

Hoặc bạn có thể cài đặt thư viện chỉ cho người dùng hiện tại bằng cách truyền cờ --user:

pip install --user firebase-admin

Bắt đầu

Bạn có thể cài đặt Admin SDK Go bằng tiện ích 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#

Bạn có thể cài đặt Admin SDK .NET bằng trình quản lý gói .NET:

Install-Package FirebaseAdmin -Version 3.7.0

Ngoài ra, bạn có thể cài đặt bằng tiện ích dòng lệnh dotnet:

dotnet add package FirebaseAdmin --version 3.7.0

Hoặc bạn có thể cài đặt bằng cách thêm mục tham chiếu gói sau đây vào tệp .csproj:

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

Dart (thử nghiệm)

dart pub add firebase_admin_sdk

Để sử dụng mô-đun trong ứng dụng, hãy nhập mô-đun như sau:

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

Khởi chạy SDK

Sau khi tạo dự án Firebase, bạn có thể khởi động SDK bằng Thông tin xác thực mặc định của ứng dụng Google. Vì quy trình tra cứu thông tin xác thực mặc định hoàn toàn tự động trong môi trường Google, nên bạn không cần cung cấp biến môi trường hoặc cấu hình khác. Bạn nên sử dụng cách khởi chạy SDK này cho các ứng dụng chạy trong môi trường Google như Firebase App Hosting, Cloud Run, App Engine và Cloud Functions for Firebase.

Để chỉ định các tuỳ chọn khởi chạy cho các dịch vụ như Realtime Database, Cloud Storage hoặc Cloud Functions, hãy sử dụng biến môi trường FIREBASE_CONFIG. Nếu nội dung của biến FIREBASE_CONFIG bắt đầu bằng {, thì nội dung đó sẽ được phân tích cú pháp dưới dạng đối tượng JSON. Nếu không, SDK sẽ giả định rằng chuỗi này là đường dẫn của tệp JSON chứa các tuỳ chọn.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Bắt đầu

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create();

Dart (thử nghiệm)

final admin = FirebaseApp.initializeApp();

Sau khi khởi chạy, bạn có thể sử dụng Admin SDK để hoàn thành các loại tác vụ sau:

Sử dụng mã làm mới OAuth 2.0

Admin SDK cũng cung cấp thông tin xác thực cho phép bạn xác thực bằng mã làm mới 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)

Bắt đầu

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(),
});

Khởi chạy SDK trong môi trường không phải của Google

Nếu đang làm việc trong một môi trường máy chủ không phải của Google, nơi không thể tự động hoá hoàn toàn việc tra cứu thông tin xác thực mặc định, bạn có thể khởi chạy SDK bằng tệp khoá tài khoản dịch vụ đã xuất.

Dự án Firebase hỗ trợ tài khoản dịch vụ của Google. Bạn có thể dùng tài khoản này để gọi API máy chủ Firebase từ máy chủ ứng dụng hoặc môi trường đáng tin cậy. Nếu đang phát triển mã trên máy hoặc triển khai ứng dụng tại chỗ, bạn có thể sử dụng thông tin xác thực có được bằng tài khoản dịch vụ này để uỷ quyền cho các yêu cầu của máy chủ.

Bạn có thể xem tất cả tài khoản dịch vụ cho dự án Firebase của mình trong thẻ Cài đặt > Tài khoản dịch vụ.

Để xác thực tài khoản dịch vụ và cho phép tài khoản đó truy cập vào các dịch vụ của Firebase, bạn phải tạo một tệp khoá riêng tư ở định dạng JSON.

Cách tạo tệp khoá riêng tư cho tài khoản dịch vụ:

  1. Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Cài đặt > Tài khoản dịch vụ.

  2. Nhấp vào Tạo khoá riêng tư mới, sau đó xác nhận bằng cách nhấp vào Tạo khoá.

  3. Lưu trữ tệp JSON chứa khoá một cách an toàn.

Khi uỷ quyền thông qua tài khoản dịch vụ, bạn có hai lựa chọn để cung cấp thông tin xác thực cho ứng dụng của mình. Bạn có thể đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS hoặc truyền rõ ràng đường dẫn đến khoá tài khoản dịch vụ trong mã. Bạn nên chọn phương án đầu tiên vì phương án này an toàn hơn.

Cách đặt biến môi trường:

Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn tệp của tệp JSON chứa khoá tài khoản dịch vụ của bạn. Biến này chỉ áp dụng cho phiên shell hiện tại của bạn, vì vậy, nếu bạn mở một phiên mới, hãy đặt lại biến.

Linux hoặc macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Bằng PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Sau khi bạn hoàn tất các bước nêu trên, Thông tin xác thực mặc định của ứng dụng (ADC) có thể xác định thông tin đăng nhập của bạn một cách ngầm định, cho phép bạn sử dụng thông tin đăng nhập tài khoản dịch vụ khi thử nghiệm hoặc chạy trong môi trường không phải của Google.

Khởi chạy SDK như sau:

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

Bắt đầu

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",
});

Khởi chạy nhiều ứng dụng

Trong hầu hết các trường hợp, bạn chỉ phải khởi động một ứng dụng mặc định duy nhất. Bạn có thể truy cập vào các dịch vụ của ứng dụng đó theo hai cách tương đương:

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(...)

Bắt đầu

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

Một số trường hợp sử dụng yêu cầu bạn tạo nhiều ứng dụng cùng một lúc. Ví dụ: bạn có thể muốn đọc dữ liệu từ Realtime Database của một dự án Firebase và tạo mã thông báo tuỳ chỉnh cho một dự án khác. Hoặc bạn có thể muốn xác thực hai ứng dụng bằng thông tin xác thực riêng biệt. Firebase SDK cho phép bạn tạo nhiều ứng dụng cùng một lúc, mỗi ứng dụng có thông tin cấu hình riêng.

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)

Bắt đầu

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

Đặt phạm vi cho Realtime Database và Authentication

Nếu bạn đang sử dụng máy ảo Google Compute Engine có Thông tin xác thực mặc định của ứng dụng Google cho Realtime Database hoặc Authentication, hãy nhớ đặt cả phạm vi truy cập phù hợp. Đối với Realtime Database và Authentication, bạn cần có phạm vi kết thúc bằng userinfo.email và cloud-platform hoặc firebase.database. Để kiểm tra phạm vi truy cập hiện có và thay đổi phạm vi đó, hãy chạy các lệnh sau bằng 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"

Kiểm thử bằng thông tin đăng nhập của người dùng cuối gcloud

Khi kiểm thử Admin SDK cục bộ bằng Thông tin xác thực mặc định của ứng dụng Google có được bằng cách chạy gcloud auth application-default login, bạn cần thực hiện thêm các thay đổi để sử dụng Firebase Authentication vì những lý do sau:

  • Firebase Authentication không chấp nhận thông tin đăng nhập của người dùng cuối gcloud được tạo bằng mã ứng dụng khách OAuth gcloud.
  • Firebase Authentication yêu cầu cung cấp mã dự án khi khởi chạy cho các loại thông tin xác thực người dùng cuối này.

Để giải quyết vấn đề này, bạn có thể tạo Thông tin xác thực mặc định của ứng dụng Google trong gcloud bằng mã ứng dụng khách OAuth 2.0 của riêng bạn. Mã ứng dụng OAuth phải là loại ứng dụng Ứng dụng dành cho máy tính.

gcloud

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

Bạn có thể chỉ định rõ mã dự án khi khởi chạy ứng dụng hoặc chỉ cần sử dụng biến môi trường GOOGLE_CLOUD_PROJECT. Cách sau giúp bạn không cần thực hiện thêm bất kỳ thay đổi nào để kiểm thử mã.

Cách chỉ định rõ mã dự án:

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)

Bắt đầu

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>",
});

Các bước tiếp theo

Tìm hiểu về Firebase:

Thêm các tính năng của Firebase vào ứng dụng: