導出和導入數據

您可以使用 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 儲存桶。您不能使用請求者付款儲存桶進行匯出和匯入操作。

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命令列工具來指派下列角色之一。例如，要將儲存管理員角色指派給 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 服務代理程式。若要查看服務代理名稱，請參閱查看服務代理名稱。

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

查看服務代理名稱

您可以從 Google Cloud Platform Console 中的匯入/匯出頁面查看匯入和匯出操作用於授權請求的帳戶。您也可以檢視您的資料庫是使用 Cloud Firestore 服務代理程式還是舊版 App Engine 服務帳號。

1. 查看作為標籤執行的匯入/匯出作業旁邊的授權帳戶。

服務代理需要 Cloud Storage 儲存桶的Storage Admin角色才能用於匯出或匯入操作。

為您的專案設定gcloud

您可以透過 Google Cloud Platform Console 或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 數據，其中時間戳記是過去 7 天內的整分鐘時間戳，但不能早於earliestVersionTime 。如果指定時間戳不再存在數據，則匯出操作失敗。

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

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

   雲雲

   執行以下命令將資料庫匯出到您的儲存桶。

   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 。
   • 確保您指定的時間戳記是過去 7 天內的整分鐘時間戳，但不早於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 Platform Console 中的匯入/匯出頁面查看您的匯入和匯出操作使用哪個帳戶來授權請求。您也可以查看您的資料庫是否已使用 Cloud Firestore 服務代理程式。

1. 在 Google Cloud Platform Console 中，前往資料庫頁面。

   前往資料庫

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

3. 在導覽功能表中，按一下匯入/匯出。

4. 查看作為標籤執行的匯入/匯出作業旁邊的授權帳戶。

如果您的專案不使用 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 中，前往資料庫頁面。

   前往資料庫

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

3. 在導覽功能表中，按一下匯入/匯出。

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 中，前往資料庫頁面。

   前往資料庫

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

3. 在導覽功能表中，按一下匯入/匯出。

4. 尋找作為標籤執行的匯入/匯出作業旁邊的主體。

   如果委託人是service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com ，則您的專案已移至 Cloud Firestore 服務代理程式。遷移無法撤銷。

   如果項目尚未遷移，頁面頂部會出現一個橫幅，其中包含「檢查儲存桶狀態」按鈕。請參閱遷移至 Firestore 服務代理程式以完成移轉。

新增組織範圍的策略約束

• 在您的組織的策略中設定以下約束：

  需要 Firestore 服務代理程式進行匯入/匯出( firestore.requireP4SAforImportExport )。

  此限制要求匯入和匯出操作才能使用 Cloud Firestore 服務代理程式來授權請求。若要設定此約束，請參閱建立和管理組織策略。

應用此組織策略限制不會自動為 Cloud Firestore 服務代理程式授予適當的 Cloud Storage 儲存桶權限。

如果該約束對任何匯入或匯出工作流程造成權限錯誤，您可以停用它以傳回使用預設服務帳戶。檢查並更新 Cloud Storage 儲存桶權限後，您可以再次啟用該約束。