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 的任何服務) 同時開發這些程式碼。
在您打算呼叫產生的管理員 SDK 的任何位置,將 Node.js 的 Admin SDK 納入為依附元件。
產生 Admin SDK
建立 SQL Connect 結構定義、查詢和異動後,即可產生對應的 Admin SDK:
開啟或建立
connector.yaml檔案,並新增adminNodeSdk定義:connectorId: default generate: adminNodeSdk: outputDir: ../../dataconnect-generated/admin-generated package: "@dataconnect/admin-generated" packageJsonDir: ../..connector.yaml檔案通常與 GraphQL (.gql) 檔案位於同一目錄,其中包含查詢和變異定義。如果您已產生用戶端 SDK,系統會建立這個檔案。產生 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) 指令定義。這樣做可確保只有管理員層級的呼叫端可以執行這些作業。