開始使用 Firebase Data Connect

提示： 加入 Firebase Data Connect 不公開預先發布版計畫，進一步瞭解 Firebase 的第一個 SQL 解決方案。您將有機會成為這項產品的早期採用者，並取得第一手資訊，瞭解 Firebase 為翻新應用程式開發體驗所做的新努力。請至 Firebase Data Connect 產品頁面註冊。

預先發布版： Firebase Data Connect 目前為不公開預先發布版，這表示該產品不適用任何服務水準協議或廢止政策，且可能會以回溯不相容的方式變更。在整個不公開預先發布版中，Data Connect 及其說明文件將會更新及改善。產品的不公開預先發布版不應用於正式版應用程式。

注意： 如要存取 Firebase Data Connect 服務，以及本指南中提及的大多數工具和來源，您必須註冊不公開預先發布版計畫。

在本快速入門導覽課程中，您將瞭解如何：

• 將 Firebase Data Connect 新增至 Firebase 專案。
• 設定開發環境 (包括 Visual Studio Code 擴充功能)，以搭配實際工作環境執行個體使用。
• 接著，我們將說明您可以如何進行以下操作：
  • 使用電子郵件應用程式範例建立結構定義，
  • 為您的結構定義定義查詢和異動。
  • 請使用自動產生的 SDK，從用戶端呼叫這些查詢和變異。
  • 將最終的原型部署至實際工作環境。

事前準備

如要使用本快速入門導覽課程，您必須符合以下條件。

• Linux、macOS 或 Windows
• Visual Studio 程式碼

將 Data Connect 新增至專案並建立資料來源

1. 如果您尚未建立 Firebase 專案，請先建立。
   1. 在 Firebase 控制台，按一下「Add project」(新增專案)，然後按照畫面上的指示操作。

2. 將您的專案升級至 Blaze 方案。這可讓您建立 PostgreSQL 適用的 Cloud SQL 執行個體

   注意： 雖然您已在 Blaze 升級方案中設定帳單，但在預先發布版中使用 Data Connect 或 PostgreSQL 適用的預設 Cloud SQL 設定時，並不會產生費用。

3. 前往 Firebase 控制台的「Data Connect」專區，然後按照產品設定工作流程操作。

4. 選取 PostgreSQL 適用的 CloudSQL 資料庫的位置。

5. 請記下專案、服務和資料庫名稱與 ID，方便稍後確認。

6. 按照剩餘的設定流程操作，然後按一下「完成」。

   注意： PostgreSQL 適用的 Cloud SQL 執行個體佈建作業最多可能需要 20 分鐘才能完成。

選擇並設定開發環境

您要先在 Visual Studio Code 中設計應用程式原型，藉此開始使用 Data Connect。

您可以視需要安裝本機 PostgreSQL 資料庫，以便使用 Data Connect 模擬器進行本機開發作業。本指南結尾會介紹這項設定。

Data Connect 支援兩種設計原型：

• 如果您是網頁或 Kotlin Android 開發人員，可在連線至 PostgreSQL 適用的 Cloud SQL 執行個體時，在本機設計結構定義和作業的原型，或選擇在本機執行 PostgreSQL。

• 如果您是網頁開發人員，可以使用 PostgreSQL 的預先設定的 IDX 範本、具有 Data Connect 模擬器的 VS Code 擴充功能，以及為您設定的快速入門程式碼，在 IDX 工作區中使用 IDX 設計原型。

VS 程式碼開發

如要在本機開發 (而非使用 IDX)，請設定 Firebase VS Code 擴充功能，可讓您透過網頁、Kotlin Android 和即將推出的 iOS 適用的 SDK 產生功能，快速疊代開發。

1. 為本機專案建立新目錄。
2. 在新目錄中開啟 VS Code。
3. 從 Firebase Storage 下載 VSIX 套件隨附的擴充功能。
4. 在 VS Code 中，從「View」選單中選取「Extensions」。
5. 在「Extensions」面板標題列中，按一下選單圖示 more_horiz，然後按照從 VSIX... 安裝。

注意： 此擴充功能包含 marketplace GraphQL 語法醒目顯示擴充功能。您安裝的其他 GraphQL 擴充功能可能會與 VSIX 檔案中隨附的 GraphQL 支援發生衝突。

IDX 開發

IDX 是針對網頁應用程式開發最佳化的環境。如果您是 Kotlin Android 開發人員，請按照「VS 程式碼開發」分頁中的步驟操作。

如要設定 Data Connect IDX 範本，請按照下列步驟操作：

1. 前往 Project IDX 網站存取範本。
2. 按照設定流程操作。

設定本機專案

注意： 如果您「不是」使用 IDX，請按照本節的步驟操作。

按照一般操作說明安裝 CLI。

然後啟用 Firebase Data Connect 實驗。

firebase experiments:enable dataconnect

注意： 如果您使用現有的 CLI 安裝項目，請務必更新至最新版本。

如要設定本機專案，我們會初始化專案目錄，並更新產生程式碼所需的幾個設定檔。

設定專案目錄

初始化專案目錄。

Firebase 擴充功能設定

在 VS Code 左側面板中，按一下 Firebase 圖示，開啟 Firebase VS Code 擴充功能 UI。

在 Firebase 擴充功能 UI 中：

1. 並確定你已登入。
2. 在 Firebase 控制台中，確認 Data Connect 設定流程 (包括資料庫佈建) 已完成。
3. 按一下「Run firebase init」按鈕。
4. 如要查看提示，請前往 VS Code 下方面板中的「Terminal」分頁。
5. 選取「Data Connect」做為要在這個目錄中使用的功能。
6. 系統提示時，請提供您先前在主控台中建立的 Data Connect 專案專案、服務和資料庫 ID。

終端機設定

1. 如有需要，請使用 firebase login 登入。
2. 在 Firebase 控制台中，確認 Data Connect 設定流程 (包括資料庫佈建) 已完成。
3. 按照畫面上的提示執行 firebase init，將目錄初始化為 Firebase 專案。
4. 選取「Data Connect」做為要在這個目錄中使用的功能。
5. 系統提示時，請提供您先前在主控台中建立的 Data Connect 專案專案、服務和資料庫 ID。

任一流程都會建立 firebase.json 和 .firebaserc 檔案，以及 dataconnect 子目錄，包括本機工作目錄中的重要 dataconnect.yaml 和 connector.yaml 檔案。

設定產生 SDK 程式碼的位置

在您編輯結構定義時，Data Connect 會自動產生 SDK 程式碼。

如要指定 SDK 的產生位置，請在 dataconnect/connector/connector.yaml 中更新初始連接器的檔案。

注意：IDX 已提供 connector.yaml 範例。

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

注意：對於網頁 SDK，由於 Data Connect 使用 npm link 安裝 SDK，因此產生的 SDK 必須輸出到與 node_modules 路徑相同層級的目錄，或是位於可存取 node_modules 的子項目錄中。

熟悉 Data Connect 工具包

Data Connect Toolkit 是 Firebase VS Code 擴充功能的元件，可直接透過 Visual Studio Code 協助開發結構定義，以及查詢和異動管理。

如何查看工具包功能：

1. 如果您尚未在 VS Code 中開啟 Firebase 專案目錄，請先完成這項作業。
2. 在 VS Code 的左側面板中，按一下 Firebase 圖示，開啟 Firebase VS Code 擴充功能 UI。

在整個開發工作過程中請注意，工具包可讓您與本機環境「以及生產資源」互動。在本快速入門導覽課程中，您將與實際工作環境互動。

擴充功能 UI 提供多個實用功能：

在 VS Code 主要側欄中：

主要側邊列

• 「Config」面板：可讓您登入 Google 並選取 Firebase 專案。
• 「Firebase Data Connect」面板：可讓您控制內建模擬器，並將資源部署至實際工作環境。
• 「FDC Explorer」面板，會根據結構定義，列出自動產生的隱式查詢與異動

在 VS Code 下方面板中：

下方面板

• 「Data Connect Execution」分頁，其中的工具可讓您在要求中傳送資料、模擬驗證及查看結果。

開始開發應用程式前，請先瞭解擴充功能的部分功能。

試用自訂 CodeLens	當您在 schema.gql、queries.gql 和 mutations.gql 檔案中使用資源時，只要編寫完整的程式碼區塊，自訂 CodeLens 就會顯示您可對宣告的資料表和作業採取的動作。 對於資料表，CodeLens 可協助您產生異動內容，將資料新增至後端資料庫。 針對查詢和異動，CodeLens 可讓您在本機或實際工作環境資源上執行作業。
設定要求的驗證等級	在下方的面板中，Data Connect Execution 面板會提供「設定」分頁，您可以在這裡選取作業的模擬驗證等級。
在查詢和異動中填入變數	在相同「Configuration」分頁中，您可以填入作業酬載。
檢查記錄、回應和錯誤	此外，您也可以在「設定」分頁中查看「記錄」和「結果」分頁，查看偵錯資訊。

建立 Data Connect 結構定義和查詢

設定完成，現在我們可以開始使用 Data Connect 進行開發。

開始使用 GraphQL 建立使用者和電子郵件的模型。您將更新以下來源：

• /dataconnect/schema/schema.gql
• /dataconnect/connector/queries.gql

開始建立結構定義

在 Firebase 專案目錄中記下 dataconnect 資料夾。您可以在這裡使用 GraphQL 定義 Cloud SQL 資料庫的資料模型。

在 /dataconnect/schema/schema.gql 檔案中，開始定義包含使用者和電子郵件的結構定義。

使用者

在 Data Connect 中，GraphQL 欄位會對應至資料欄。使用者擁有 uid、name 和電子郵件地址 address。Data Connect 可辨識數種原始資料類型：String 和 Date。

複製下列程式碼片段，或是取消註解檔案中對應的行。

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

根據預設，如果未提供 UUID id 金鑰，Firebase Data Connect 會預設新增該金鑰。不過在本範例中，您想將 uid 設為主鍵，可以透過 @table(key: "uid") 指令執行。

傳送電子郵件

現在有了使用者，您就可以建立電子郵件模型了。您可以在這裡為電子郵件資料新增一般欄位 (或資料欄)。這次我們省略了新增主鍵，因為您可以使用 Data Connect 來管理主鍵。

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   date: Date!
   text: String!
   from: User!
}

請注意，from 欄位會對應至 User 類型。Data Connect 瞭解這是 Email 和 User 之間的關係，且會為您管理這項關係。

將結構定義部署至正式環境

您正在使用 Firebase VS Code 擴充功能與實際工作環境資料庫搭配使用，因此必須先部署結構定義再繼續。

注意： 佈建 PostgreSQL 適用的 Cloud SQL 執行個體最多可能需要 20 分鐘才能完成。執行個體準備就緒後，才能部署。

1. 您可以使用 Firebase VS Code 擴充功能進行部署。
   • 在擴充功能 UI 的「Firebase Data Connect」面板下方，按一下「Deploy」(部署)。

2. 您也可以使用 Firebase CLI。

   firebase deploy
   

3. 在擴充功能或 CLI 流程中，您可能需要審查結構定義變更，並核准可能具有破壞性的修改內容。系統會提示你：

   • 使用 firebase dataconnect:sql:diff 查看結構定義變更
   • 如果對變更內容感到滿意，請使用 firebase dataconnect:sql:migrate 啟動的流程套用這些變更。

查看產生的結構定義擴充功能

在您編輯電子郵件結構定義時，Data Connect 會自動產生結構定義延伸、查詢、異動、篩選器和資料表關係。您可以透過兩種方式查看產生的程式碼。

• 您可在 Firebase 擴充功能 UI 的「FDC Explorer」面板下方，查看產生的隱含查詢和異動清單。
• 您可以在 .dataconnect/schema 目錄的來源中，查看所有本機產生的程式碼。

執行異動作業，將資料新增至資料表

您可以在 /dataconnect/schema/schema.gql 中的 GraphQL 類型上方看到 CodeLens 按鈕。

開發時間查詢和異動

與這些 CodeLens 按鈕相關聯的作業是快速實用的動作，在本例中為新增資料至資料表。Data Connect 使用 GraphQL 異動來說明可以對資料庫操作的方式和人員。使用這個按鈕即可建立開發時間作業，以便快速播種資料。

將結構定義部署至實際工作環境後，您可以使用「Run (Production)」(實際工作環境) CodeLens 按鈕，在後端執行這些動作。

注意： 網頁開發人員的 IDX 範本包含為各個資料表提供大量種子資料。您可以逐一點選並逐一新增，或將這些元素合併為單一異動。

撰寫查詢以列出電子郵件

現在來談談有趣的部分開發人員會習慣撰寫 SQL 查詢，而非編寫 GraphQL 查詢，因此這乍看之下可能稍有不同。不過，GraphQL 比原始 SQL 更精確、更安全。我們的 VS Code 擴充功能可提升開發體驗。

開始編輯 /dataconnect/connector/queries.gql 檔案。如果您想收到所有電子郵件，請使用如下查詢。

# File `/dataconnect/connector/queries.gql`

query listEmails @auth(level: PUBLIC) {
  emails {
    id, subject, text, date
    from {
      name
    }
  }
}

這裡有個令人期待的功能，就是可以將資料庫的關係當做圖表處理。電子郵件具有參照使用者的 from 欄位，因此您可以在欄位中建立巢狀結構，重新取得使用者的相關資訊。

@auth 指令

在本例中，@auth 指令並沒有充分發揮效用，但這個概念實在是很強大的功能。這是決定對資料庫作業的授權政策的方式

這項查詢相當簡單直觀，當執行更複雜的彙整和多對多關係時，Data Connect 真正令人期待的功能就會開始一流。隨著您探索工具和說明文件，我們會進一步討論這點。

測試查詢

現在我們已建立這個查詢，請先檢查是否可以正常運作，然後再將查詢整合至用戶端程式碼。在 Data Connect 的開發人員體驗中，其中一個可使用「Data Connect Execution」面板快速疊代及測試查詢結果。

您可以提供這項查詢所需的引數，然後按一下查詢名稱上方的「CodeLens」按鈕。這項動作會執行查詢並顯示結果，讓你可以看到運作情形符合預期。

從用戶端應用程式產生用戶端 SDK 程式碼及查詢資料

如要結束開發週期，請將這個查詢整合至用戶端程式碼。

您可以編寫用戶端，示範呼叫查詢及處理 Data Connect 服務回覆的情形。

注意： 如果您使用我們的 IDX 範本，就能從這裡取得起點，包括網頁應用程式架構程式碼。

1. 找出先前在 connector.yaml 檔案中指定的位置自動產生的來源。

2. 將 Firebase 新增至專案、註冊應用程式，並安裝相關的 Firebase 核心 SDK：

   • 如果是 JavaScript，請按照這些步驟操作。
   • 如果是 Kotlin，請按照這篇文章的指示操作。

3. 如果您沒有使用 IDX，則可設定可透過指令列呼叫的用戶端。

JavaScript

建立來源檔案 clientTest.js，並複製下列程式碼。

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);
const dc = getDataConnect(app, connectorConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(dc, "localhost", 9399);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

您可以執行用戶端。

    node clientTest.js
    

Kotlin Android

建立來源檔案 clientTest.kt，並複製下列程式碼。

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}
    

接著：

1. 執行活動。
2. 檢查 Android 的 logcat 輸出內容。

將已完成的原型部署至實際工作環境

您已經歷開發疊代作業。您現在可以使用 Firebase 擴充功能 UI 或 Firebase CLI，將結構定義、資料、查詢和異動內容部署至伺服器，就像處理結構定義一樣。

部署完成後，您的 Data Connect 服務就可以準備處理來自用戶端的作業。PostgreSQL 適用的 Cloud SQL 執行個體 會更新為最終部署的結構定義和資料

(選用) 在本機安裝 PostgreSQL

在本機安裝 PostgreSQL 並與模擬器整合，即可在完全本機開發環境中設計原型。

您可以安裝新的 PostgreSQL 執行個體或使用現有執行個體。

安裝 PostgreSQL

按照平台適用的操作說明，安裝 PostgreSQL 15.x 版。

注意： 請記下使用者名稱和密碼，以便日後存取。

• macOS。下載並安裝 Postgres.app。
• Windows：使用 PostgreSQL 下載頁面的 EDB 安裝程式。
• Docker：提取並執行 pgvector/pgvector:15 映像檔，其同時提供 PostgreSQL 15.x 和向量支援。
• Linux：建議您搭配上述映像檔使用 Docker，但您也可以按照熱門發行版本的替代操作說明進行。

記下安裝序列期間的主機名稱、通訊埠、使用者名稱、密碼，以及相關參數輸出。

如要連線至 PostgreSQL 執行個體，模擬器需要：

• 這些設定設定參數
• dataconnect.yaml 中的資料庫名稱，以及在本機執行個體中初始化的對應命名資料庫。

使用連線字串更新 .firebaserc

使用本機 PostgreSQL 設定詳細資料 (包括本機 PostgreSQL 使用者名稱和密碼) 做為連線字串，將連線字串新增至 .firebaserc 檔案中的以下金鑰。

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

連線至本機 PostgreSQL 執行個體

完成這項設定後，如要連線至本機資料庫，請按照下列步驟操作：

1. 在 VS Code 的左側面板中，按一下 Firebase 圖示，開啟 Firebase VS Code 擴充功能 UI。
2. 按一下「連線至本機 PostgreSQL」按鈕。

後續步驟

提示： 這份逐步操作說明是否讓您有興趣參與不公開預先發布版計畫？如果是，請前往 Firebase Data Connect 產品頁面註冊。