Menggunakan Admin SDK dengan Data Connect

Firebase Admin SDK adalah serangkaian library server yang dapat Anda gunakan untuk berinteraksi dengan Firebase dari lingkungan istimewa untuk melakukan berbagai tindakan, seperti melakukan kueri dan mutasi pada layanan Firebase Data Connect untuk pengelolaan data massal dan operasi lainnya dengan hak istimewa yang ditingkatkan dan kredensial yang di-impersonate.

Admin SDK memberi Anda API untuk memanggil operasi dalam mode baca/tulis dan hanya baca. Dengan operasi hanya baca, Anda dapat menerapkan fungsi administratif yang tidak dapat mengubah data di database Anda dengan tenang.

Penyiapan Admin SDK

Untuk mulai menggunakan Firebase Data Connect di server, Anda harus menginstal dan menyiapkan Admin SDK untuk Node.js terlebih dahulu.

Menginisialisasi Admin SDK dalam skrip Anda

Untuk melakukan inisialisasi SDK, impor ekstensi Data Connect dan deklarasikan ID layanan dan lokasi project Anda.


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

Mendesain kueri dan mutasi untuk digunakan dengan Admin SDK

Admin SDK berguna untuk menguji operasi Data Connect, mengingat pertimbangan berikut.

Memahami SDK dan direktif operasi @auth(level: NO_ACCESS)

Karena Admin SDK beroperasi dengan hak istimewa, Admin SDK dapat mengeksekusi kueri dan mutasi Anda terlepas dari tingkat akses yang ditetapkan menggunakan direktif @auth, termasuk tingkat NO_ACCESS.

Jika bersama dengan operasi klien, Anda mengatur kueri dan mutasi administratif di file sumber .gql untuk diimpor ke dalam skrip administratif, Firebase merekomendasikan agar Anda menandai operasi administratif tanpa tingkat akses otorisasi apa pun, atau mungkin lebih eksplisit dan menetapkannya sebagai NO_ACCESS. Bagaimanapun, hal ini mencegah operasi tersebut dijalankan dari klien atau dalam konteks non-hak istimewa lainnya.

Menggunakan SDK dengan emulator Data Connect

Di lingkungan prototipe dan pengujian, sebaiknya lakukan pengisian data dan operasi lainnya pada data lokal. Admin SDK memungkinkan Anda menyederhanakan alur kerja karena mengabaikan autentikasi dan otorisasi untuk alur lokal.

Firebase Admin SDK otomatis terhubung ke emulator Data Connect saat variabel lingkungan DATA_CONNECT_EMULATOR_HOST ditetapkan:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Untuk informasi selengkapnya, lihat:

Menerapkan kasus penggunaan umum

Admin SDK disediakan untuk operasi istimewa pada data penting Anda.

Admin SDK menyediakan dua antarmuka:

  • Antarmuka umum untuk sebagian besar operasi baca-tulis atau hanya baca, yang kode Anda mengimplementasikan kueri dan mutasi serta meneruskannya ke metode executeGraphql baca-tulis atau metode executeGraphqlRead hanya baca.
  • Antarmuka khusus untuk operasi data massal, yang bukan menggunakan metode executeGraphql umum, melainkan menampilkan metode khusus untuk operasi mutasi: insert, insertMany, upsert, dan upsertMany.

Mengelola data pengguna dengan metode executeGraphql

Kasus penggunaan umum untuk Admin SDK adalah mengelola data pengguna.

Menggunakan kredensial administratif

Pendekatan paling mudah adalah mengakses data pengguna menggunakan kredensial administratif.

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

Meniru identitas kredensial pengguna

Ada juga kasus penggunaan saat Anda ingin skrip mengubah data pengguna berdasarkan kredensial terbatas, atas nama pengguna tertentu. Pendekatan ini mematuhi prinsip hak istimewa terendah.

Untuk menggunakan antarmuka ini, kumpulkan informasi dari token autentikasi JWT yang disesuaikan yang mengikuti format token Authentication. Lihat juga panduan token kustom.

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

Mengelola data publik dengan metode executeGraphql

Anda dapat menggunakan data yang dapat diakses secara publik dengan SDK, meniru pengguna yang tidak diautentikasi.

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

Melakukan operasi data massal

Firebase merekomendasikan Anda menggunakan Admin SDK untuk operasi data massal di database produksi.

SDK menyediakan metode berikut untuk menangani data massal. Dari argumen yang diberikan, setiap metode membuat dan mengeksekusi mutasi 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);

Catatan performa untuk operasi massal

Setiap permintaan ke backend akan menimbulkan satu perjalanan pulang pergi ke Cloud SQL, sehingga semakin banyak yang Anda gabungkan, semakin tinggi throughput-nya.

Namun, makin besar ukuran batch, makin panjang pernyataan SQL yang dihasilkan. Jika batas panjang pernyataan SQL PostgreSQL tercapai, Anda akan mengalami error.

Dalam praktiknya, lakukan eksperimen untuk menemukan ukuran batch yang sesuai untuk beban kerja Anda.

Apa langkah selanjutnya?