Data Connect 的 Firebase CLI 指令參考資料

Firebase CLI 是一項工具，可讓您透過指令列管理及設定 Firebase 產品和服務。

CLI 提供多種指令，可用於執行各種 Data Connect 工作，例如建立新 Data Connect 專案、初始化對應的本機工作目錄、設定 Data Connect 模擬器、列出 Data Connect 資源、產生用戶端 SDK 等。

設定指令

將「Data Connect」新增至 Firebase 專案

firebase init

使用 firebase init 設定新的本機專案設定。這個工作流程會在目錄中建立或更新 Firebase 設定檔。

firebase init

firebase init 流程會引導您設定服務和資料庫，並視需要安裝 Data Connect 模擬器及設定產生的 SDK。

設定服務和資料庫

如果選取 dataconnect 進行產品設定，CLI 會提示您輸入新的服務名稱和位置，以及是否要連結現有的 PostgreSQL 適用的 Cloud SQL 執行個體，或是建立新的執行個體。

如果連結現有執行個體，CLI 會檢查相容的設定，例如 IAM 驗證和公開 IP 位址。

注意：在流程中佈建新的 Cloud SQL 執行個體最多可能需要 15 分鐘。

注意：如要使用客戶管理的加密金鑰 (CMEK)，請務必連結現有的 Cloud SQL 資料庫和 CMEK。

Local Emulator Suite設定

CLI 流程會提供模擬器設定選項，包括 Data Connect 模擬器。

Data Connect 模擬器指令

啟動 Data Connect 模擬器

emulators:start/exec

firebase emulators:start/exec

在互動模式下，使用 Local Emulator Suite 版本的 Data Connect 模擬器搭配 start，或在指令碼驅動的非互動模式下，使用 exec。

匯出及匯入本機 PostgreSQL 資料

為支援本機原型設計和測試，以及持續整合，您可以匯出儲存在本機資料庫執行個體中的資料，並在開發疊代和測試執行之間匯入資料。

匯出內容會以本機 PostgreSQL 資料庫的快照形式儲存。

Data Connect 提供三種匯出/匯入方法：

• 在 firebase.json 中設定自動匯出/匯入，在模擬器關機和啟動時提供快照備份
• 使用 CLI 手動匯出/匯入
• 使用 VS Code 擴充功能介面手動匯出/匯入

在 firebase.json 中設定自動匯出及匯入

如要在開發工作階段之間備份資料，請在 firebase init 序列中指定自動備份位置。這個位置會儲存在 emulators.dataconnect.dataDir 欄位的 firebase.json 中。模擬器執行期間，您所做的任何資料變更都會自動儲存於此，因此在進行本機測試和探索時非常實用。

手動匯出：emulators:export和emulators:start/exec --import

在 Data Connect 模擬器執行期間，在另一個終端機中執行 firebase emulators:export 指令，儲存資料的快照。接著，您可以使用 --import 標記，從該快照啟動模擬器。

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

注意：使用 CLI 透過 emulators:start --import 標記手動匯入時，您指定的匯入目錄會優先於 firebase.json 中設定的預設備份目錄。

注意：手動匯入及匯出是透過 CI/CD 填入測試資料的好方法。

手動匯出/匯入：VS Code 擴充功能

在 VS Code 擴充功能 UI 中，模擬器執行期間，使用「匯出模擬器資料」按鈕匯出目前的資料庫內容。預設匯出位置是專案目錄根層級的 exportedData 目錄。

注意： 如要修改匯出位置，請先按一下「Configure emulator」(設定模擬器) 連結，再使用擴充功能啟動模擬器。

如上一節所述，您可以使用 CLI 匯入這項資料。您也可以在透過 VS Code 啟動模擬器前匯入這項資料，方法是按一下「設定模擬器」連結，然後設定「匯入路徑」。

結構定義和連接器管理指令

本節提供 CLI 參考資訊，說明如何使用指令管理結構定義和連接器。

注意： 您可以授予個別使用者更多或更少的提升權限角色，藉此限制 PostgreSQL 資料庫的存取權。下列指令的行為可能因目前使用者的角色而異。請參閱 Cloud SQL 管理指令。

如要瞭解這些指令的使用案例和建議做法，請參閱結構定義和連接器管理指南。

部署結構定義和連接器

部署

firebase deploy

這個指令會部署 firebase.json 中建立索引的 Data Connect 服務資源。視需要執行結構定義遷移和連接器更新。

指令	說明
firebase deploy	旗標	說明
	--only dataconnect	為這個專案的所有 Data Connect 服務部署結構定義和連接器，但不要部署其他 Firebase 產品資源。
	--only dataconnect:serviceId	為指定的 Data Connect 服務部署結構定義和連接器。
	--only dataconnect:serviceId:connectorId	為指定的 Data Connect 服務部署單一連接器。
	--only dataconnect:serviceId:schema	為指定的 Data Connect 服務部署結構定義。

使用 –-only 旗標，即可傳遞以半形逗號分隔的值，部署所需的任何資源子集。

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

列出 Data Connect 服務、結構定義和連接器

dataconnect:services:list

firebase dataconnect:services:list

這個指令會列印專案中部署的服務、結構定義和連接器基本資訊。

比較及遷移 SQL 結構定義

執行 firebase deploy 時，CLI 會先比較 SQL 結構定義，再部署更新。您也可以直接使用一組 dataconnect:sql 指令執行比較和更新。

dataconnect:sql:diff

firebase dataconnect:sql:diff

這項指令會比較服務的本機結構定義與對應 Cloud SQL 資料庫的目前結構定義。這會列印出要執行的指令，將資料庫遷移至新結構定義。

指令	說明
firebase dataconnect:sql:diff	旗標/參數	說明
	serviceId	指定服務。如果省略，則會列印 firebase.json 中所有服務的差異。

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

這項指令會將本機結構定義變更套用至服務的 Cloud SQL 資料庫。

設定新的本機 Data Connect 專案時，如果使用預設的 dataconnect.yaml 檔案，dataconnect:sql:migrate 指令的行為是先提示您進行所有必要變更，然後提示您進行所有選用變更，最後再執行變更。如要修改這項行為，一律納入或忽略選用變更，請更新您的dataconnect.yaml設定，詳情請參閱「以嚴格或相容模式遷移結構定義」一文。

在互動式環境中，CLI 會顯示每個遷移 SQL 陳述式 (以及是否具破壞性)，並提示您要套用的變更。傳遞 --force 旗標等同於接受所有提示。

在非互動式環境中：

• 如果沒有 --force，系統只會進行非破壞性變更。如有破壞性變更，CLI 會中止作業，且不會進行任何變更。
• 所有變更都會透過 --force 進行。如果包含任何破壞性變更，系統會列印這些變更，並提示您是否要繼續 (除非提供 --force 旗標)。

指令	說明
firebase dataconnect:sql:migrate	旗標	說明
	serviceId	遷移指定服務的資料庫。如果專案只有一項服務，系統會推斷 serviceId。
	--force	自動接受提示。

與其他 --only 標記一樣，你可以提供多項服務，並以半形逗號分隔。

以嚴格或相容模式遷移結構定義

Data Connect 架構遷移有兩種不同的架構驗證模式：strict 和 compatible。嚴格模式驗證要求資料庫結構定義必須與應用程式結構定義完全相符，才能部署應用程式結構定義。如要進行相容模式驗證，資料庫結構定義必須與應用程式結構定義相容，也就是說，資料庫中未使用的元素不會經過修改。

如要瞭解這些結構定義驗證模式和結構定義遷移最佳做法，請參閱結構定義和連結器管理指南。

您可以使用 dataconnect.yaml 檔案中的 schemaValidation 鍵定義驗證模式。如果未指定 schemaValidation，CLI 會套用相容的變更，並在執行任何嚴格變更前提示您。請參閱設定參考資料。

管理連接器變更

執行 firebase deploy 時，CLI 會啟動適用連接器的更新。CLI 會分析每個連接器的變更，並針對可能導致舊版用戶端程式碼發生非預期行為 (警告層級訊息) 或中斷 (中斷層級訊息) 的連接器變更，發布一組評估訊息。

注意： 以下清單僅列出部分用途。請參閱 CLI 輸出訊息，瞭解適用於連接器的警告和錯誤。

影響評估	情境
警告等級 (與有線裝置相容，但行為可能有所不同)	從查詢中移除可為空值的欄位，但沒有 @retired 註解。
重大變更 (線路不相容，可能會導致用戶端中斷)	將可為空值的變數變更為不可為空值，且沒有預設值。 將欄位的資料類型變更為與 JSON 相容的類型 (例如從 Int 變更為 Float)。 將不可為空值的資料欄變更為可為空值。 移除沒有 @retired 註解的可為空值變數。 移除具有預設值的非空值變數，但沒有 @retired 註解。
破壞性層級 (線路不相容，會中斷用戶端)	移除沒有 @retired 註解的作業。 從沒有 @retired 註解的查詢中移除非空值欄位。 新增沒有預設值的非空值變數。 將欄位的資料類型變更為不相容的類型 (例如從 String 變更為 Int)。 移除沒有預設值且沒有 @retired 註解的非空值變數。

在互動式環境中，CLI 會顯示每個連結器評估結果，並提示您要套用的變更。傳遞 --force 標記等同於接受所有評估。

在非互動式環境中：

• 如果只發生警告層級的評估 (可能導致行為變更)，系統會部署所有連接器，並將警告記錄到終端機。
• 如果發生任何重大程度的評估，系統就不會部署任何連接器，並將警告記錄到終端機。您可以使用 --force 標記覆寫這項設定。

稽核授權碼

Data Connect 可在您使用 Firebase CLI 部署至伺服器時，分析連結器程式碼，協助稽核授權策略。firebase deploy您可以透過這項稽核來檢查程式碼集。

部署連結器時，CLI 會輸出連結器中現有、修改和新作業程式碼的評估結果。

如果是經過修改和新增的作業，當您在新作業中使用特定存取層級，或是修改現有作業以使用這些存取層級時，CLI 會發出警告並提示您確認。

注意： 如果您使用 insecureReason 引數為作業中的 @auth 指令加上註解，系統就會抑制不安全作業警告。

系統一律會針對下列情況顯示警告和提示：

• PUBLIC

此外，當您未透過 auth.uid 使用篩選器擴增下列存取層級時，系統會顯示警告和提示：

• USER
• USER_ANON
• USER_EMAIL_VERIFIED

如要進一步瞭解授權，請參閱授權和認證指南。

SDK 指令

產生 SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

這個指令會產生 connector.yaml 中宣告的型別化 SDK。

另請參閱網頁 SDK、Android SDK 和 iOS SDK 的使用指南。

指令	說明
firebase dataconnect:sdk:generate	旗標	說明
	--watch	在您將變更儲存至結構定義和連接器 GQL 檔案時，保持程序運作並產生新的 SDK。 如果生成失敗，系統會將錯誤列印至 stdout，生成的程式碼不會變更，且指令會繼續執行。
	--only connectorId:platform	只能為單一平台和單一連接器產生 SDK。

使用 –only 旗標時，您可以傳遞以半形逗號分隔的值。

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Cloud SQL 管理指令

授予 Cloud SQL 的 SQL 角色

Data Connect 運作時會使用您在 Cloud SQL 上代管的 PostgreSQL 執行個體。SQL 角色指令可協助您管理資料庫表格的權限。

dataconnect:sql:setup

firebase dataconnect:sql:setup

這項指令會為資料庫中的資料表設定初始全域權限。

預設資料庫佈建和管理流程會假設專案使用新的 (綠地) 資料庫，當您叫用 firebase deploy 時，Data Connect 會顯示要進行的資料庫結構定義變更，並在您核准後執行任何遷移作業。如果這是您偏好的流程，dataconnect:sql:setup 會提示您授予權限，包括 superuser 架構擁有權。

如果是現有 (棕地) 資料庫，您可能已有遷移結構定義的工作流程，並希望自行維護結構定義擁有權。如果偏好這個流程，請務必在dataconnect:sql:setup提示中拒絕，讓 Data Connect 為您處理 SQL 遷移作業。拒絕後，Data Connect只會取得資料庫表格的 read 和 write 存取權，但結構定義擁有權和遷移作業仍由您負責。

如需更多討論內容和用途，請參閱「管理服務和資料庫」。

dataconnect:sql:grant

firebase dataconnect:sql:grant

有時您可能想直接存取資料庫，查詢或更新 Data Connect 應用程式產生的資料。如要執行這項操作，請將本節中定義的其中一個角色授予必要的使用者或服務帳戶。

如要瞭解授予的角色，請參閱 PostgreSQL 使用者角色。

注意： 除了使用 Firebase CLI 設定 PostgreSQL 角色，您還需要指派 IAM 角色 roles/cloudsql.client。請參閱服務和資料庫管理指南。

角色	SQL 角色	權限	用量	可授予
讀取者	firebasereader_<db_name>_<schema_name>	具備資料庫的唯讀存取權。 可對指定結構定義中的所有資料表執行 SELECT 作業。	適合需要擷取資料但不需修改資料的使用者或服務。	是
作家	firebasewriter_<db_name>_<schema_name>	資料庫的讀寫權限。 可對結構定義中的所有資料表執行 SELECT、INSERT、UPDATE、DELETE 和 TRUNCATE 作業。	適合需要修改資料庫內資料的使用者或服務。	是
擁有者	firebaseowner_<db_name>_<schema_name>	結構定義擁有者。 擁有結構定義中所有資料表和序列的所有權限。	這個角色搭配 IAM roles/cloudsql.client 角色，可授予在資料庫上執行遷移作業的權限。 舉例來說，呼叫 firebase dataconnect:sql:migrate 時。	是
超級使用者	cloudsqlsuperuser	內建超級使用者角色，具備資料庫的完整權限。 除了擁有者權限外，還能建立結構定義、捨棄結構定義、安裝擴充功能，以及執行任何其他管理工作。 在 CLI 中登入「firebasesuperuser」即可存取。	安裝擴充功能、建立初始結構定義，以及將任何可授予的 SQL 角色授予其他使用者時，都需要這項權限。 如果非管理員使用者需要超級使用者權限，移轉作業就會失敗，並提示使用者要求資料庫管理員 (即具備 roles/cloudsql.admin 的使用者) 執行具備權限的 SQL 指令。	授予擁有 roles/cloudsql.admin 的使用者，無法直接從 Firebase CLI 授予

注意： 這些 SQL 角色與 Cloud SQL IAM 角色不同。身分與存取權管理角色可控管資料庫的存取權。SQL 角色可控管您可透過這類存取權執行的作業，以及可修改的資料表。

指令	說明
firebase dataconnect:sql:grant	旗標/參數	說明
	-R, --role role	要授予的 SQL 角色，包括擁有者、寫入者或讀取者。
	-E, --email email_address	要授予角色的使用者或服務帳戶電子郵件地址。

全域選項

下列全域選項適用於所有指令：

• --json 會將 CLI 輸出切換為 JSON，供其他工具剖析。
• 視需要覆寫 --noninteractive 和 --interactive，自動偵測非 TTY 環境。