匯出及匯入資料

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

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

事前準備

您必須先完成下列步驟，才能使用匯出與匯入代管服務：

1. 為 Google Cloud 專案啟用結帳功能。只有啟用計費功能的 Google Cloud 專案才能使用匯出和匯入功能。
2. 為專案建立 Cloud Storage 值區，位置應靠近 Cloud Firestore 資料庫位置。匯出與匯入作業不適用於要求者付費值區。

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 值區。如果 Cloud Storage 值區與 Cloud Firestore 資料庫皆屬同一個專案，Cloud Firestore 服務代理就能根據預設存取該值區。

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

為服務代理指派角色

您可以使用 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. 查看「匯入/匯出工作執行身分」標籤旁的授權帳戶。

服務代理需要 Storage Admin 角色，才能使用 Cloud Storage 值區進行匯出或匯入作業。

為專案設定 gcloud

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

• 使用 Cloud Shell 從 Google Cloud Platform 主控台存取 gcloud。

  啟動 Cloud Shell

  確保將 gcloud 設定為正確的專案：

  gcloud config set project [PROJECT_ID]
  

• 安裝並初始化 Google Cloud SDK。

匯出資料

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

匯出所有文件

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

匯出特定集合

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

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

從 PITR 時間戳記匯出

您可以使用 gcloud firestore export 指令，將資料庫從 PITR 資料匯出至 Cloud Storage。您可以匯出時間戳記為過去七天內整分鐘時間戳記的 PITR 資料，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，匯出作業就會失敗。

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

1. 匯出資料庫，並將 snapshot-time 參數指定為所需的復原時間戳記。

   gcloud

   執行下列指令，將資料庫匯出至您的值區。

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   其中

   • PITR_TIMESTAMP：以分鐘為單位的 PITR 時間戳記，例如 2023-05-26T10:20:00.00Z。

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

   • 請使用 RFC 3339 格式指定時間戳記。例如：2020-09-01T23:59:30.234233Z。
   • 請確認您指定的時間戳記是過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記時資料已不存在，系統會產生錯誤。
   • 系統不會向您收取 PITR 匯出作業失敗的費用。

匯入資料

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

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

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

• 如果資料庫中的文件沒有受到匯入影響，則匯入後仍會保留在資料庫中。

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

• .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_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

匯入 PITR 匯出內容

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

管理匯出和匯入作業

開始匯出或匯入作業後，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 控制台的「資料庫」頁面。

   前往「資料庫」

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

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

4. 查看「匯入/匯出工作執行身分」標籤旁的授權帳戶。

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

• 檢查並更新 Cloud Storage bucket 權限 (建議做法)，以便遷移專案。
• 新增機構全體政策限制，影響機構內的所有專案。

第一種方法較佳，因為它可將效果範圍局限於單一 Cloud Firestore 專案。不建議使用第二種方法，因為它不會遷移現有的 Cloud Storage 值區權限。不過，它會在機構層級提供安全性法規遵循功能。

檢查及更新 Cloud Storage 值區權限，以便遷移

遷移程序分為兩個步驟：

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

服務代理值區權限

對於在其他專案中使用 Cloud Storage 值區的任何匯出或匯入作業，您必須授予該值區的 Cloud Firestore 服務代理程式權限。舉例來說，將資料移至其他專案的作業需要存取該專案中的值區。否則，這些作業在遷移至 Cloud Firestore 服務代理後會失敗。

只要匯入和匯出的工作流程仍在同一個專案中，就不需要變更權限。根據預設，Cloud Firestore 服務代理可存取同一個專案中的資料夾。

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

Firestore Service Agent 角色會授予 Cloud Storage 值區的讀取和寫入權限。如果您只需要授予讀取或寫入權限，請使用自訂角色。

下文所述的遷移程序可協助您找出可能需要更新權限的 Cloud Storage 桶。

將專案遷移至 Firestore 服務代理人

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

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

   前往「資料庫」

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

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

4. 如果您的專案尚未遷移至 Cloud Firestore 服務代理程式，您會看到說明遷移作業的橫幅，以及「Check Bucket Status」按鈕。接下來，我們將說明如何找出並修正潛在的權限錯誤。

   按一下「查看值區狀態」。

   系統會顯示選單，其中包含完成遷移作業的選項，以及 Cloud Storage 值區的清單。清單可能需要幾分鐘才能完成載入。

   這份清單列出最近在匯入和匯出作業中使用的值區，但目前尚未授予 Cloud Firestore 服務代理人讀取和寫入權限。

5. 請記下專案 Cloud Firestore 服務代理人的主要名稱。服務代理名稱會顯示在「應授予存取權的服務代理」標籤下方。

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

   1. 在這個值層的資料表列中，按一下「修正」。 系統會在新分頁中開啟該儲存桶的權限頁面。

   2. 按一下 [新增]。
   3. 在「New principals」欄位中輸入 Cloud Firestore 服務代理人的名稱。
   4. 在「Select a role」欄位中，依序選取「Service Agents」>「Firestore Service Agent」。
   5. 按一下 [儲存]。
   6. 返回含有 Cloud Firestore「匯入/匯出」頁面的分頁。
   7. 針對清單中的其他區隔重複上述步驟。請務必查看清單的所有頁面。

7. 按一下「Migrate to Firestore Service Agent」。如果仍有權限檢查失敗的值區，請按一下「Migrate」確認遷移作業。

   系統會在遷移作業完成後通知您。遷移作業無法復原。

查看遷移狀態

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

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

   前往「資料庫」

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

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

4. 請查看「Import/Export jobs run as」標籤旁的「Principal」(主要)。

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

   如果專案尚未遷移，頁面頂端會顯示橫幅，並提供「檢查資料集狀態」按鈕。請參閱遷移至 Firestore 服務代理人，完成遷移作業。

新增全機構政策限制

• 在貴機構的政策中設定下列限制：

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

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

套用這項機構政策限制不會自動為 Cloud Firestore 服務代理授予適當的 Cloud Storage 值區權限。

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