Menggunakan Admin SDK yang dibuat

Dengan SDK admin Firebase Data Connect, Anda dapat memanggil kueri dan mutasi dari lingkungan tepercaya seperti Cloud Functions, backend kustom, atau workstation Anda sendiri. Dengan cara yang hampir sama seperti saat Anda membuat SDK untuk aplikasi klien, Anda dapat membuat SDK admin kustom secara paralel saat mendesain skema, kueri, dan mutasi yang Anda deploy ke layanan Data Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika backend atau skrip administrasi.

Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa kueri dan mutasi Data Connect tidak dikirimkan oleh klien pada saat permintaan. Sebagai gantinya, saat di-deploy, operasi Data Connect disimpan di server seperti Cloud Functions. Artinya, setiap kali men-deploy perubahan pada kueri dan mutasi, Anda juga perlu membuat ulang SDK admin dan men-deploy ulang layanan apa pun yang mengandalkannya.

Sebelum memulai

Membuat Admin SDK

Setelah membuat skema, kueri, dan mutasi Data Connect, Anda dapat membuat SDK admin yang sesuai:

  1. Buka atau buat file connector.yaml dan tambahkan definisi adminNodeSdk:

    connectorId: default
generate:
  adminNodeSdk:
    outputDir: ../../dataconnect-generated/admin-generated
    package: "@dataconnect/admin-generated"
    packageJsonDir: ../..

    File connector.yaml biasanya ditemukan di direktori yang sama dengan file GraphQL (.gql) yang berisi definisi kueri dan mutasi Anda. Jika Anda telah membuat SDK klien, file ini sudah dibuat.

  2. Buat SDK.

    Jika Anda telah menginstal ekstensi Data Connect VS Code, ekstensi tersebut akan selalu memperbarui SDK yang dihasilkan.

    Atau, gunakan Firebase CLI:

    firebase dataconnect:sdk:generate

    Atau, untuk membuat ulang SDK secara otomatis saat Anda memperbarui file gql:

    firebase dataconnect:sdk:generate --watch

Menjalankan operasi dari Admin SDK

Admin SDK yang dihasilkan berisi antarmuka dan fungsi yang sesuai dengan definisi gql Anda, yang dapat Anda gunakan untuk melakukan operasi pada database Anda. Misalnya, Anda membuat SDK untuk database lagu, beserta kueri, getSongs:

import { initializeApp } from "firebase-admin/app";
import { getSongs } from "@dataconnect/admin-generated";

const adminApp = initializeApp();

const songs = await getSongs(
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

Atau, untuk menentukan konfigurasi konektor:

import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import {
  connectorConfig,
  getSongs,
} from "@dataconnect/admin-generated";

const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);

const songs = await getSongs(
  adminDc,
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

Meniru identitas pengguna yang tidak diautentikasi

Admin SDK dimaksudkan untuk dijalankan dari lingkungan tepercaya, dan oleh karena itu memiliki akses tidak terbatas ke database Anda.

Saat menjalankan operasi publik dengan Admin SDK, Anda harus menghindari menjalankan operasi dengan hak istimewa administrator penuh (mengikuti prinsip hak istimewa terendah). Sebagai gantinya, Anda harus menjalankan operasi sebagai pengguna yang di-impersonate (lihat bagian berikutnya), atau sebagai pengguna tidak terautentikasi yang di-impersonate. Pengguna yang tidak diautentikasi hanya dapat menjalankan operasi yang ditandai sebagai PUBLIC.

Dalam contoh di atas, kueri getSongs dijalankan sebagai pengguna yang tidak diautentikasi.

Meniru identitas pengguna

Anda juga dapat melakukan operasi atas nama pengguna tertentu dengan meneruskan sebagian atau seluruh token Firebase Authentication dalam opsi impersonate; minimal, Anda harus menentukan ID pengguna di sub-klaim. (Nilai ini sama dengan nilai server auth.uid yang dapat Anda rujuk dalam operasi GraphQL Data Connect.)

Saat Anda meniru identitas pengguna, operasi hanya akan berhasil jika data pengguna yang Anda berikan lulus pemeriksaan autentikasi yang ditentukan dalam definisi GraphQL Anda.

Jika Anda memanggil SDK yang dihasilkan dari endpoint yang dapat diakses secara publik, endpoint tersebut harus memerlukan autentikasi dan Anda harus memvalidasi integritas token autentikasi sebelum menggunakannya untuk meniru identitas pengguna.

Saat menggunakan Cloud Functions yang dapat dipanggil, token autentikasi akan diverifikasi secara otomatis dan Anda dapat menggunakannya seperti dalam contoh berikut:

import { HttpsError, onCall } from "firebase-functions/https";

export const callableExample = onCall(async (req) => {
    const authClaims = req.auth?.token;
    if (!authClaims) {
        throw new HttpsError("unauthenticated", "Unauthorized");
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Jika tidak, gunakan metode verifyIdToken dari Admin SDK untuk memvalidasi dan mendekode token autentikasi. Misalnya, endpoint Anda diimplementasikan sebagai fungsi HTTP biasa dan Anda telah meneruskan token Firebase Authentication ke endpoint menggunakan header authorization, seperti standar:

import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";

const auth = getAuth();

export const httpExample = onRequest(async (req, res) => {
    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
    if (!token) {
        res.sendStatus(401);
        return;
    }
    let authClaims;
    try {
        authClaims = await auth.verifyIdToken(token);
    } catch {
        res.sendStatus(401);
        return;
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Hanya saat melakukan tugas administratif yang sebenarnya, seperti migrasi data, dari lingkungan yang aman dan tidak dapat diakses secara publik, Anda harus menentukan ID pengguna yang tidak berasal dari sumber yang dapat diverifikasi:

// Never do this if end users can initiate execution of the code!
const favoriteSongs = await getMyFavoriteSongs(
  undefined,
  { impersonate: { authClaims } }
);

Menjalankan dengan akses tidak terbatas

Jika Anda melakukan operasi yang memerlukan izin tingkat admin, hapus parameter peniruan identitas dari panggilan:

await upsertSong(adminDc, {
  title: songTitle_one,
  instrumentsUsed: [Instrument.VOCAL],
});

Operasi yang dipanggil dengan cara ini memiliki akses penuh ke database. Jika Anda memiliki kueri atau mutasi yang hanya dimaksudkan untuk digunakan untuk tujuan administrasi, Anda harus menentukannya dengan direktif @auth(level: NO_ACCESS). Dengan demikian, hanya pemanggil tingkat admin yang dapat menjalankan operasi ini.