Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

導出和導入數據

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

您可以使用 Cloud Firestore 託管導出和導入服務從意外刪除的數據中恢復,並導出數據以供離線處理。您可以導出所有文檔或僅導出特定集合。同樣,您可以從導出中導入所有數據或僅導入特定集合。從一個 Cloud Firestore 數據庫導出的數據可以導入另一個 Cloud Firestore 數據庫。您還可以將Cloud Firestore 導出加載到 BigQuery中。

本頁面介紹如何使用託管導出和導入服務和Cloud Storage導出和導入 Cloud Firestore 文檔。 Cloud Firestore 託管導出和導入服務可通過gcloud命令行工具和 Cloud Firestore API( RESTRPC )獲得。

在你開始之前

在使用託管導出和導入服務之前,您必須完成以下任務:

  1. 為您的 Google Cloud 項目啟用結算功能。只有啟用了結算功能的 Google Cloud 項目才能使用導出和導入功能。
  2. Cloud Firestore 數據庫位置附近的位置為您的項目創建一個 Cloud Storage 存儲分區。您不能將請求者付款存儲桶用於導出和導入操作。
  3. 確保您的帳號擁有 Cloud Firestore 和 Cloud Storage 的必要權限。如果您是項目所有者,則您的帳戶具有所需的權限。否則,以下角色會授予導出和導入操作以及訪問 Cloud Storage 的必要權限:

默認服務帳號權限

每個 Google Cloud 項目都會自動創建一個名為PROJECT_ID @appspot.gserviceaccount.com的默認服務帳號。導出和導入操作使用此服務帳號來授權 Cloud Storage 操作。

您項目的默認服務帳號需要訪問在導出或導入操作中使用的 Cloud Storage 存儲分區。如果您的 Cloud Storage 存儲分區與 Cloud Firestore 數據庫位於同一項目中,則默認服務帳號默認有權訪問該存儲分區

如果 Cloud Storage 存儲分區位於另一個項目中,則您必須向默認服務帳號授予對 Cloud Storage 存儲分區的訪問權限。

服務帳號需要 Cloud Storage 存儲分區的Storage Admin角色才能用於導出或導入操作。

如果您禁用或刪除 App Engine 默認服務帳戶,您的 App Engine 應用將失去對 Cloud Firestore 數據庫的訪問權限。如果您禁用了 App Engine 服務帳戶,您可以重新啟用它,請參閱啟用服務帳戶。如果您在過去 30 天內刪除了 App Engine 服務帳戶,則可以恢復您的服務帳戶,請參閱取消刪除服務帳戶

為您的項目設置gcloud

您可以通過 Google Cloud Platform Console 或gcloud命令行工具啟動導入和導出操作。要使用gcloud ,請設置命令行工具並通過以下方式之一連接到您的項目:

導出數據

導出操作會將數據庫中的文檔複製到 Cloud Storage 存儲分區中的一組文件中。請注意,導出不是在導出開始時拍攝的精確數據庫快照。導出可能包括在操作運行時所做的更改。

導出所有文件

谷歌云控制台

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

    轉到導入/導出頁面

  2. 單擊導出

  3. 單擊導出整個數據庫選項。

  4. 選擇目標下方,輸入 Cloud Storage 存儲分區的名稱或使用瀏覽按鈕選擇一個存儲分區。

  5. 單擊導出

控制台返回導入/導出頁面。如果操作成功啟動,該頁面會在最近的導入和導出頁面中添加一個條目。失敗時,頁面會顯示錯誤消息。

使用firestore export命令導出數據庫中的所有文檔,將[BUCKET_NAME]替換為 Cloud Storage 存儲分區的名稱。添加--async標誌以防止gcloud工具等待操作完成。

gcloud firestore export gs://[BUCKET_NAME]

您可以通過在存儲桶名稱後添加文件前綴來組織導出,例如BUCKET_NAME/my-exports-folder/export-name 。如果您不提供文件前綴,則託管導出服務會根據當前時間戳創建一個。

啟動導出操作後,關閉終端不會取消操作,請參閱取消操作

導出特定集合

谷歌云控制台

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

    轉到導入/導出頁面

  2. 單擊導出

  3. 單擊導出一個或多個集合組選項。使用下拉菜單選擇一個或多個集合組。

  4. 選擇目標下方,輸入 Cloud Storage 存儲分區的名稱或使用瀏覽按鈕選擇一個存儲分區。

  5. 單擊導出

控制台返回導入/導出頁面。如果操作成功啟動,該頁面會在最近的導入和導出頁面中添加一個條目。失敗時,頁面會顯示錯誤消息。

要導出特定的集合組,請使用--collection-ids標誌。該操作僅導出具有給定集合 ID 的集合組。集合組包括具有指定集合 ID 的所有集合和子集合(在任何路徑)。

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文件名相同。

從導出中導入所有文檔

谷歌云控制台

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

    轉到導入/導出頁面

  2. 單擊導入

  3. 文件名字段中,輸入已完成導出操作的.overall_export_metadata文件的文件名。您可以使用瀏覽按鈕來幫助您選擇文件。

  4. 單擊導入

控制台返回導入/導出頁面。如果操作成功啟動,該頁面會在最近的導入和導出頁面中添加一個條目。失敗時,頁面會顯示錯誤消息。

使用firestore import命令從之前的導出操作中導入文檔。

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

其中[BUCKET_NAME][EXPORT_PREFIX]指嚮導出文件的位置。例如:

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

您可以在 Google Cloud Platform Console 的 Cloud Storage 瀏覽器中確認導出文件的位置:

打開雲存儲瀏覽器

一旦開始導入操作,關閉終端並不會取消操作,請參閱取消操作

導入特定集合

谷歌云控制台

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

要從一組導出文件中導入特定的集合組,請使用--collection-ids標誌。該操作僅導入具有給定集合 ID 的集合組。集合組包括具有指定集合 ID 的所有集合和子集合(在任何路徑)。

只有特定集合組的導出支持特定集合組的導入。您不能從所有文檔的導出中導入特定集合。

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

但是,在為describecanceldelete命令指定操作名稱時,您可以省略前綴。

列出所有導出和導入操作

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 導入/導出頁面中查看最近的導出和導入操作列表。

轉到導入/導出頁面

使用operations list命令查看所有正在運行和最近完成的導出和導入操作:

gcloud firestore operations list

檢查運行狀態

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 導入/導出頁面中查看最近導出或導入操作的狀態。

轉到導入/導出頁面

使用operations describe命令顯示導出或導入操作的狀態。

gcloud firestore operations describe [OPERATION_NAME]

估計完成時間

對長時間運行操作狀態的請求會返回指標workEstimatedworkCompleted 。這些指標中的每一個都以字節數和實體數返回:

  • workEstimated顯示操作將處理的估計總字節數和文檔。如果 Cloud Firestore 無法做出估計,它可能會忽略此指標。

  • workCompleted顯示到目前為止已處理的字節數和文檔數。操作完成後,該值顯示實際處理的字節和文檔總數,可能大於workEstimated的值。

workCompleted除以workEstimated以獲得粗略的進度估計。此估計可能不准確,因為它取決於延遲的統計信息收集。

取消操作

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 導入/導出頁面中取消正在運行的導出或導入操作。

轉到導入/導出頁面

最近的導入和導出表中,當前運行的操作在已完成列中包括一個取消按鈕。單擊取消按鈕停止操作。當操作完全停止時,該按鈕變為取消消息,然後變為取消

使用operations cancel命令停止正在進行的操作:

gcloud firestore operations cancel [OPERATION_NAME]

取消正在運行的操作不會撤消該操作。取消的導出操作將保留已在 Cloud Storage 中導出的文檔,取消的導入操作將保留已對您的數據庫進行的更新。您不能導入部分完成的導出。

刪除操作

使用gcloud firestore operations delete命令從最近操作列表中刪除操作。此命令不會從 Cloud Storage 中刪除導出文件。

gcloud firestore operations delete [OPERATION_NAME]

進出口業務的計費和定價

在使用託管導出和導入服務之前,您需要為您的 GCP 項目啟用結算功能。導出和導入操作按Cloud Firestore 定價中列出的費率收取文檔讀取和寫入費用。

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

查看進出口成本

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

從過濾器菜單訪問 goog-firestoremanaged 標籤。

導出到 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 服務代理來授權導入和導出操作,而不是使用 App Engine 服務帳號。服務代理和服務帳戶使用以下命名約定:

Cloud Firestore 服務代理
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
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 label 旁邊的授權帳戶。

如果您的項目不使用 Cloud Firestore 服務代理,您可以使用以下任一技術遷移到 Cloud Firestore 服務代理:

這些技術中的第一個更可取,因為它將影響範圍本地化到單個 Cloud Firestore 項目。第二種技術不是首選,因為它不會遷移現有的 Cloud Storage 存儲分區權限。但是,它確實提供了組織級別的安全合規性。

通過檢查和更新 Cloud Storage 存儲分區權限進行遷移

遷移過程有兩個步驟:

  1. 更新 Cloud Storage 存儲分區權限。有關詳細信息,請參閱以下部分。
  2. 確認遷移到 Cloud Firestore 服務代理。

服務代理存儲桶權限

對於在另一個項目中使用 Cloud Storage 存儲分區的任何導出或導入操作,您必須授予 Cloud Firestore 服務代理對該存儲分區的權限。例如,將數據移動到另一個項目的操作需要訪問另一個項目中的存儲桶。否則,這些操作在遷移到 Cloud Firestore 服務代理後會失敗。

位於同一項目中的導入和導出工作流不需要更改權限。默認情況下,Cloud Firestore 服務代理可以訪問同一項目中的存儲分區。

從其他項目更新 Cloud Storage 存儲分區的權限,以授予對 service 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 中的Cloud Firestore 導入/導出頁面。

    轉到導入/導出

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

    單擊檢查存儲桶狀態

    將顯示一個菜單,其中包含完成遷移的選項和 Cloud Storage 存儲分區列表。列表可能需要幾分鐘才能完成加載。

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

  3. 記下項目的 Cloud Firestore 服務代理的主體名稱。服務代理名稱出現在服務代理下方以授予對標籤的訪問權限
  4. 對於列表中您將用於未來導入或導出操作的任何存儲桶,請完成以下步驟:

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

    2. 單擊添加
    3. New principals字段中,輸入您的 Cloud Firestore 服務代理的名稱。
    4. 選擇角色字段中,選擇服務代理 > Firestore 服務代理
    5. 單擊保存
    6. 返回到 Cloud Firestore 導入/導出頁面的選項卡。
    7. 對列表中的其他存儲桶重複這些步驟。確保查看列表的所有頁面。
  5. 單擊遷移到 Firestore 服務代理。如果您仍有未通過權限檢查的存儲桶,您需要通過單擊Migrate來確認您的遷移。

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

查看遷移狀態

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

    轉到導入/導出

  2. Import/Export jobs run as label 旁邊查找主體。

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

    如果項目尚未遷移,則頁面頂部會顯示一個橫幅,其中包含檢查存儲桶狀態按鈕。請參閱遷移到 Firestore 服務代理以完成遷移。

添加組織範圍的策略約束

  • 在組織的策略中設置以下約束:

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

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

應用此組織政策限制不會自動為 Cloud Firestore 服務代理授予相應的 Cloud Storage 存儲分區權限。

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