開始使用 Firebase Data Connect

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

• 將 Firebase Data Connect 新增至 Firebase 專案。
• 設定包括 Visual Studio 的開發環境 用於與實際工作環境執行個體搭配使用的程式碼擴充功能。
• 接著將說明以下內容：
  • 為電子郵件應用程式建立結構定義，並部署至實際工作環境。
  • 為您的結構定義定義查詢和異動。
  • 將最終的原型部署至實際工作環境。

事前準備

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

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

連結至 Firebase 專案

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

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

3. 前往 Firebase 控制台的「Data Connect」部分 並按照產品設定流程操作

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

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

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

選擇並設定開發環境

Data Connect 支援兩種設計原型：

• 如果您是 Kotlin Android 或網頁開發人員，則可以使用 VS Code 開發藉此在本機設計結構定義和作業原型 PostgreSQL 適用的 Cloud SQL 執行個體
• 如果您是網頁開發人員，可以使用 IDX 開發來設計原型 透過 PostgreSQL 使用預先設定的 IDX 範本 具備 Data Connect 模擬器的 VS Code 擴充功能，以及快速入門導覽課程程式碼 設定想進一步瞭解 Project IDX 網站。

本快速入門導覽課程著重於 VS Code 擴充功能的開發流程，如要繼續，請按照下列步驟操作：

1. 為本機專案建立新目錄。
2. 在新目錄中開啟 VS Code。

3. 從 Firebase Storage 下載 VSIX 套件隨附的擴充功能。

4. 在 VS Code 中，從「View」選單中選取「Extensions」。

5. 按一下「擴充功能」面板標題列的選單圖示 more_horiz，然後追蹤 從 VSIX 安裝...。

您也可以安裝本機 PostgreSQL 資料庫以進行本機開發 與 Data Connect 模擬器搭配使用我們會在結尾介紹 這份快速入門指南。

設定本機專案

按照一般操作說明安裝 CLI。如果有 npm ，請執行下列指令：

npm install -g firebase-tools

設定專案目錄

如要設定本機專案，請初始化專案目錄。

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

在 Firebase 擴充功能 UI 中：

1. 並確定你已登入。
2. 按一下「Run firebase init」按鈕。
3. 如要查看提示，請前往 VS Code 下方面板中的「Terminal」分頁。
4. 選取「Data Connect」做為要在這個目錄中使用的功能。
5. 系統出現提示時，請提供 先前在控制台中建立的 Data Connect 專案。

建立結構定義

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

使用者

在 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!
   sent: Date!
   text: String!
   from: User!
}

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

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

如果您採用 Firebase VS Code 擴充功能 ，請先部署結構定義再繼續操作。更新後 應該可以看到 設定 Deployment

1. 您可以使用 Firebase VS Code 擴充功能進行部署。
   • 在擴充功能 UI 的「Firebase Data Connect」面板下方，按一下 部署。
2. 您可能需要檢查結構定義變更，並核准可能的破壞性 或是修改內容系統會提示你：
   • 使用 firebase dataconnect:sql:diff 查看結構定義變更
   • 如果對變更內容感到滿意，請透過 firebase dataconnect:sql:migrate。

將資料加入表格

在 VS Code 編輯器面板中，可以看到 CodeLens 按鈕出現在 /dataconnect/schema/schema.gql 中的 GraphQL 類型。由於您已部署 要將結構定義發布至實際工作環境，您可以使用「新增資料」和「執行 (實際工作環境)」 按鈕會將資料新增至後端的資料庫。

如何新增記錄至 User 和 Email 資料表：

1. 在 schema.gql 中，按一下 User 類型上方的「Add data」(新增資料) 按鈕 宣告。
   
2. 在系統產生的 User_insert.gql 檔案中，指定 三個欄位
3. 按一下「Run (Production)」按鈕。
   
4. 重複上述步驟，將記錄新增至 Email 資料表，並提供 fromUid 欄位中使用者的 uid，如產生的 Email_insert 異動。

定義查詢

現在來談談有趣的部分開發人員習慣編寫 SQL 而非 GraphQL 查詢，因此初期情況會稍有不同。 不過，GraphQL 比原始 SQL 更精確、更安全。以及我們的 VS Code 擴充功能可以簡化開發體驗

開始編輯 /dataconnect/default-connector/queries.gql 檔案。如果您希望 想取得所有電子郵件，請使用像這樣的查詢。

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

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

使用鄰近的 CodeLens 按鈕執行查詢。

這裡有一項令人期待的功能 例如圖表由於電子郵件的 from 欄位參照 使用者，您可以將巢狀結構置入欄位中，重新取得使用者的相關資訊。

將結構定義和查詢部署至實際工作環境

您已經歷開發疊代作業。您現在可以 使用 Firebase 向伺服器結構定義、資料和查詢 的 UI 或 Firebase CLI，就像輸入結構定義一樣。

如果您使用 Firebase VS Code 擴充功能部署，請按一下「Deploy all」(全部部署) 按鈕。

部署完成後，您應該就能在控制台中查看及執行作業 您的 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 中的資料庫名稱及對應的 已初始化的資料庫應用程式。

使用本機 PostgreSQL 執行個體

您可以使用現有的本機 PostgreSQL 執行個體，方法是更新 Data Connect 模擬器設定。

firebase setup:emulators:dataconnect

系統提示時，請按照下列格式輸入 PostgreSQL 連線字串： postgresql://postgresusername:postgrespassword@localhost:5432/postgresdatabase?sslmode=disable。

如要進一步瞭解連線字串，請參閱 PostgreSQL 說明文件。

連線至本機 PostgreSQL 執行個體

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

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

後續步驟