将 Admin SDK 与 Data Connect 搭配使用

Firebase Admin SDK 是一组服务器库，让您可以从特权环境与 Firebase 进行交互，以执行以下操作：以提升的权限和模拟的凭据对 Firebase Data Connect 服务执行查询和变更操作，以便进行批量数据管理和其他操作。

Admin SDK 为您提供了一个 API，用于在读/写模式和只读模式下调用操作。借助只读操作，您可以放心地实现无法修改数据库中数据的管理功能。

Admin SDK 设置

如需开始在服务器上使用 Firebase Data Connect，您首先需要为 Node.js 安装并设置 Admin SDK。

在脚本中初始化 Admin SDK

如需初始化 SDK，请导入 Data Connect 扩展程序并声明您的项目服务 ID 和位置。


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

// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.

const app = initializeApp();

const dataConnect = getDataConnect({
    serviceId: 'serviceId',
    location: 'us-west2'
});

设计要与 Admin SDK 搭配使用的查询和变更

鉴于以下注意事项，Admin SDK 对于测试 Data Connect 操作非常有用。

了解 SDK 和 @auth(level: NO_ACCESS) 操作指令

由于 Admin SDK 以特权运行，因此无论使用 @auth 指令设置的访问权限级别如何，它都可以执行您的任何查询和突变，包括 NO_ACCESS 级别。

如果您在客户端操作之外，还会在 .gql 源文件中整理管理查询和突变，以便将其导入到管理脚本中，Firebase 建议您标记没有任何授权访问权限级别的管理操作，或者更明确地将其设置为 NO_ACCESS。无论哪种方式，这都能防止从客户端或在其他非特权上下文中执行此类操作。

将 SDK 与 Data Connect 模拟器搭配使用

在原型设计和测试环境中，对本地数据执行数据植入和其他操作可能很有用。借助 Admin SDK，您可以简化工作流程，因为它会忽略本地流程的身份验证和授权。

设置 DATA_CONNECT_EMULATOR_HOST 环境变量后，Firebase Admin SDK 会自动连接到 Data Connect 模拟器：

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

如需了解详情，请参阅以下主题：

实现常见使用场景

Admin SDK 用于对关键数据执行特权操作。

Admin SDK 提供了两个接口：

  • 适用于大多数读写或只读操作的常规接口，您的代码可在其中实现查询和突变，并将它们传递给读写 executeGraphql 方法或只读 executeGraphqlRead 方法。
  • 一种用于批量数据操作的专用接口，它不使用通用的 executeGraphql 方法，而是公开用于突变操作的专用方法：insert、insertMany、upsert 和 upsertMany。

使用 executeGraphql 方法管理用户数据

Admin SDK 的典型应用场景是管理用户数据。

使用管理员凭据

最直接的方法是使用管理员凭据访问用户数据。

// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";

interface UserData {
  user: {
    id: string;
    name: string;
  };
}

export interface UserVariables {
  id: string;
}

const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };

// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);

// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

模拟用户凭据

在某些使用情形下，您可能希望脚本代表特定用户，根据有限的凭据修改用户数据。这种方法遵循了最小权限原则。

如需使用此接口，请从遵循 Authentication 令牌格式的自定义 JWT 身份验证令牌中收集信息。另请参阅自定义令牌指南。

// Get the current user's data
const queryGetUserImpersonation = `
    query getUser @auth(level: USER) {
        user(key: {uid_expr: "auth.uid"}) {
            id,
            name
        }
    }`;

// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        authClaims: {
            sub: 'QVBJcy5ndXJ1'
        }
    }
};

// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

使用 executeGraphql 方法管理公开数据

您可以使用 SDK 模拟未经过身份验证的用户，从而处理可公开访问的数据。

// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
    query getPosts @auth(level: PUBLIC) {
        posts {
          description
        }
    }`;

// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        unauthenticated: true
    }
};

// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);

执行批量数据操作

Firebase 建议您使用 Admin SDK 对生产数据库执行批量数据操作。

该 SDK 提供了以下用于处理批量数据的方法。根据提供的实参，每种方法都会构建并执行 GraphQL 变更。


// Methods of the bulk operations API
// dc is a Data Connect admin instance from getDataConnect

const resp = await dc.insert("movie" /*table name*/, data[0]);
const resp = await dc.insertMany("movie" /*table name*/, data);
const resp = await dc.upsert("movie" /*table name*/, data[0]);
const resp = await dc.upsertMany("movie" /*table name*/, data);

批量操作的性能说明

每次向后端发出请求都会产生一次 Cloud SQL 往返，因此批处理越多，吞吐量就越高。

不过，批次大小越大，生成的 SQL 语句就越长。当达到 PostgreSQL SQL 语句长度限制时，您会遇到错误。

在实践中，请通过实验找到适合您工作负载的批次大小。

后续步骤