将 Firebase Admin SDK 添加到您的服务器

通过 Admin SDK,您可以从特权环境与 Firebase 进行交互,以执行以下操作:

  • 以完整的管理员权限读写实时数据库数据。
  • 使用简单的替代方法以编程方式将 Firebase 云消息传递消息发送至 FCM 服务器协议。
  • 生成并验证 Firebase 身份验证令牌。
  • 访问 Google Cloud Platform 资源,例如与您的 Firebase 项目相关联的 Cloud Storage 存储分区和 Firestore 数据库。
  • 创建您自己的简化管理控制台,以执行查询用户数据或更改用户用于身份验证的电子邮件地址等操作。

如果您希望将 Node.js SDK 用作面向最终用户的客户端(例如,在 Node.js 桌面应用或 IoT 应用中),而不是用于在特权环境(如服务器)中供管理员访问,则应该按照设置客户端 JavaScript SDK 的说明进行操作。

以下功能矩阵展示了每种语言支持哪些 Firebase 功能:

功能 Node.js Java Python Go
自定义令牌创建
ID 令牌验证
用户管理
使用自定义声明控制访问
刷新令牌撤消
导入用户
会话 Cookie 管理
实时数据库 * *
云消息传递
管理主题订阅
Cloud Storage
Cloud Firestore

要详细了解用于这些用途的 Admin SDK 集成,请参阅相应的实时数据库FCM身份验证Cloud Storage 文档。本页面的其余部分重点介绍 Admin SDK 的基本设置。

前提条件

在开始之前,请确保满足以下条件:

  • 如果使用 Admin Node.js SDK,则服务器必须运行 Node.js 4.0+
  • 如果使用 Admin Java SDK,则服务器必须运行 Java 7+
  • 如果使用 Admin Python SDK,则服务器必须运行 Python 2.7+ 或 3.x
  • 如果使用 Admin Go SDK,则服务器必须运行 Go 1.6+
  • 一个服务器应用

将 Firebase 添加至您的应用

要使用 Firebase Admin SDK,您需要一个 Firebase 项目、一个与 Firebase 服务通信的服务帐号,以及一个含有您的服务帐号凭据的配置文件。

  1. 如果您还没有 Firebase 项目,请在 Firebase 控制台中添加一个项目。添加项目对话框还为您提供了将 Firebase 添加到已有 Google Cloud Platform 项目中的选项。
  2. 转到您项目的设置页面中的服务帐号标签。
  3. 点击位于服务帐号标签中 Firebase Admin SDK 部分底部的生成新的私钥按钮。

点击该按钮后,系统会下载一个包含您的服务帐号凭据的 JSON 文件。您在下一步初始化 SDK 时需要用到此文件。

此文件仅生成一次。如果该密钥丢失或泄漏,您可以按照上述说明重新为服务帐号创建一个新的 JSON 密钥。

添加 SDK

如果您正在设置新项目,则需要安装所选语言的 SDK。

Node.js

Firebase Admin Node.js SDK 可从 npm 上获得。如果您还没有 package.json 文件,可通过 npm init 创建一个。接下来,安装 firebase-admin npm 软件包并将其保存到您的 package.json 中:

$ npm install firebase-admin --save

要在应用中使用该模块,您可以在任何 JavaScript 文件中 require 它:

var admin = require('firebase-admin');

如果您使用的是 ES2015,则可以改为 import 该模块:

import * as admin from 'firebase-admin';

Java

Firebase Admin Java SDK 已发布至 Maven 中央代码库。要安装该库,请在您的 build.gradle 文件中将其声明为依赖项:

dependencies {
  compile 'com.google.firebase:firebase-admin:5.9.0'
}

如果您使用 Maven 来构建应用,则可以向您的 pom.xml 中添加以下依赖项:

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

Python

Firebase Admin Python SDK 可通过 pip 获得。您可以通过 sudo 为所有用户安装库:

$ sudo pip install firebase-admin

或者,您可以通过传递 --user 标记仅为当前用户安装库:

$ pip install --user firebase-admin

Go

您可以使用 go get 实用程序安装 Go Admin SDK:

$ go get firebase.google.com/go

初始化 SDK

创建一个 Firebase 控制台项目并下载了一个包含您的服务帐号凭据的 JSON 文件后,就可以使用以下这段代码来初始化 SDK:

Node.js

var admin = require('firebase-admin');

var serviceAccount = require('path/to/serviceAccountKey.json');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FileInputStream serviceAccount = new FileInputStream("path/to/serviceAccountKey.json");

FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

import firebase_admin
from firebase_admin import credentials

cred = credentials.Certificate('path/to/serviceAccountKey.json')
default_app = firebase_admin.initialize_app(cred)

要在 Google App Engine 标准环境中使用 Python Admin SDK,您需要进行一些额外配置

Go

import (
	"log"

	"golang.org/x/net/context"

	firebase "firebase.google.com/go"
	"firebase.google.com/go/auth"

	"google.golang.org/api/option"
)

opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")
app, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

您可以在 Firebase 控制台项目的 Database(数据库)页面上找到您的数据库名称。

例如,如果无法引用服务帐号文件,那么 Admin Node.js SDK 可以通过直接嵌入代码的方式来接受服务帐号的各个字段:

Node.js

admin.initializeApp({
  credential: admin.credential.cert({
    projectId: '<PROJECT_ID>',
    clientEmail: 'foo@<PROJECT_ID>.iam.gserviceaccount.com',
    privateKey: '-----BEGIN PRIVATE KEY-----\n<KEY>\n-----END PRIVATE KEY-----\n'
  }),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

或者,Admin SDK 可以使用其他凭据类型进行身份验证。例如,如果您在 Google Cloud Platform 中运行自己的代码,则可以利用 Google 应用默认凭据让 Admin SDK 自行代表您获取服务帐号:

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FirebaseOptions options = new 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)
}

如果您将 Google Compute Engine VM 与 Google 应用默认凭据一起用于实时数据库或身份验证,请确保您还设置了正确的访问权限范围。对于实时数据库和身份验证,访问权限范围应以 userinfo.email 以及 cloud-platformfirebase.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"

如果您是在 Cloud Functions 函数中使用 Node.js Admin SDK,则可以通过 functions.config() 变量自动初始化此 SDK:

Node.js

admin.initializeApp(functions.config().firebase);

Admin SDK 还提供一个凭据,允许您使用 Google OAuth2 刷新令牌进行身份验证:

Node.js

var refreshToken; // Get refresh token from OAuth2 flow

admin.initializeApp({
  credential: admin.credential.refreshToken(refreshToken),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

Java

FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");

FirebaseOptions options = new 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)
}

该 SDK 也可以在不使用参数的情况下进行初始化。在这种情况下,该 SDK 使用 Google 应用默认凭据并从 FIREBASE_CONFIG 环境变量中读取选项。如果 FIREBASE_CONFIG 变量的内容以一个 { 开头,则会被解析为一个 JSON 对象。如果不是以该字符开头,则 SDK 会假定该字符串是包含选项的 JSON 文件的名称。

Node.js

// Initialize the default app
var admin = require('firebase-admin');
var app = admin.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)
}

您现在可以使用 Firebase Admin SDK 完成以下任务:

初始化多个应用

在大多数情况下,您只需要初始化一个默认应用。您可以通过两种等效的方式利用该应用访问各项服务:

Node.js

// Initialize the default app
var defaultApp = admin.initializeApp(defaultAppConfig);

console.log(defaultApp.name);  // '[DEFAULT]'

// Retrieve services via the defaultApp variable...
var defaultAuth = defaultApp.auth();
var defaultDatabase = defaultApp.database();

// ... or use the equivalent shorthand notation
defaultAuth = admin.auth();
defaultDatabase = admin.database();

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

有些使用情形需要您同时创建多个应用。例如,您可能需要从一个 Firebase 项目的实时数据库中读取数据,并为另一个项目创建自定义令牌。或者,您可能想要使用单独的凭据对两个应用进行身份验证。借助 Firebase SDK,您可以同时创建多个应用,每个都有自己的配置信息。

Node.js

// Initialize the default app
admin.initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = admin.initializeApp(otherAppConfig, 'other');

console.log(admin.app().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = admin.auth();
var defaultDatabase = admin.database();

// Use the otherApp variable to retrieve the other app's services
var otherAuth = otherApp.auth();
var otherDatabase = otherApp.database();

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

后续步骤

了解 Firebase:

向您的应用添加 Firebase 功能:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面