匯入及匯出資料

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

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

事前準備

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

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

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

服務代理權限

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

Firestore 服務代理
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

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

Firestore 服務代理需要存取匯出或匯入作業所用的 Cloud Storage 值區。根據預設，如果您的 Cloud Storage 值區與 Firestore 資料庫皆屬同一個專案，Firestore 服務代理即可存取該值區。

如果 Cloud Storage 值區在另一個專案中，則必須授予 Firestore 服務代理對 Cloud Storage 值區的存取權。

指派角色給服務代理

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

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

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

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

查看服務代理名稱

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

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

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

為專案設定 gcloud

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

匯入資料

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

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

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

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

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

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

    如果移動或複製匯出檔案，請保持 PARENT_FOLDER_NAME 和 .overall_export_metadata 檔案名稱相同。

  • 從匯出檔案匯入與 MongoDB 相容的 Firestore 資料庫時，如果匯出檔案包含子集合，匯入作業會失敗，因為與 MongoDB 相容的 Firestore 不支援子集合。

  • 從含有 BSON 類型的匯出內容匯入 Firestore Standard 版資料庫時會失敗，因為 Firestore Standard 版不支援 BSON 類型。

  • 匯入與 MongoDB 相容的 Firestore 資料庫時，無法匯入非預設命名空間 (Datastore API) 的資料。

    如果資料檔案包含非預設命名空間，只有在匯出作業包含預設命名空間的 --namespace-ids 篩選條件時，才能將資料匯入與 MongoDB 相容的 Firestore 資料庫。系統只會匯入預設命名空間的資料。

從匯出內容匯入所有文件

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

  4. 按一下「匯入」。

  5. 在「Filename」(檔案名稱) 欄位中，輸入已完成匯出作業的 .overall_export_metadata 檔案名稱。你可以使用「瀏覽」按鈕選取檔案。

  6. 按一下「匯入」。

控制台會返回「匯入/匯出」頁面。如果作業順利開始，頁面會將項目新增至「近期匯入和匯出」頁面。如果失敗，頁面會顯示錯誤訊息。

gcloud

使用 firestore import 指令，從先前的匯出作業匯入文件。

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

更改下列內容：

  • BUCKET_NAME/EXPORT_PREFIX：匯出檔案的位置。

  • DATABASE：資料庫名稱。

例如：

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

您可以在 Google Cloud 控制台的 Cloud Storage 瀏覽器中，確認匯出檔案的位置：

開啟 Cloud Storage 瀏覽器

開始匯入作業後，關閉終端機不會取消作業，請參閱取消作業。

匯入特定集合

Google Cloud Console

您無法在控制台中選取特定集合。請改用 gcloud。

gcloud

如要從一組匯出檔案匯入特定集合，請使用 --collection-ids 標記。這項作業只會匯入具有指定集合 ID 的集合。使用 --database 旗標指定資料庫名稱。

只有匯出特定集合時，才能匯入特定集合。您無法從所有文件的匯出項目中，匯入特定集合。

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

從包含 PITR 資料的匯出檔案匯入

按照「匯入所有文件」或「匯入特定集合」一節中的步驟，匯入 PITR 資料。如果資料庫中已有任何文件，系統會覆寫這些文件。

匯出資料

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

匯出所有文件

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

  4. 按一下 [匯出]。

  5. 按一下「匯出整個資料庫」選項。

  6. 選取「匯出資料庫目前狀態」，匯出目前的資料。

  7. 在「目的地」部分，輸入 Cloud Storage bucket 的名稱，或使用「瀏覽」按鈕選取 bucket。

  8. 按一下 [匯出]。

控制台會返回「匯入/匯出」頁面。如果作業順利開始，頁面會將項目新增至「近期匯入和匯出」頁面。如果失敗，頁面會顯示錯誤訊息。

gcloud

使用 firestore export 指令匯出資料庫中的所有文件，並將 [BUCKET_NAME] 替換為 Cloud Storage bucket 名稱。加上 --async 旗標，避免 gcloud 工具為了等待作業完成而停頓。

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

更改下列內容：

  • BUCKET_NAME：在 bucket 名稱後方新增檔案前置字串，即可整理匯出內容，例如 BUCKET_NAME/my-exports-folder/export-name。如未提供檔案前置字元，代管匯出服務會根據目前的時間戳記建立前置字元。

  • DATABASE：要匯出文件的資料庫名稱。

匯出作業開始後，關閉終端機不會取消作業，請參閱「取消作業」。

匯出特定集合

Google Cloud Console

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

  4. 按一下 [匯出]。

  5. 按一下「匯出一或多個集合群組」選項。使用下拉式選單選取一或多個集合。

  6. 選取「匯出資料庫目前狀態」，匯出目前的資料。

  7. 在「目的地」部分，輸入 Cloud Storage bucket 的名稱，或使用「瀏覽」按鈕選取 bucket。

  8. 按一下 [匯出]。

控制台會返回「匯入/匯出」頁面。如果作業順利開始，頁面會將項目新增至「近期匯入和匯出」頁面。如果失敗，頁面會顯示錯誤訊息。

gcloud

如要匯出特定集合，請使用 --collection-ids 旗標。這項作業只會匯出具有指定集合 ID 的集合。

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

舉例來說，您可以在 foo 資料庫中設計 restaurants 集合，納入 ratings、reviews 或 outlets 等其他集合。如要匯出特定集合 restaurants 和 reviews，指令如下所示：

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

從 PITR 時間戳記匯出

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

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

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

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

控制台

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」
  2. 從資料庫清單中選取資料庫。
  3. 按一下導覽選單中的「匯入/匯出」。
  4. 按一下 [匯出]。
  5. 設定匯出來源，匯出整個資料庫或僅匯出特定集合。

  6. 在「選擇要匯出的資料庫狀態」部分，選取「從較早的時間點匯出」。

    選取要用於匯出的快照時間

  7. 在「目的地」專區中，輸入 Cloud Storage 值區名稱，或使用「瀏覽」按鈕選取值區。

  8. 按一下 [匯出]。

    控制台會返回「匯入/匯出」頁面。如果作業順利開始，頁面會將項目新增至「近期匯入和匯出」頁面。如果失敗，頁面會顯示錯誤訊息。

gcloud

您可以使用 gcloud firestore export 指令，從 PITR 資料將資料庫匯出至 Cloud Storage。

匯出資料庫，並將 snapshot-time 參數指定為復原時間戳記。執行下列指令，將資料庫匯出至 bucket。

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

其中 PITR_TIMESTAMP 是精細程度為分鐘的 PITR 時間戳記，例如 2023-05-26T10:20:00.00Z。

新增 --collection-ids 旗標，匯出特定集合。

管理匯出和匯入作業

開始匯出或匯入作業後，與 MongoDB 相容的 Firestore 會為作業指派專屬名稱。您可以使用作業名稱刪除、取消或檢查作業狀態。

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

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

列出所有匯出和匯入作業

Google Cloud Console

您可以在 Google Cloud 控制台的「匯入/匯出」頁面中，查看最近的匯出和匯入作業清單。

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

gcloud

使用 operations list 指令查看所有執行中和最近完成的匯出及匯入作業：

gcloud firestore operations list

檢查作業狀態

Google Cloud Console

您可以在 Google Cloud 控制台的「匯入/匯出」頁面中，查看最近匯出或匯入作業的狀態。

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

gcloud

使用 operations describe 指令顯示匯出或匯入作業的狀態。

gcloud firestore operations describe [OPERATION_NAME]

估算完成時間

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

  • workEstimated 會顯示作業將要處理的位元組總數和文件總數預估值。如果無法估算，與 MongoDB 相容的 Firestore 可能會省略這項指標。

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

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

取消作業

Google Cloud Console

您可以在 Google Cloud 控制台的「匯入/匯出」頁面中，取消正在執行的匯出或匯入作業。

  1. 前往 Google Cloud 控制台的「Databases」頁面。

    前往「資料庫」

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

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

在「最近的匯入和匯出作業」表格中，目前執行的作業會在「已完成」欄中顯示「取消」按鈕。按一下「取消」按鈕即可停止作業。作業完全停止後，按鈕會先顯示「正在取消」訊息，然後顯示「已取消」。

主控台的「近期匯入和匯出」表格顯示正在進行的資料匯入作業，並提供「取消」選項來停止作業。

gcloud

使用 operations cancel 指令停止進行中的作業：

gcloud firestore operations cancel [OPERATION_NAME]

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

刪除作業

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

gcloud firestore operations delete [OPERATION_NAME]

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

使用代管匯出與匯入服務前，您需要先為 Google Cloud 專案啟用計費功能。

系統會依據 與 MongoDB 相容的 Firestore 定價，向您收取匯出與匯入作業的讀取單位和寫入單位費用。

儲存在 Cloud Storage 中的輸出檔案，會計入您的 Cloud Storage 資料儲存空間費用。

待匯出或匯入作業完成後，系統才會發出關於Google Cloud 預算的提醒。匯出和匯入作業不會影響控制台使用情況部分顯示的使用量。

查看匯出和匯入費用

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

從篩選器選單存取 goog-firestoremanaged 標籤。

匯出至 BigQuery

您可以將 Firestore with MongoDB compatibility 匯出資料載入 BigQuery，但前提是您已指定 collection-ids 篩選器。請參閱「從與 MongoDB 相容的 Firestore 匯出檔案載入資料」。

將與 MongoDB 相容的 Firestore 資料載入 BigQuery 時，BSON 資料類型會以 STRING 資料類型表示。

BigQuery 資料欄限制

BigQuery 對每個資料表設有 10,000 個資料欄的限制。與 MongoDB 相容的 Firestore 匯出作業會為每個集合產生 BigQuery 資料表結構定義。在這個架構中，集合中的每個不重複欄位名稱都會成為架構資料欄。

如果集合的 BigQuery 結構定義超過 10,000 個資料欄，Firestore with MongoDB compatibility 的匯出作業會將對應欄位視為位元組，盡量不超過資料欄限制。如果轉換後欄數少於 10,000，您就可以將資料載入 BigQuery，但無法查詢對應欄位中的子欄位。如果欄數仍超過 10,000，匯出作業就不會為集合產生 BigQuery 結構定義，您也無法將資料載入 BigQuery。

匯出格式和中繼資料檔案

代管匯出項目輸出內容採用 LevelDB 記錄檔格式。

中繼資料檔案

在匯出作業中，會建立每個指定集合的中繼資料檔案。中繼資料檔案名稱通常是 ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata。

中繼資料檔案為通訊協定緩衝區，可透過 protoc 通訊協定編譯器進行解碼。舉例來說，您可以將中繼資料檔案解碼，判斷匯出檔案中包含的集合：

protoc --decode_raw < export0.export_metadata