開始使用 Firebase Data Connect

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

  • Firebase Data Connect 新增至您的 Firebase 專案。
  • 設定開發環境,包括 Visual Studio Code 擴充功能,以便與實際工作環境執行個體搭配使用。
  • 接著,我們會說明如何:
    • 為電子郵件應用程式建立結構定義,並部署至正式環境。
    • 為您的結構定義定義查詢和異動
    • 將最終結構定義、查詢和資料部署至實際工作環境。

事前準備

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

連結至 Firebase 專案

  1. 如果尚未建立 Firebase 專案,請先建立。
    1. Firebase 控制台中,按一下 新增專案,然後按照畫面上的指示操作。
  2. 將專案升級至 Blaze 方案。建立 Cloud SQL 適用於 PostgreSQL 執行個體

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

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

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

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

選擇並設定開發環境

Data Connect 支援兩種開發體驗,以便進行原型設計:

  • 如果您是 Kotlin AndroidiOS網頁開發人員,可以使用 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 Code 擴充功能 UI。

在 Firebase 擴充功能 UI 中:

  1. 並確定你已登入。
  2. 按一下「Run firebase init」按鈕。
  3. 請查看 VS Code 下方面板中的「Terminal」分頁,瞭解提示。
  4. 選取「Data Connect」做為要在這個目錄中使用的功能。
  5. 系統提示時,請提供您先前在控制台中建立的 Data Connect 專案的專案、服務和資料庫 ID。

建立結構定義

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

使用者

Data Connect 中,GraphQL 欄位會對應至資料欄。使用者 uidnameaddress電子郵件地址。「Data Connect」可辨識多個 原始資料類型:StringDate

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

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

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

根據預設,如果未提供 UUID,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 擴充功能 ,請先部署結構定義再繼續操作。將結構定義部署至實際運作資料庫後,您應該可以在控制台中查看結構定義。

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

將資料加入表格

在 VS Code 編輯器面板中,您會看到 CodeLens 按鈕會顯示在 /dataconnect/schema/schema.gql 中的 GraphQL 類型上。由於您已將結構定義部署至實際執行環境,因此可以使用「Add data」和「Run (Production)」按鈕,將資料新增至後端資料庫。

如要在 UserEmail 表格中新增記錄,請按照下列步驟操作:

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

定義查詢

接下來是查詢的部分。開發人員習慣編寫 SQL 而非 GraphQL 查詢,因此初期情況會稍有不同。 不過,GraphQL 比原始 SQL 更精簡,且具有類型安全性。以及我們的 VS Code 擴充功能可以簡化開發體驗

開始編輯 /dataconnect/connector/queries.gql 檔案。如要取得所有電子郵件,請使用類似以下的查詢。

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

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

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

這裡有一項令人期待的功能 例如圖表由於電子郵件含有參照使用者的 from 欄位,您可以巢狀進入該欄位,並取得使用者相關資訊。

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

您已完成一個開發迭代。您現在可以 使用 Firebase 向伺服器結構定義、資料和查詢 擴充功能 UI 或 Firebase CLI,就像使用結構定義時一樣 (#deploy-schema)。

如果您使用 Firebase VS Code 擴充功能進行部署,請按一下「Deploy」按鈕。

部署完成後,您應該也可以在控制台中查看及執行作業。您的「Data Connect」服務就能開始處理作業 。Cloud SQL for PostgreSQL 執行個體會更新為最終部署產生的結構定義和資料。

(選用) 在本機安裝 PostgreSQL

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

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

安裝 PostgreSQL

按照適用於您平台的操作說明,安裝 PostgreSQL 15.x 版本。

請留意 安裝序列

如要連線至 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. 按一下「Connect to Local PostgreSQL」按鈕。

後續步驟