Sử dụng SDK dành cho quản trị viên với tính năng Kết nối dữ liệu

Firebase Admin SDK là một tập hợp các 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 thao tác như thực hiện truy vấn và đột biến trên một dịch vụ Firebase Data Connect để quản lý dữ liệu hàng loạt và các thao tác khác có đặc quyền nâng cao và thông tin đăng nhập được mạo danh.

Admin SDK cung cấp cho bạn một API để gọi các thao tác ở cả chế độ đọc/ghi và chỉ đọc. Với các thao tác chỉ đọc, bạn có thể yên tâm triển khai các chức năng quản trị mà không thể sửa đổi dữ liệu trong cơ sở dữ liệu của mình.

Thiết lập Admin SDK

Để bắt đầu sử dụng Firebase Data Connect trên máy chủ, trước tiên, bạn cần cài đặt và thiết lập Admin SDK cho Node.js.

Khởi chạy Admin SDK trong tập lệnh

Để khởi động SDK, hãy nhập các tiện ích Data Connect và khai báo mã dịch vụ dự án cũng như vị trí của bạn.


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

Thiết kế các truy vấn và đột biến để sử dụng với Admin SDK

Admin SDK rất hữu ích khi kiểm thử các thao tác Data Connect, dựa trên những điểm cần cân nhắc sau.

Tìm hiểu về SDK và chỉ thị hoạt động @auth(level: NO_ACCESS)

Vì Admin SDK hoạt động với các đặc quyền, nên nó có thể thực thi mọi truy vấn và đột biến của bạn, bất kể cấp độ truy cập được đặt bằng cách sử dụng chỉ thị @auth, bao gồm cả cấp độ NO_ACCESS.

Nếu bên cạnh các thao tác của ứng dụng, bạn sắp xếp các truy vấn và đột biến hành chính trong tệp nguồn .gql để nhập vào các tập lệnh hành chính, thì Firebase đề xuất bạn đánh dấu các thao tác hành chính mà không có cấp độ truy cập uỷ quyền nào, hoặc có thể rõ ràng hơn và đặt chúng thành NO_ACCESS. Dù bằng cách nào, điều này cũng ngăn các thao tác như vậy được thực thi từ các ứng dụng hoặc trong các bối cảnh không có đặc quyền khác.

Sử dụng SDK với trình mô phỏng Data Connect

Trong môi trường thử nghiệm và nguyên mẫu, bạn có thể thực hiện việc gieo dữ liệu và các thao tác khác trên dữ liệu cục bộ. Admin SDK giúp bạn đơn giản hoá quy trình làm việc vì bỏ qua việc xác thực và uỷ quyền cho các luồng cục bộ.

Firebase Admin SDK sẽ tự động kết nối với trình mô phỏng Data Connect khi bạn đặt biến môi trường DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Để biết thêm thông tin, hãy xem các bài viết sau:

Triển khai các trường hợp sử dụng phổ biến

Admin SDK được cung cấp cho các thao tác đặc quyền trên dữ liệu quan trọng của bạn.

Admin SDK cung cấp 2 giao diện:

  • Một giao diện chung cho hầu hết các thao tác đọc-ghi hoặc chỉ đọc, trong đó mã của bạn triển khai các truy vấn và đột biến, đồng thời truyền chúng đến phương thức executeGraphql đọc-ghi hoặc phương thức executeGraphqlRead chỉ đọc.
  • Một giao diện chuyên biệt cho các thao tác dữ liệu hàng loạt, thay vì các phương thức executeGraphql chung, giao diện này sẽ hiển thị các phương thức chuyên dụng cho các thao tác biến đổi: insert, insertMany, upsert và upsertMany.

Quản lý dữ liệu người dùng bằng các phương thức executeGraphql

Một trường hợp sử dụng điển hình cho Admin SDK là quản lý dữ liệu người dùng.

Sử dụng thông tin đăng nhập của quản trị viên

Cách đơn giản nhất là truy cập vào dữ liệu người dùng bằng thông tin đăng nhập của quản trị viên.

// 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" } } }

Nhập vai thông tin đăng nhập của người dùng

Ngoài ra, có những trường hợp sử dụng mà bạn muốn tập lệnh của mình sửa đổi dữ liệu người dùng dựa trên thông tin đăng nhập hạn chế, thay mặt cho một người dùng cụ thể. Phương pháp này tuân theo nguyên tắc về đặc quyền tối thiểu.

Để sử dụng giao diện này, hãy thu thập thông tin từ một mã thông báo uỷ quyền JWT tuỳ chỉnh tuân theo định dạng mã thông báo Authentication. Ngoài ra, hãy xem hướng dẫn về mã thông báo tuỳ chỉnh.

// 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" } } }

Quản lý dữ liệu công khai bằng các phương thức executeGraphql

Bạn có thể làm việc với dữ liệu có thể truy cập công khai bằng SDK, mạo danh một người dùng chưa được xác thực.

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

Thực hiện các thao tác hàng loạt trên dữ liệu

Firebase khuyên bạn nên sử dụng Admin SDK cho các thao tác dữ liệu hàng loạt trên cơ sở dữ liệu sản xuất.

SDK cung cấp các phương thức sau để xử lý dữ liệu hàng loạt. Từ các đối số được cung cấp, mỗi phương thức sẽ tạo và thực thi một đột biến 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);

Lưu ý về hiệu suất đối với các thao tác hàng loạt

Mỗi yêu cầu gửi đến phần phụ trợ sẽ phát sinh một chuyến khứ hồi đến Cloud SQL, vì vậy, bạn càng xử lý hàng loạt thì thông lượng càng cao.

Tuy nhiên, kích thước lô càng lớn thì câu lệnh SQL được tạo càng dài. Khi đạt đến giới hạn độ dài câu lệnh SQL của PostgreSQL, bạn sẽ gặp lỗi.

Trong thực tế, hãy thử nghiệm để tìm ra kích thước lô phù hợp cho khối lượng công việc của bạn.

Tiếp theo là gì?