使用產生的 Flutter SDK

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

如我們在其他地方所述，請務必注意，Data Connect 查詢和突變不會由用戶端程式碼提交，而是在伺服器上執行。而是部署後，Data Connect 作業會儲存在伺服器上，例如 Cloud Functions。也就是說，您需要部署對應的用戶端變更，避免現有使用者 (例如使用舊版應用程式) 無法正常運作。

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

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

什麼是用戶端開發工作流程？

如果您已按照「開始使用」一文的說明操作，應該已瞭解 Data Connect 的整體開發流程。本指南將詳細說明如何從結構定義產生 Flutter SDK，以及如何處理用戶端查詢和變動。

總而言之，如要在用戶端應用程式中使用產生的 Flutter SDK，請先完成下列必要步驟：

  1. 將 Firebase 新增至 Flutter 應用程式。
  2. 安裝 flutterfire CLI dart pub global activate flutterfire_cli。
  3. 執行 flutterfire configure。

接著：

  1. 開發應用程式結構定義。

  2. 設定 SDK 產生作業：

    • 使用 Data Connect VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕
    • 更新connector.yaml。

  3. 初始化用戶端程式碼並匯入程式庫。

  4. 實作查詢和異動的呼叫。

  5. 設定及使用 Data Connect 模擬器，然後疊代。

產生 Flutter SDK

與大多數 Firebase 專案一樣，您會在專案的本機目錄中處理Firebase Data Connect用戶端程式碼。Data Connect VS Code 擴充功能和 Firebase CLI 都是重要的本機工具，可產生及管理用戶端程式碼。

SDK 生成選項會對應到您初始化專案時生成的 dataconnect.yaml 檔案中的多個項目。

初始化 SDK 生成作業

在 connector.yaml 中，加入 outputDir、package 和 (適用於網頁 SDK) packageJsonDir。 
connectorId: movies
generate:
  dartSdk:
    outputDir: ../../lib/generated # Feel free to change this to a different path
    package: movies

outputDir 指定產生的 SDK 輸出位置。這個路徑是相對於包含 connector.yaml 檔案本身的目錄。您可以選擇提供 outputDir 的絕對路徑。

package 指定套件名稱。

在原型設計期間更新 SDK

如果您使用 Data Connect VS Code 擴充功能及其 Data Connect 模擬器，以互動方式製作原型，系統會在您修改定義結構定義、查詢和變異的 .gql 檔案時，自動產生及更新 SDK 來源檔案。在熱重載工作流程中，這項功能相當實用。

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

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

firebase dataconnect:sdk:generate --watch

產生 SDK，用於整合及發布正式版

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

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

設定用戶端程式碼

初始化 Data Connect 應用程式

首先，請按照標準 Firebase 設定說明初始化應用程式。

然後安裝 Data Connect 外掛程式：

flutter pub add firebase_data_connect

初始化 Data Connect Flutter SDK

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

匯入程式庫

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

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

在用戶端使用查詢

產生的程式碼會預先定義查詢參照。您只需要匯入並對其呼叫 execute 即可。

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

呼叫 SDK 查詢方法

以下是使用這些動作快速鍵函式的範例：

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

選填欄位

部分查詢可能會有選填欄位。在這些情況下，Flutter SDK 會公開建構工具方法，且必須分別設定。

舉例來說，呼叫 createMovie 時，rating 欄位為選用欄位，因此您需要在建構函式中提供該欄位。

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();

訂閱變更

您可以訂閱變更 (每次執行查詢時都會更新)。

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

在用戶端使用變異

變動作業的存取方式與查詢作業相同。

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

製作 Flutter 應用程式原型並進行測試

設定用戶端，使用本機模擬器

您可以透過 Data Connect 模擬器，從 Data Connect VS Code 擴充功能或 CLI 進行操作。

無論是哪種情境，將應用程式連線至模擬器的做法都相同。

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

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

Dart SDK 中的資料型別

Data Connect 伺服器代表常見的 GraphQL 資料型別。這些項目在 SDK 中會以以下方式表示。

資料連結類型 Dart
時間戳記 firebase_data_connect.Timestamp
Int (32 位元) int
日期 DateTime
UUID 字串
Int64 int
浮點值 double
布林值 bool
不限 firebase_data_connect.AnyValue