開始使用 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 擴充功能，以便與實際工作環境執行個體搭配使用。
• 接著，我們會說明如何：
  • 為電子郵件應用程式建立結構定義，並部署至正式環境。
  • 為您的結構定義定義查詢和異動。
  • 將最終結構定義、查詢和資料部署至實際工作環境。

事前準備

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

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

連結至 Firebase 專案

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

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

   注意：雖然您在 Blaze 升級中設定了帳單設定，但在預覽期間，您不會因使用 Data Connect 或預設 PostgreSQL 適用的 Cloud SQL 設定而遭到收費。

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

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

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

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

   注意：為 Cloud SQL for PostgreSQL 例項佈建所需資源可能需要最多 15 分鐘的時間。您可以使用 Google Cloud 主控台確認 Data Connect 設定流程 (包括資料庫佈建) 是否已完成。

選擇並設定開發環境

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

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

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

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

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

   注意： 您無法按兩下 VSIX 套件來安裝擴充功能。 請務必按照後續幾個步驟正確安裝。

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

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

   注意： 這項擴充功能包含 Marketplace GraphQL 語法醒目顯示功能 。您安裝的其他 GraphQL 擴充功能可能會與 VSIX 檔案中隨附的 GraphQL 支援。

您也可以安裝本機 PostgreSQL 資料庫以進行本機開發 透過 Data Connect 模擬器運作。本快速入門指南的最後部分會說明這項設定。

設定本機專案

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

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

npm install -g firebase-tools

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

設定專案目錄

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

在 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 欄位會對應至資料欄。使用者 uid、name和address電子郵件地址。「Data Connect」可辨識多個 原始資料類型：String 和 Date。

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

# 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 擴充功能 ，請先部署結構定義再繼續操作。將結構定義部署至實際運作資料庫後，您應該可以在控制台中查看結構定義。

注意： PostgreSQL 適用的 Cloud SQL 執行個體佈建作業最多可能需要 15 項才能完成 分鐘。在執行個體準備就緒前，您無法進行部署。部署結構定義前，請使用 Google Cloud 控制台確認 Data Connect 設定流程 (包括資料庫佈建) 已完成。

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)」按鈕，將資料新增至後端資料庫。

如要在 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/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 版本。

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

• macOS。下載並安裝 Postgres.app。
• Windows：請從 PostgreSQL 下載頁面使用 EDB 安裝程式。
• Docker：提取並執行 pgvector/pgvector:pg15 映像檔，該映像檔支援 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. 按一下「Connect to Local PostgreSQL」按鈕。

後續步驟

提示：您是否對這份操作說明感興趣，並想參與私人搶先體驗方案？如果是，請前往 Firebase Data Connect 產品頁面。