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 中，在模擬器執行時，請使用「Export emulator data」按鈕匯出資料，以便匯出目前的資料庫內容。預設匯出位置是專案目錄根目錄中的 exportedData 目錄。

注意： 如要修改這個匯出位置，請在使用擴充功能啟動模擬器前，按一下「Configure emulator」連結。

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

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

本節提供用於管理結構定義和連接器的指令 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 資料庫。

當您使用預設 dataconnect.yaml 檔案設定新的本機 Data Connect 專案時，dataconnect:sql:migrate 指令的行為會在執行變更前，先提示您進行任何必要變更，然後再提示您進行任何選用變更。您可以修改這項行為，讓系統一律納入或忽略選用變更，方法是更新 dataconnect.yaml 設定，如「在嚴格或相容模式下遷移結構定義」一文所述。

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

在非互動式環境中：

• 如未使用 --force，則只會進行非破壞性的變更。如果有破壞性的變更，CLI 會中止，且不會進行任何變更。
• 使用 --force 時，所有變更都會完成。如果這項操作包含任何破壞性變更，系統會列印這些變更，並提示您是否要繼續操作，除非您提供 --force 旗標。

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

如同其他 --only 標記，您可以提供多項服務，並以半形逗號分隔。

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

Data Connect 結構定義遷移作業有兩種不同的結構定義驗證模式：嚴格和相容。在嚴格模式驗證中，資料庫結構定義必須與應用程式結構定義完全相符，應用程式結構定義才能部署。相容模式驗證要求資料庫結構定義與應用程式結構定義相容，也就是說，資料庫中未由應用程式結構定義使用的元素將保持不變。

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

驗證模式是使用 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。 如果產生作業失敗，系統會將錯誤訊息輸出至標準輸出，產生的程式碼不會變更，指令也會繼續執行。
	--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 角色	權限	用量	可授予
reader	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	內建超級使用者角色，具備資料庫的完整權限。 除了擁有者權限外，還可建立結構定義、刪除結構定義、安裝擴充功能，以及執行其他管理工作。 以「firebasesuperuser」登入 CLI 後即可存取。	必須具備這項權限，才能安裝擴充功能、建立初始結構定義，以及將任何可授予的 SQL 角色授予其他使用者。 如果非管理員使用者需要超級使用者權限，移轉作業就會失敗，並提示使用者請求資料庫管理員 (即具備 roles/cloudsql.admin 的使用者) 執行具權限的 SQL 指令。	授予具有 roles/cloudsql.admin 的使用者，且無法直接從 Firebase CLI 授予

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

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

全域選項

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

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