匯出及匯入資料

您可以使用 Cloud Firestore 代管的匯出和匯入服務，復原意外刪除的資料，以及匯出資料以供離線處理。您可以匯出所有文件，或只匯出特定集合群組。同樣地，您也能匯入某個匯出項目中的所有資料，或只匯入特定集合群組。從某個 Cloud Firestore 資料庫匯出的資料，可以匯入另一個 Cloud Firestore 資料庫。您也可以將 Cloud Firestore 匯出項目載入 BigQuery。

本頁面說明如何使用代管匯出和匯入服務及 Cloud Storage，匯出及匯入 Cloud Firestore 文件。Cloud Firestore 代管匯出和匯入服務可透過 gcloud 指令列工具和 Cloud Firestore API (REST、RPC) 使用。

事前準備

您必須先完成下列工作，才能使用代管匯出和匯入服務：

1. 啟用 Google Cloud 專案的計費功能。只有已啟用計費功能的 Google Cloud 專案，才能使用匯出和匯入功能。
2. 在靠近Cloud Firestore資料庫位置的地方，為專案建立Cloud Storage bucket。您無法使用「要求者付費」值區或快速值區執行匯出和匯入作業。

3. 請確認您的帳戶具備 Cloud Firestore 和 Cloud Storage 的必要權限。如果您是專案擁有者，您的帳戶已具備必要權限。否則，下列角色會授予匯出和匯入作業，以及存取 Cloud Storage 所需的權限：

   • Cloud Firestore 角色： Owner、Cloud Datastore Owner 或 Cloud Datastore Import Export Admin

   • Cloud Storage 角色： Owner 或 Storage Admin

服務代理權限

匯出和匯入作業會使用 Cloud Firestore 服務代理，授權 Cloud Storage 作業。Cloud Firestore 服務代理程式採用下列命名慣例：

Cloud Firestore 服務代理

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

如要進一步瞭解服務代理，請參閱「服務代理」。

Cloud Firestore 服務代理需要存取匯出或匯入作業中使用的 Cloud Storage bucket。如果 Cloud Storage bucket 與 Cloud Firestore 資料庫位於相同專案，Cloud Firestore 服務代理預設可存取該 bucket。

如果 Cloud Storage bucket 位於其他專案，您必須授予 Cloud Firestore 服務代理 Cloud Storage bucket 的存取權。

將角色指派給服務代理

您可以使用 gsutil 指令列工具指派下列其中一種角色。例如，如要將 Storage 管理員角色指派給 Cloud Firestore 服務代理，請執行下列指令：

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

將 PROJECT_NUMBER 替換為專案編號，用於命名 Cloud Firestore 服務代理。如要查看服務代理名稱，請參閱「查看服務代理名稱」。

或者，您也可以使用 Google Cloud 控制台指派這個角色。

查看服務代理名稱

在 Google Cloud 控制台的「Import/Export」(匯入/匯出) 頁面中，您可以查看匯入和匯出作業用來授權要求的帳戶。您也可以查看資料庫使用的是 Cloud Firestore 服務代理，還是舊版 App Engine 服務帳戶。

1. 查看「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的授權帳戶。

服務代理需要 Cloud Storage bucket 的 Storage Admin 角色，才能用於匯出或匯入作業。

為專案設定 gcloud

您可以透過 Google Cloud 控制台或 gcloud 指令列工具，啟動匯入和匯出作業。如要使用 gcloud，請設定指令列工具，並透過下列任一方式連線至專案：

• 使用 Cloud Shell 透過 Google Cloud 控制台存取 gcloud。

  開始 Cloud Shell

  確認 gcloud 已設為正確的專案：

  gcloud config set project [PROJECT_ID]
  

• 安裝並初始化 Google Cloud SDK。

匯出資料

匯出作業會將資料庫中的文件複製到 Cloud Storage bucket 中的一組檔案。請注意，匯出作業並非在匯出開始時間擷取的確切資料庫快照。匯出作業可能會包含執行期間所做的變更。

匯出所有文件

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

匯出特定集合群組

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=reviews \
--database='cymbal'

從 PITR 時間戳記匯出

您可以從時間點復原資料將資料庫匯出至 Cloud Storage。您可以匯出 PITR 資料，時間戳記為過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記已無資料，匯出作業就會失敗。

PITR 匯出作業支援所有篩選器，包括匯出所有文件和匯出特定集合群組。

匯出 PITR 資料前，請注意下列事項：

• 請以 RFC 3339 格式指定時間戳記。例如：2023-05-26T10:20:00.00Z。
• 請確認您指定的時間戳記是過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記已無資料，系統會產生錯誤。
• 如果 PITR 匯出作業失敗，系統不會收取費用。

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

匯入資料

在 Cloud Storage 中取得匯出檔案後，您可以將這些檔案中的文件匯回專案，或匯入其他專案。關於匯入作業，請注意下列事項：

• 匯入資料時，系統會使用資料庫目前的索引定義更新必要索引。匯出項目不含索引定義。

• 匯入作業不會指派新的文件 ID。匯入作業會使用匯出時擷取的 ID。匯入文件時，系統會保留文件 ID，以免 ID 衝突。如果已有相同 ID 的文件，匯入作業會覆寫現有文件。

• 如果資料庫中的文件不受匯入作業影響，匯入後仍會保留在資料庫中。

• 匯入作業不會觸發 Cloud Functions。快照監聽器會接收與匯入作業相關的更新。

• 請勿新增匯出作業原始輸出檔案中沒有的新 Cloud Firestore 文件，也不要在匯入前從 GCS 檔案中移除任何現有文件。否則匯入作業會失敗。

• .overall_export_metadata 檔案名稱必須與其父項資料夾的名稱相符：

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  如果移動或複製匯出的輸出檔案，請將 PARENT_FOLDER_NAME 和 .overall_export_metadata 檔案名稱保持一致。

匯入匯出作業中的所有文件

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

匯入特定集合群組

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
  --database=[DATABASE]

匯入時間點復原匯出作業

按照「匯入所有文件」中的步驟匯入匯出的資料庫。如果資料庫中已有任何文件，系統會覆寫該文件。

管理匯出和匯入作業

啟動匯出或匯入作業後，Cloud Firestore 會為作業指派不重複的名稱。您可以使用作業名稱刪除、取消或檢查作業狀態。

作業名稱的前置字串為 projects/[PROJECT_ID]/databases/(default)/operations/，例如：

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

不過，為 describe、cancel 和 delete 指令指定作業名稱時，可以省略前置字元。

列出所有匯出和匯入作業

gcloud firestore operations list

查看作業狀態

gcloud firestore operations describe [OPERATION_NAME]

預估完成時間

要求長時間執行的作業狀態時，會傳回 workEstimated 和 workCompleted 指標。每項指標都會以位元組數和實體數傳回：

• workEstimated 會顯示作業預計處理的位元組和文件總數。如果無法預估，Cloud Firestore 可能會省略這項指標。

• workCompleted 顯示目前處理的位元組和文件數量。作業完成後，這個值會顯示實際處理的位元組和文件總數，可能大於 workEstimated 的值。

將 workCompleted 除以 workEstimated 可得出進度的粗估值。這項預估值可能不準確，因為取決於延遲的統計資料收集。

取消作業

gcloud firestore operations cancel [OPERATION_NAME]

取消執行中的作業並不會復原該作業。取消匯出作業後，已匯出的文件會保留在 Cloud Storage 中；取消匯入作業後，資料庫中已完成的更新會保留。您無法匯入部分完成的匯出作業。

刪除作業

使用 gcloud firestore operations delete 指令，從近期作業清單中移除作業。這個指令不會刪除 Cloud Storage 中的匯出檔案。

gcloud firestore operations delete [OPERATION_NAME]

匯出和匯入作業的計費與定價

您必須先為 Google Cloud 專案啟用計費功能，才能使用代管匯出和匯入服務。

匯出和匯入作業會依據 Cloud Firestore 定價中列出的費率，收取文件讀取和寫入費用。每匯出一份文件，匯出作業就會產生一項讀取作業。每匯入一份文件，匯入作業就會產生一項寫入作業。

儲存在 Cloud Storage 的輸出檔案會計入Cloud Storage 資料儲存費用。

匯出或匯入作業完成後，才會觸發Google Cloud預算快訊。匯出和匯入作業不會影響控制台用量部分顯示的用量。

查看匯出和匯入費用

匯出和匯入作業會將 goog-firestoremanaged:exportimport 標籤套用至計費作業。在 Cloud Billing 帳單報表頁面中，您可以使用這個標籤查看與匯入和匯出作業相關的費用：

匯出至 BigQuery

您可以將 Cloud Firestore 匯出作業中的資料載入 BigQuery，但前提是您已指定 collection-ids 篩選器。請參閱「從 Cloud Firestore 匯出作業載入資料」。

BigQuery 欄限制

BigQuery 規定每個資料表最多只能有 10,000 個資料欄。Cloud Firestore 匯出作業會為每個集合群組產生 BigQuery 資料表結構定義。在這個結構定義中，集合群組內的每個不重複欄位名稱都會成為結構定義資料欄。如果集合群組的 BigQuery 結構定義超過 10,000 欄，Cloud Firestore 匯出作業會將對應欄位視為位元組，嘗試將欄數控制在限制範圍內。如果轉換後資料欄數量低於 10,000，您就能將資料載入 BigQuery，但無法查詢對應欄位中的子欄位。如果資料欄數量仍超過 10,000，匯出作業就不會為集合群組產生 BigQuery 結構定義，您也無法將其資料載入 BigQuery。

匯出格式和中繼資料檔案

代管匯出作業的輸出內容會使用 LevelDB 記錄格式。

中繼資料檔案

匯出作業會為您指定的每個集合群組建立中繼資料檔案。中繼資料檔案通常名為 ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata。

中繼資料檔案是通訊協定緩衝區，您可以使用 protoc 通訊協定編譯器解碼。舉例來說，您可以解碼中繼資料檔案，判斷匯出檔案包含的集合群組：

protoc --decode_raw < export0.export_metadata

服務代理遷移

Cloud Firestore 會使用 Cloud Firestore 服務代理授權匯入和匯出作業，而非使用 App Engine 服務帳戶。服務代理和服務帳戶採用下列命名慣例：

Cloud Firestore 服務代理

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore 先前使用的是 App Engine 預設服務帳戶，而非 Cloud Firestore 服務代理。如果資料庫仍使用 App Engine 服務帳戶匯入或匯出資料，建議您按照本節的操作說明，改用 Cloud Firestore 服務代理。

App Engine 個服務帳戶

PROJECT_ID@appspot.gserviceaccount.com

建議使用 Cloud Firestore 服務代理，因為這是 Cloud Firestore 專用。App Engine 服務帳戶由多項服務共用。

查看授權帳戶

您可以前往 Google Cloud 控制台的「Import/Export」(匯入/匯出) 頁面，查看匯入和匯出作業使用哪個帳戶授權要求。您也可以查看資料庫是否已使用 Cloud Firestore 服務代理。

1. 前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

   前往「資料庫」

2. 從資料庫清單中選取所需資料庫。

3. 在導覽選單中，按一下「匯入/匯出」。

4. 查看「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的授權帳戶。

如果專案未使用 Cloud Firestore 服務代理，您可以使用下列任一技術，遷移至 Cloud Firestore 服務代理：

• 檢查並更新 Cloud Storage bucket 權限，藉此遷移專案 (建議做法)。
• 新增組織層級政策限制，影響組織內的所有專案。

建議採用第一種技術，因為這種技術會將影響範圍限制在單一 Cloud Firestore 專案。第二種技術不會遷移現有的 Cloud Storage bucket 權限，因此不建議使用。不過，這項服務會在組織層級提供安全性法規遵循。

檢查並更新 Cloud Storage bucket 權限，以便進行遷移

遷移程序包含兩個步驟：

1. 更新 Cloud Storage bucket 權限。詳情請參閱下節。
2. 確認遷移至 Cloud Firestore 服務代理。

服務代理值區權限

如果匯出或匯入作業使用「其他」專案中的 Cloud Storage bucket，您必須為該 bucket 授予 Cloud Firestore 服務代理權限。例如，將資料移至其他專案的作業需要存取該專案中的 bucket。否則，遷移至 Cloud Firestore 服務代理後，這些作業會失敗。

如果匯入和匯出工作流程都在同一個專案中，則不需變更權限。根據預設，Cloud Firestore 服務代理可以存取相同專案中的 bucket。

更新其他專案中 Cloud Storage bucket 的權限，將存取權授予 service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com 服務代理。將 Firestore Service Agent 角色授予服務代理。

Firestore Service Agent 角色會授予 Cloud Storage bucket 的讀取和寫入權限。如需僅授予讀取或寫入權限，請使用自訂角色。

下一節說明的遷移程序可協助您找出可能需要更新權限的 Cloud Storage bucket。

將專案遷移至 Firestore 服務代理

請完成下列步驟，從 App Engine 服務帳戶遷移至 Cloud Firestore 服務代理。遷移完成後即無法復原。

1. 前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

   前往「資料庫」

2. 從資料庫清單中選取所需資料庫。

3. 在導覽選單中，按一下「匯入/匯出」。

4. 如果專案尚未遷移至 Cloud Firestore 服務代理，您會看到說明遷移作業的橫幅和「Check Bucket Status」(檢查 bucket 狀態) 按鈕。下一步可協助您找出並修正潛在的權限錯誤。

   按一下「Check Bucket Status」(檢查值區狀態)。

   畫面上會顯示選單，其中包含完成遷移的選項和 Cloud Storage bucket 清單。清單可能需要幾分鐘才能載入完畢。

   這份清單包含最近用於匯入和匯出作業，但目前未授予 Cloud Firestore 服務代理讀取和寫入權限的 bucket。

5. 記下專案 Cloud Firestore 服務代理的主體名稱。服務代理名稱會顯示在「Service agent to give access to」(要授予存取權的服務代理) 標籤下方。

6. 針對清單中日後要用於匯入或匯出作業的任何 bucket，請完成下列步驟：

   1. 在值區的表格列中，按一下「修正」。 系統會在新分頁開啟該值區的權限頁面。

   2. 按一下 [新增]。
   3. 在「New principals」(新增主體) 欄位中，輸入 Cloud Firestore 服務代理程式的名稱。
   4. 在「Select a role」(選取角色) 欄位中，依序選取「Service Agents」(服務代理) >「Firestore Service Agent」(Firestore 服務代理)。
   5. 按一下 [儲存]。
   6. 返回 Cloud Firestore 匯入/匯出頁面的分頁。
   7. 對清單中的其他值區重複執行這些步驟。請務必查看清單的所有頁面。

7. 按一下「Migrate to Firestore Service Agent」(遷移至 Firestore 服務代理)。如果仍有 bucket 未通過權限檢查，請按一下「Migrate」(遷移) 確認遷移。

   遷移作業完成後，系統會發出快訊通知。遷移作業無法復原。

查看遷移狀態

如要確認專案的遷移狀態，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

   前往「資料庫」

2. 從資料庫清單中選取所需資料庫。

3. 在導覽選單中，按一下「匯入/匯出」。

4. 找到「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的主體。

   如果主體是 service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com，表示專案已遷移至 Cloud Firestore 服務代理。遷移作業無法復原。

   如果專案尚未遷移，頁面頂端會顯示橫幅，並附有「Check Bucket Status」(檢查 bucket 狀態) 按鈕。請參閱「遷移至 Firestore 服務代理」一文，完成遷移作業。

新增組織層級政策限制

• 在組織政策中設定下列限制：

  必須使用 Firestore 服務代理才能執行匯入/匯出工作 (firestore.requireP4SAforImportExport)。

  這項限制規定匯入和匯出作業必須使用 Cloud Firestore 服務代理授權要求。如要設定這項限制，請參閱「 建立及管理組織政策 」。

套用這項組織政策限制，並不會自動為 Cloud Firestore 服務代理授予適當的 Cloud Storage bucket 權限。

如果限制導致任何匯入或匯出工作流程發生權限錯誤，您可以停用限制，改回使用預設服務帳戶。檢查並更新 Cloud Storage bucket 權限後，即可再次啟用限制。