開始使用 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 程式碼

將 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 擴充功能，以協助您快速疊代開發。

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 安裝項目，請務必更新至最新版本。

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

設定專案目錄

初始化專案目錄。

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

在 Firebase 擴充功能 UI 中：

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

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

建立 Data Connect 結構定義和查詢

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

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

• /dataconnect/schema/schema.gql
• /dataconnect/default-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!
   sent: Date!
   text: String!
   from: User!
}

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

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

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

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

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

2. 您也可以使用 Firebase CLI。

   firebase deploy
   

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

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

執行異動事件，將資料新增至資料表

在 VS Code 編輯器面板中，您可以看到 /dataconnect/schema/schema.gql 中 GraphQL 類型上方的 CodeLens 按鈕。

開發時間查詢和異動

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

由於您已將結構定義部署到實際工作環境，因此在產生的檔案中使用 schema.gql 和 Run (Production) 中的「CodeLens」按鈕，即可在後端執行這些動作。

如何新增記錄至 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，將結構定義、資料和查詢部署至伺服器，就像處理結構定義一樣。

部署完成後，您的 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 產品頁面註冊。