Firebase Data Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變異。您可以同時產生自訂用戶端 SDK,同時設計要部署至 Data Connect 服務的結構定義、查詢和變異。接著,您將整合此 SDK 的方法至用戶端邏輯。
如同我們在其他地方提到的,請務必注意 Data Connect 查詢和變異不會由用戶端程式提交,而是在伺服器上執行。相反地,部署 Data Connect 作業會在伺服器 (如 Cloud Functions) 中儲存。這表示您需要部署對應的用戶端變更,以免破壞現有使用者 (例如在舊版應用程式版本上)。
因此,Data Connect 提供開發人員環境和工具,讓您製作伺服器部署的結構定義、查詢和變異的程式原型。在您製作原型時,它也會自動產生用戶端 SDK。
服務和用戶端應用程式更新完成後,即可部署伺服器和用戶端更新。
產生 Web SDK
與大多數 Firebase 專案一樣,Firebase Data Connect 用戶端程式碼作業會在本機專案目錄中執行。Data Connect VS Code 擴充功能和 Firebase CLI 都是用於產生及管理用戶端程式碼的重要本機工具。
SDK 產生選項會對應至您初始化專案時產生的 dataconnect.yaml
檔案中多個項目。
初始化 SDK 產生作業
在connector.yaml
中新增 outputDir
、package
和 (針對網路 SDK) packageJsonDir
。generate:
javascriptSdk:
outputDir: "../movies-generated"
package: "@movie-app/movies"
packageJsonDir: "../../"
outputDir
會指定產生的 SDK 應輸出至何處。
package
會指定套件名稱。
packageJsonDir
指定安裝套件的地點。
在這種情況下,請安裝 firebase@latest
,確保此相依項目已滿足。
相對於 node_modules
設定路徑
就 Web SDK 而言,由於 Data Connect 會使用 npm link
安裝 SDK,因此您產生的 SDK 必須輸出至與 node_modules
路徑相同層級的目錄,或可存取 node_modules
的子目錄。
換句話說,您產生的 SDK 必須能存取 firebase
節點模組,才能正常運作。
舉例來說,如果您在 my-app/
中擁有 node_modules
,則輸出目錄應為 my-app/js-email-generated
,以便 js-email-generated
從其父項 node_modules
資料夾匯入。
my-app/
dataconnect/
connector/
connector.yaml
node_modules/
firebase/
js-email-generated/
// connector.yaml
connectorId: "my-connector"
generate:
javascriptSdk:
outputDir: "../../js-email-generated"
package: "@myapp/my-connector"
或者,如果您有一個 monorepo,其中模組會託管在根目錄中,您可以將輸出目錄放在 monorepo 中的任何資料夾中。
my-monorepo/
dataconnect/
connector/
connector.yaml
node_modules/
firebase/
my-app/
js-email-generated/
package.json
// connector.yaml
connectorId: "my-connector"
generate:
javascriptSdk:
outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated
在設計原型時更新 SDK
如果您使用 Data Connect VS Code 擴充功能及其 Data Connect 模擬器進行互動式原型設計,SDK 來源檔案會在您修改定義結構定義、查詢和突變的 .gql
檔案時自動產生及更新。這項功能在熱門 (重新) 載入工作流程中非常實用。
.gql
更新的監控,並自動更新 SDK 來源。
或者,您也可以在 .gql 檔案變更時使用 CLI 重新產生 SDK:
firebase dataconnect:sdk:generate --watch
產生 SDK 以便整合及發布正式版
在某些情況下,例如為提交持續整合測試準備的專案來源,您可以呼叫 Firebase CLI 來進行批次更新。
在這種情況下,請使用 firebase dataconnect:sdk:generate
。
設定用戶端程式碼
初始化「Data Connect」應用程式
首先,請使用標準 Firebase 序列初始化應用程式。
initializeApp({...});
初始化 Data Connect Web SDK
使用設定 Data Connect 時所用的資訊 (所有資訊皆可在 Firebase 控制台的「Data Connect」分頁中找到),初始化 Data Connect 執行個體。
ConnectorConfig 物件
SDK 需要連接器設定物件。
這個物件是由 dataconnect.yaml
中的 serviceId
和 location
和 connector.yaml
中的 connectorId
自動產生。
匯入程式庫
初始化用戶端程式碼時,需要兩組匯入作業,分別是一般 Data Connect 匯入作業和特定的產生 SDK 匯入作業。
// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';
// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';
設計及測試網路用戶端
檢測要使用本機模擬器的用戶端
您可以使用 Data Connect 模擬器,無論是透過 Data Connect VS Code 擴充功能或 CLI 皆可。
在兩種情況下,檢測應用程式連線至模擬器的做法都相同。
import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name
const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`
// Make calls from your app
如要切換至正式版資源,請將用於連線至模擬器的程式碼行註解掉。
取得執行個體
只有在您想連線至 Data Connect 模擬器時,才需要呼叫 getDataConnect
。否則,系統會自動為您建立 DataConnect
物件的例項。
在用戶端使用查詢
產生的程式碼會隨附預先定義的查詢參照。您只需匯入並呼叫執行作業即可。
import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';
const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);
呼叫 SDK 查詢方法
以下是使用這些動作快捷鍵函式的範例:
import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out // to the server.
listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}
訂閱變更
您可以訂閱變更 (每次執行查詢時都會更新)。
const listRef = listAllMoviesRef();
// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
updateUIWithMovies(data.movies);
});
await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`
在用戶端使用變異
異動的存取方式與查詢相同。
import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';
const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));
Web SDK 中的資料類型
Data Connect 伺服器代表常見的 GraphQL 資料類型。這些元素在 SDK 中的表示方式如下所示。
資料連結類型 | TypeScript |
---|---|
時間戳記 | 字串 |
日期 | 字串 |
UUID | 字串 |
Int64 | 字串 |
雙人床 | 數字 |
浮點值 | 數字 |
架構注意事項
Angular
產生程式碼時,Angular CLI
不會因其依附元件最佳化程式碼而擷取新變更。為修正這個問題,您必須修改 angular.json
。
"projects": {
"myproject": {
"architect": {
"serve:": {
"prebundle": {
"exclude": ["@movie-app/movies"]
}
}
}
}
}