使用產生的 Admin SDK

Firebase SQL Connect Admin SDK 可讓您從 Cloud Functions、自訂後端或自己的工作站等信任環境,呼叫查詢和變更。就像為用戶端應用程式產生 SDK 一樣,您也可以在設計要部署至 SQL Connect 服務的結構定義、查詢和修改作業時,同時產生自訂 Admin SDK。接著,將這個 SDK 的方法整合到後端邏輯或管理指令碼中。

如其他地方所述,請務必注意,用戶端不會在要求時提交 SQL Connect 查詢和變動。相反地,部署時,SQL Connect 作業會儲存在伺服器上,例如 Cloud Functions。這表示每當您部署查詢和修改作業的異動時,也需要重新產生 Admin SDK,並重新部署任何依賴這些 SDK 的服務。

事前準備

  • 瞭解如何設計 SQL Connect 結構定義、查詢和變異。在一般工作流程中,您會與應用程式程式碼 (包括使用 Admin SDK 的任何服務) 同時開發這些程式碼。
  • 安裝 Firebase CLI。

  • 在您打算呼叫產生的管理員 SDK 的任何位置,將 Node.js 的 Admin SDK 納入為依附元件。

產生 Admin SDK

建立 SQL Connect 結構定義、查詢和異動後,即可產生對應的 Admin SDK:

  1. 開啟或建立 connector.yaml 檔案,並新增 adminNodeSdk 定義:

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

    connector.yaml 檔案通常與 GraphQL (.gql) 檔案位於同一目錄,其中包含查詢和變異定義。如果您已產生用戶端 SDK,系統會建立這個檔案。

  2. 產生 SDK。

    如果已安裝 SQL Connect VS Code 擴充功能,系統會隨時更新產生的 SDK。

    否則,請使用 Firebase CLI:

    firebase dataconnect:sdk:generate

    或者,如要在更新 gql 檔案時自動重新產生 SDK,請按照下列步驟操作:

    firebase dataconnect:sdk:generate --watch

透過 Admin SDK 執行作業

產生的 Admin SDK 包含與 gql 定義對應的介面和函式,可用於對資料庫執行作業。舉例來說,假設您為歌曲資料庫生成 SDK,並附上查詢 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 } }
);

或者,如要指定連接器設定,請按照下列步驟操作:

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

冒用未經驗證的使用者

Admin SDK 應在受信任的環境中執行,因此可不受限制地存取資料庫。

使用 Admin SDK 執行公開作業時,請避免以完整管理員權限執行作業 (遵循最小權限原則)。您應該改為以模擬使用者 (請參閱下一節) 或模擬未經驗證的使用者身分執行作業。未經驗證的使用者只能執行標示為 PUBLIC 的作業。

在上述範例中,getSongs 查詢是以未經驗證的使用者身分執行。

模擬使用者

您也可以在 impersonate 選項中傳遞部分或全部 Firebase Authentication 權杖,代表特定使用者執行作業;您至少必須在 sub 宣告中指定使用者的使用者 ID。(這個值與您可在 SQL Connect GraphQL 作業中參照的 auth.uid 伺服器值相同)。

模擬使用者時,只有在您提供的使用者資料通過 GraphQL 定義中指定的身分驗證檢查時,作業才會成功。

如果您是從可公開存取的端點呼叫產生的 SDK,請務必確保端點需要驗證,且您必須先驗證驗證權杖的完整性,才能使用該權杖模擬使用者。

使用可呼叫的 Cloud Functions 時,系統會自動驗證驗證權杖,您可以按照下列範例使用:

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

    // ...
});

否則,請使用 Admin SDK 的 verifyIdToken 方法驗證及解碼驗證權杖。舉例來說,假設您的端點是以一般 HTTP 函式實作,且您已使用 authorization 標頭將 Firebase Authentication 權杖傳遞至端點,這是標準做法:

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

    // ...
});

只有在安全、非公開存取的環境中執行真正的管理工作 (例如資料遷移) 時,才應指定並非來自可驗證來源的使用者 ID:

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

執行時不受存取限制

如果您執行的作業需要管理員層級權限,請從呼叫中省略模擬參數:

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

以這種方式呼叫的作業可以完整存取資料庫。如果查詢或變異僅用於管理目的,請使用 @auth(level: NO_ACCESS) 指令定義。這樣做可確保只有管理員層級的呼叫端可以執行這些作業。