匯出及匯入資料

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

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

事前準備

您必須先完成 幾項工作：

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 Cloud Storage 也提供目錄同步處理功能 方便您同步處理 VM 目錄與值區

為服務代理指派角色

您可以使用 gsutil 指令列工具指派下列其中一種角色。舉例來說，如要指派「儲存空間管理員」角色 執行下列指令：

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

將 PROJECT_NUMBER 替換成您的專案編號。 可用來命名 Cloud Firestore 服務代理。如何查看 服務代理名稱，請參閱「查看服務代理名稱」一節。

或者也可以使用 GCP Console 指派此角色。

查看服務代理名稱

您可以查看匯入和匯出作業用來授權的帳戶 Google Cloud Platform Console 的「Import/Export」頁面。你也可以 查看資料庫是否使用 Cloud Firestore 服務代理或舊版 App Engine 服務帳戶

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

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

為專案設定 gcloud

您可以透過 Google Cloud Platform 控制台或 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) 時間戳記匯出

您可以從 PITR 資料將資料庫匯出至 Cloud Storage 搜尋 gcloud firestore export 指令您可以匯出時間點復原資料，時間戳記是指時間戳記在 過去 7 天，但早於 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：以分鐘為單位的時間點復原時間戳記，例如 2023-05-26T10:20:00.00Z。

   匯出時間點復原資料前，請注意下列事項：

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

匯入資料

將檔案匯出至 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 Platform Console 的「Import/Export」頁面。你也可以 查看資料庫是否已使用 Cloud Firestore 服務代理。

1. 在 Google Cloud Platform Console 中，前往「Databases」頁面。

   前往「資料庫」頁面

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

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

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

如果專案未使用 Cloud Firestore 服務代理， 可以使用 Cloud Firestore 服務代理，將資料遷移至 Cloud Firestore 服務代理 這些技巧：

• 檢查及更新 Cloud Storage 值區權限來遷移專案 (建議做法)。
• 新增全機構的政策限制，該限制會影響下列專案中的所有專案 機構。

我們建議採用第一種技術，因為能將 單一 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 Platform Console 中，前往「Databases」頁面。

   前往「資料庫」頁面

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

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

4. 如果專案尚未遷移至 Cloud Firestore 服務 代理程式會看到內含遷移作業的橫幅 「檢查值區狀態」按鈕。下一步將協助您找出 修正潛在的權限錯誤。

   點選「檢查值區狀態」。

   系統隨即會顯示選單，提供完成遷移的選項和 Cloud Storage 值區清單這項作業會在幾分鐘內 即可完成載入清單

   這份清單包含最近曾查看的值區 用於匯入和匯出作業，但目前不提供讀取和 寫入 Cloud Firestore 服務代理。

5. 記下專案的 Cloud Firestore 主體名稱 服務代理。服務代理名稱會顯示在 「用來授予標籤存取權的服務代理」標籤。

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

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

   2. 按一下「新增」。
   3. 在「新增主體」欄位中輸入名稱 Cloud Firestore 服務代理。
   4. 在「請選擇角色」欄位中，選取 服務代理 >Firestore 服務代理。
   5. 按一下 [儲存]。
   6. 返回「Cloud Firestore 匯入/匯出」頁面。
   7. 針對清單中的其他值區重複上述步驟。請務必查看 列出的所有網頁。

7. 按一下「遷移至 Firestore 服務代理」。如果發生以下情況： 含有未通過權限檢查的值區 只要按一下「遷移」，即可確認遷移作業。

   遷移完成時，您會收到通知。無法進行遷移作業 已復原。

查看遷移狀態

如何驗證專案的遷移狀態：

1. 在 Google Cloud Platform Console 中，前往「Databases」頁面。

   前往「資料庫」頁面

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

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

4. 在「匯入/匯出工作執行身分」標籤旁找出主體。

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

   如果專案尚未遷移，頁面頂端會顯示橫幅 系統隨即會顯示「檢查值區狀態」按鈕。詳情請見 遷移至 Firestore 服務代理 以完成遷移

新增整個機構的政策限制

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

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

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

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

如果限制會導致任何匯入或匯出工作流程發生權限錯誤， 您可以停用這項功能，改回使用預設服務帳戶 請先檢查及更新 Cloud Storage 值區 權限，您可以再次啟用限制。