導出和導入數據

您可以使用 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 存儲桶。您不能將 Requester Pays 存儲桶用於導出和導入操作。

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. 查看Import/Export jobs run as標籤旁邊的授權帳戶。

服務代理需要 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]

導出特定集合

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

導入數據

在 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]/

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

導入特定集合

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

管理進出口業務

在您開始導出或導入操作後，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 定價中列出的費率對文檔讀取和寫入收費。

進出口業務的成本不計入您的支出限額。導出或導入操作在完成之前不會觸發您的Google Cloud 預算警報。同樣，在導出或導入操作期間執行的讀取和寫入會在操作完成後應用於您的每日配額。導出和導入操作不會影響控制台使用部分中顯示的使用情況。

查看進出口成本

導出和導入操作將goog-firestoremanaged:exportimport標籤應用於計費操作。在Cloud Billing 報告頁面中，您可以使用此標籤查看與導入和導出操作相關的成本：

導出到 BigQuery

您可以將數據從 Cloud Firestore 導出加載到 BigQuery，但前提是您指定了collection-ids過濾器。請參閱從 Cloud Firestore 導出加載數據。

BigQuery 列限制

BigQuery 對每個表施加了 10,000 列的限制。 Cloud Firestore 導出操作為每個收集組生成一個 BigQuery 表架構。在此架構中，集合組中的每個唯一字段名稱都成為一個架構列。

如果集合組的 BigQuery 架構超過 10000 列，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 中的Cloud Firestore 導入/導出頁面。

   轉到導入/導出

2. 查看Import/Export jobs run as標籤旁邊的授權帳戶。

如果您的項目不使用 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 Service Agent

完成以下步驟以從 App Engine 服務帳戶遷移到 Cloud Firestore 服務代理。一旦完成，遷移就無法撤消。

1. 轉到 Google Cloud Platform Console 中的Cloud Firestore 導入/導出頁面。

   轉到導入/導出

2. 如果您的項目尚未遷移到 Cloud Firestore 服務代理，您會看到一個描述遷移的橫幅和一個檢查存儲桶狀態按鈕。下一步可幫助您​​識別和修復潛在的權限錯誤。

   單擊檢查存儲桶狀態。

   出現一個菜單，其中包含完成遷移的選項和 Cloud Storage 存儲桶列表。列表可能需要幾分鐘才能完成加載。

   此列表包括最近在導入和導出操作中使用過但目前未向 Cloud Firestore 服務代理授予讀取和寫入權限的存儲桶。

3. 記下項目的 Cloud Firestore 服務代理的主體名稱。服務代理名稱顯示在服務代理下方以授予對標籤的訪問權限。

4. 對於列表中您將用於未來導入或導出操作的任何存儲桶，請完成以下步驟：

   1. 在此存儲桶的表行中，單擊Fix 。這會在新選項卡中打開該存儲桶的權限頁面。

   2. 單擊添加。
   3. 在新委託人字段中，輸入您的 Cloud Firestore 服務代理的名稱。
   4. 在選擇角色字段中，選擇服務代理 > Firestore 服務代理。
   5. 單擊保存。
   6. 返回帶有 Cloud Firestore 導入/導出頁面的選項卡。
   7. 對列表中的其他存儲桶重複這些步驟。確保查看列表的所有頁面。

5. 單擊遷移到 Firestore 服務代理。如果您仍然有未通過權限檢查的存儲桶，則需要通過單擊Migrate來確認您的遷移。

   遷移完成時會有警報通知您。遷移無法撤消。

查看遷移狀態

1. 要驗證項目的遷移狀態，請轉到 Google Cloud Platform Console 中的導入/導出頁面：

   轉到導入/導出

2. 在作為標籤運行的導入/導出作業旁邊查找主體。

   如果委託人是service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com ，那麼您的項目已經遷移到 Cloud Firestore 服務代理。遷移無法撤消。

   如果項目尚未遷移，頁面頂部會出現一個帶有檢查存儲桶狀態按鈕的橫幅。請參閱遷移到 Firestore 服務代理以完成遷移。

添加組織範圍的策略約束

• 在您的組織策略中設置以下限制：

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

  此約束要求導入和導出操作使用 Cloud Firestore 服務代理來授權請求。要設置此約束，請參閱創建和管理組織策略。

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

如果約束為任何導入或導出工作流創建權限錯誤，您可以禁用它以返回使用默認服務帳戶。檢查並更新 Cloud Storage 存儲桶權限後，您可以再次啟用約束。