使用產生的 Web SDK

Firebase Data Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變異。您可以同時產生自訂用戶端 SDK，並設計要部署至 Data Connect 服務的結構定義、查詢和變異。接著，您將這個 SDK 的方法整合至用戶端邏輯。

如同我們在其他地方提到的，請務必注意 Data Connect 查詢和變異不會由用戶端程式碼提交，也不會在伺服器上執行。相反地，在部署時，Data Connect 作業會儲存在 Cloud Functions 等伺服器上。這表示您必須部署相應的用戶端端變更，以免影響現有使用者 (例如舊版應用程式)。

因此，Data Connect 提供開發人員環境和工具，讓您製作伺服器部署的結構定義、查詢和變異的程式原型。在您製作原型時，它也會自動產生用戶端 SDK。

服務和用戶端應用程式更新完成後，即可部署伺服器和用戶端更新。

使用 Firebase JavaScript SDK 實作用戶端程式碼

本節將說明如何使用 Firebase JavaScript SDK 實作用戶端。

如果您使用的是 React，請參閱其他設定說明和連結，進一步瞭解如何為 Data Connect 產生 React SDK。

初始化應用程式

首先，請使用標準 Firebase 序列初始化應用程式。

initializeApp({...});

產生 JavaScript 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，確保此相依項目已滿足。

初始化 JavaScript SDK

使用設定 Data Connect 時所用的資訊 (所有資訊皆可在 Firebase 控制台的 Data Connect 分頁中找到)，初始化 Data Connect 執行個體。

ConnectorConfig 物件

SDK 需要連接器設定物件。

這個物件會自動從 dataconnect.yaml 中的 serviceId 和 location，以及 connector.yaml 中的 connectorId 產生。

匯入程式庫

初始化用戶端程式碼時，需要兩組匯入作業：一般 Data Connect 匯入作業和特定的產生 SDK 匯入作業。

請注意一般匯入作業中包含的 ConnectorConfig 物件。

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

使用 JavaScript SDK 的查詢

產生的程式碼會隨附預先定義的查詢參照。您只需匯入並呼叫執行作業即可。

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`

使用 JavaScript SDK 中的突變

變異體的存取方式與查詢相同。

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

連線至 Data Connect 模擬器

您可以選擇呼叫 connectDataConnectEmulator，然後傳入 Data Connect 例項，藉此連線至模擬器，如下所示：

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

如要切換至正式版資源，請將用於連線至模擬器的程式碼行註解掉。

為 React 實作用戶端程式碼

Firebase Data Connect 會提供產生的 SDK，其中包含適用於 React 的鉤子，並使用 Invertase 合作夥伴提供的程式庫，也就是 TanStack Query Firebase。

這個程式庫提供一組鉤子，可大幅簡化應用程式中使用 Firebase 處理非同步工作。

初始化應用程式

首先，如同任何 Firebase 網頁應用程式，請使用標準 Firebase 序列初始化應用程式。

initializeApp({...});

安裝 TanStack Query Firebase 套件

在專案中安裝 TanStack Query 套件。

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

產生 React SDK

如同前面所述，與標準網路 SDK 一樣，Firebase 工具會根據您的結構定義和作業，自動產生 SDK。

如要為專案產生 React SDK，請在 connector.yaml 設定檔中新增 react 索引鍵。

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

匯入程式庫

初始化 React 用戶端程式碼時，需要四組匯入項目：一般 Data Connect 匯入項目、一般 TanStack 匯入項目，以及 JS 和 React 產生的 SDK 專屬匯入項目。

請注意一般匯入作業中包含的 ConnectorConfig 類型。

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

在 React 用戶端中使用查詢和突變

設定完成後，您就可以從產生的 React SDK 中納入方法。

在下列程式碼片段中，請注意產生的 React SDK 中含有 use 前置字元的 useListAllMovies 方法。產生的 SDK 中所有這類 use 作業 (包括查詢和突變) 都會呼叫 TanStack 查詢繫結：

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
   const queryClient = new QueryClient();
   return <QueryClientProvider client={queryClient}>
     <MyComponent />
   </QueryClientProvider>
}

連線至 Data Connect 模擬器

您可以選擇呼叫 connectDataConnectEmulator，然後將 Data Connect 例項傳入產生的鉤子，藉此連線至模擬器，如下所示：

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

如要切換至正式版資源，請將用於連線至模擬器的程式碼行註解掉。

SDK 中的資料類型

Data Connect 伺服器代表常見的 GraphQL 資料類型。這些元素在 SDK 中的表示方式如下所示。

Data Connect 類型 TypeScript
時間戳記 字串
日期 字串
UUID 字串
Int64 字串
雙人床 數字
浮點值 數字

產生 SDK 的特別注意事項

相對於 node_modules 設定路徑

就 JavaScript 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 檔案時自動產生及更新。這項功能在熱門 (重新) 載入工作流程中相當實用。

在其他情況下，如果您使用 Firebase CLI 中的 Data Connect 模擬器，可以設定 .gql 更新的監控，並讓 SDK 來源自動更新。

或者，您也可以在 .gql 檔案變更時使用 CLI 重新產生 SDK：

firebase dataconnect:sdk:generate --watch

產生 SDK 以便整合及發布正式版

在某些情況下，例如準備要提交 CI 測試的專案來源，您可以呼叫 Firebase CLI 來進行批次更新。

在這種情況下，請使用 firebase dataconnect:sdk:generate。

其他架構的考量

Angular

產生程式碼時，Angular CLI 不會因為其依附元件最佳化程式碼而擷取新的變更。如要修正這個問題，您必須修改 angular.json。

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }