開始使用 Firebase Data Connect

在本快速入門導覽課程中，您將瞭解以下內容：

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

事前準備

如要使用這個快速入門導覽課程，您需要下列項目。

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

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

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

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

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

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

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

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

選擇及設定開發環境

您會先從 Visual Studio 程式碼設計應用程式原型，以使用 Data Connect。

您可以選擇使用 Data Connect 模擬器安裝本機 PostgreSQL 資料庫，進行本機開發作業。此設定將在本快速入門指南的結尾介紹。

Data Connect 支援兩種設計原型開發體驗：

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

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

設定本機專案

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

接著，啟用 Firebase Data Connect 實驗。

firebase experiments:enable dataconnect

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

設定專案目錄

初始化專案目錄。

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

設定 SDK 程式碼的產生位置

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

如要指定 SDK 的產生位置，請在 dataconnect/connector/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

熟悉 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」分頁，此分頁包含多項工具，可讓您在要求中傳遞資料、模仿驗證作業及查看結果。

開始開發應用程式前，不妨先看看擴充功能的幾項功能。

建立 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!
}

根據預設，如未提供，Firebase Data Connect 會新增 UUID id 金鑰。不過，您可以將我的 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 擴充功能搭配實際工作環境的資料庫，因此必須先部署結構定義才能繼續。

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 (實際工作環境)」按鈕，在後端執行這些動作。

撰寫查詢以列出電子郵件

現在有趣部分是查詢開發人員習慣編寫 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
    }
  }
}

這裡有個特別有趣的功能，就是能將資料庫的關係處理成圖表。由於電子郵件具有參照 User 的 from 欄位，因此您可以將巢狀結構嵌入欄位內，並取得使用者的相關資訊。

@auth 指令

在這個範例中，@auth 指令未充分發揮潛力，但這個概念非常強大。這就是針對資料庫作業決定操作授權政策的方式。

這項查詢相當簡單直接，當您執行具有多對多關係的更複雜的彙整作業時，Data Connect 真正令人興奮的功能就會開始運作。當您探索工具和說明文件時，您將進一步瞭解此功能。

測試查詢

建立這項查詢後，請先檢查查詢是否有效，然後再將其整合至用戶端程式碼。Data Connect 開發人員體驗中的其中一項要素，就是透過「Data Connect Execution」面板快速執行及測試查詢結果。

您可以提供這項查詢所需的引數，然後按一下查詢名稱上方的 CodeLens 按鈕。這會執行查詢並顯示結果，所以您可以看到工作是否正常運作。

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

如要關閉開發週期，請將這項查詢整合至用戶端程式碼。

您可以編寫用戶端來示範呼叫資料 Connect 服務及處理回覆。

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

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

   • 如果是 JavaScript，請按照這些說明操作。
   • 如果是 Kotlin，請按照這裡的說明操作。

3. 如果您使用的不是 IDX，則可以設定用戶端 (可透過指令列呼叫)。

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
    

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")
      }
    }
  }
}
    

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

您已經研究了開發階段的成果。您現在可以使用 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」按鈕。

後續步驟