匯出與匯入實體

本頁將說明如何透過匯出與匯入代管服務來匯出及匯入 Cloud Firestore (Datastore 模式) 實體。匯出與匯入代管服務可以透過 gcloud 指令工具及 Cloud Datastore Admin API (RESTRPC) 來使用。

有了匯出與匯入代管服務,您可以還原誤刪的資料,也能夠匯出資料用以進行離線處理。您可以選擇匯出所有實體,或是只匯出特定種類的實體。同樣的,您也可以匯入某個匯出項目中的所有資料,或是只匯入特定的類別。當您使用匯出與匯入代管服務時,應考量下列要點:

  • 匯出服務使用最終一致性讀取。您不能假設匯出在一個單一時間點發生。該匯出項目能夠包含匯出開始後寫入的實體並且不會包含匯出開始前寫入的實體。

  • 匯出項目不包含任何索引。當您匯入資料時,系統會使用您資料庫現行的索引定義自動重建所需索引。個別實體屬性值索引設定會被匯出並在匯入作業期間發揮其作用。

  • 匯入項目不會為實體分配新的 ID。匯入會使用匯出時存在的 ID,並覆寫具有相同 ID 的任何現有實體。 匯入時,ID 將會在實體被匯入的期間被保留。如果在匯入作業執行時啟用了寫入,則此功能可防止與新實體的 ID 衝突。

  • 若您資料庫中的實體沒有受到匯入影響,則匯入後將會保留在資料庫中。

  • 從 Datastore 模式資料庫匯出的資料可以匯入到另一個 Datastore 模式資料庫中,即使其中一個資料庫在其他專案中亦是如此。

  • 代管匯出匯入服務目前限制並行作業數量上限為 50 項,並且允許一個專案每分鐘最多 20 個匯出和匯入要求。

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

事前準備

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

  1. 確保您的 Google Cloud Platform 專案有啟用計費服務。只有啟用計費服務的 GCP 專案才能使用匯出及匯入功能。如需瞭解計費相關資訊,請參閱匯入匯出的計費及定價

  2. 使用與 Cloud Firestore (Datastore 模式) 資料庫位置相同的位置,為專案建立 Cloud Storage 值區。匯出及匯入功能全都必須使用 Cloud Storage,並且您的 Cloud Storage 值區和 Cloud Firestore (Datastore 模式) 資料庫必須使用同一個位置。匯出與匯入作業不適用於要求者付費值區。

  3. 指派一 IAM 角色至您的使用者帳戶,若您要匯出資料,為其授予 datastore.databases.export 權限;若您要匯入資料,則授予 datastore.databases.import 權限。例如 Cloud Datastore Import Export Admin 角色則是兩方皆有授權。

  4. 指派一個能授權您 Cloud Storage 值區讀取或寫入權限的 Cloud Storage IAM 角色至您的使用者帳戶。

設定環境

在您執行匯出或匯入作業之前,您必須先為 gcloud 工具設定環境變數,並且以您的使用者帳戶進行驗證。

  1. 設定您的 GCP 專案 ID 為環境變數。

    PROJECT_ID="YOUR_PROJECT_ID"
    
  2. 以此變數將您的專案設定至 gcloud 工具使用中的配置。

    gcloud config set project ${PROJECT_ID}
    
  3. 使用 gcloud 工具進行驗證。

    gcloud auth login
    
  4. 設定您的 Cloud Storage 值區 ID 為環境變數。

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    其中 YOUR_BUCKET_NAME 是 Cloud Storage 值區的名稱,而 NAMESPACE_PATH 是可以選用的 Cloud Storage 命名空間路徑 (非 Datastore 模式命名空間)。如需進一步瞭解 Cloud Storage 命名空間路徑,請參閱物件名稱考量

啟用匯出與匯入代管作業

本節說明如何啟用匯出與匯入代管作業,以及如何檢查其進度

匯出實體

請使用下列的指令來匯出預設命名空間內的所有類別。可以加上 --async 標記,來避免 gcloud 工具為了等待作業完成而停頓。

gcloud

gcloud datastore export --namespaces="(default)" gs://${BUCKET}

通訊協定

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "namespaceIds": [""], }, }'

若要匯出一個「種類」和 / 或「命名空間」的特定子集合,請為實體篩選器提供種類和名稱空間 ID 的值。

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="NAMESPACE1,NAMESPACE2" gs://${BUCKET}

通訊協定

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "kinds": ["KIND1", "KIND2", …], "namespaceIds": ["NAMESPACE1", "NAMESPACE2", …], }, }

匯入實體

請使用下列的指令來匯入先前已透過「匯出與匯入代管服務」匯出的實體。可以加上 --async 標記,來避免 gcloud 工具為了等待作業完成而停頓。

gcloud

gcloud datastore import gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata

通訊協定

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:import
-d '{ "inputUrl": "gs://'${BUCKET}'/[PATH]/[FILE].overall_export_metadata", }'

您可以使用 Google Cloud Platform 控制台中的 Cloud Storage UI 查看值區,並取得匯入位置所需的值。或是在您的匯出作業完成後,檢查 gcloud datastore export 輸出內容或是 ExportEntitiesResponse。以下是匯入位置範例值:

gcloud

gs://${BUCKET}/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

通訊協定

"outputUrl": "gs://'${BUCKET}'/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

非同步匯入或匯出

匯出及匯入作業需要一段時間才能完成。您可以加上 --async 標記,來避免 gcloud 工具為了等待作業完成而停頓。

在您開始一項匯出或匯入作業後,可以使用 gcloud 工具返回的 ID 來檢查作業的進行狀態。例如:

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

如果忘記加上 --async 標記,您也可以使用 Ctrl+c 來停止等待進行中的作業項目。鍵入 Ctrl+c 並不會取消作業項目。

管理長時間執行的作業

「長時間執行的作業」是指可能需要大量時間才能完成的方法呼叫。您在匯出或匯入資料時,Datastore 模式資料庫便會建立一個長時間運行的作業。

舉例來說,您開始執行一項匯出作業時,Datastore 模式資料庫便會建立一個長時間運行的作業,用以追蹤匯出作業的狀態。這是開始匯出時的輸出內容:

{
  "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2017-05-25T23:54:39.583780Z",
      "operationType": "EXPORT_ENTITIES"
    },
    "progressEntities": {},
    "progressBytes": {},
    "entityFilter": {
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
  }
}

name 欄位值為該長時間運行作業的 ID。

Cloud Firestore (Datastore 模式) 提供一項作業 Admin API 用於檢查長時間運行作業的狀態,以及取消、刪除,或是列出長時間運行作業項目:

方法 說明
projects.operations.cancel 取消一個長時間執行的作業。
projects.operations.delete 刪除一個長時間執行的作業。

附註:刪除作業不會取消作業。
projects.operations.get 取得長時間執行的作業狀態。
projects.operations.list 列出長時間執行的作業。

列出長時間執行的作業

若要列出長時間執行的作業,請執行下列指令:

gcloud

gcloud datastore operations list

通訊協定

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}/operations

此範例的輸出內容將為最近完成匯出的作業項目。匯出完成後其項目會保留幾天以供存取:

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://[YOUR_BUCKET_NAME]/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

匯入實體時請使用 input_url 值。

估算完成時間

針對一個取得長時間執行作業狀態的要求,系統會回傳指標 workEstimatedworkCompleted。每個指標都會以位元組數及實體數回傳。workEstimated 會根據資料庫統計資料顯示估算一個作業會處理的總位元組數及總實體數。workCompleted 則顯示目前已處理的位元組數及實體數。作業完成後,workCompleted 會反映出實際處理的總位元數及實體數,可能會比 workEstimated 得到的值要來的大。

workCompleted 除以 workEstimated 得到一個進度的粗估值,此估計可能不準確,因為此取決於延遲的統計數據收集。

例如,以下是匯出作業的進度狀態:

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

代管匯出匯入服務的計費及定價

在使用代管匯出與匯入服務前,您需要先為您的 Google Cloud Platform 專案啟用計價功能。系統會依據 Datastore 模式定價中的實體讀取和寫入工作費率表,向您收取匯出與匯入作業的費用。

匯出和匯入作業的費用不會計入您的 App Engine 支付上限金額。此外,若您已經設定 Google Cloud Platform 預算,則在操作完成之前,匯出或匯入作業不會觸發警告訊息。同樣地,在匯出或匯入作業期間執行的讀取和寫入,將在操作完成後套用至您的每日配額

如要進一步瞭解計價相關資訊,請參閱帳單與付款支援

權限

若要開始匯出與匯入作業,您使用者帳號的 IAM 角色需開通 datastore.databases.exportdatastore.databases.import 權限。例如 Cloud Datastore Import Export Admin 角色則是兩方皆有授權。同樣地,若您要使用 curl 發出 REST 要求,您必須指派一個 IAM 角色,以授予這些權限給您的使用者帳戶。如要進一步瞭解 Datastore 模式資料庫權限,請參閱身分和 Access Management (IAM) 章節。

如果您使用範例 Cron 應用程式,其要求使用 GCP 專案的 App Engine 預設服務帳戶。您必須授予 App Engine 預設服務帳戶 Cloud Datastore Import Export Admin 角色或其他有 datastore.databases.export 權限的角色。

此外,針對所有匯出要求,發出要求的帳戶和 GCP 專案的預設服務帳戶都必須具有 IAM 角色,該角色為您的 Cloud Storage 值區授予以下權限:

權限名稱 說明
storage.buckets.get 讀取值區中繼資料,但不含 IAM 政策。
storage.objects.create 新增物件至值區。
storage.objects.list 列出專案中的物件,並在列出過程中讀取物件中繼資料,但不含 ACL。

如需「Cloud Storage 的使用者角色」清單,請參閱 Cloud Storage IAM Roles 章節。舉例來說,Storage Admin 或者 Storage Legacy Bucket Writer 的角色擁有所有匯出項目所需的 Cloud Storage 權限,並且能夠套用至完整的專案或者特定的值區。請注意 Storage Object Creator 角色並無包含匯出項目所需的所有 Cloud Storage 權限。

針對匯入要求,發出要求的帳戶和 GCP 專案的預設服務帳戶都必須具有 IAM 角色,該角色為您的 Cloud Storage 值區授予以下權限:

權限名稱 說明
storage.objects.get 讀取物件資料和中繼資料,不含 ACL。
storage.objects.list 列出專案中的物件,並在列出過程中讀取物件中繼資料,但不含 ACL。

Storage Object Viewer 角色可以授權匯入時所有必要的許可。

與 Cloud Datastore Admin 備份的差異

如果您先前使用 Cloud Datastore Admin 控制台進行備份,請注意下列幾項差異:

  • 代管匯出匯入服務沒有 GUI 可供使用。

  • 代管匯出的項目不會顯示在 Cloud Datastore Admin 控制台中。代管匯出匯入是一項新的服務,不與 App Engine 的備份和還原功能共享資料 (此功能由 GCP 控制台管理)。

  • 代管匯出與匯入服務不支援與 Cloud Datastore Admin 備份相同的中繼資料,也不會在您的資料庫儲存進度狀態。如需瞭解檢查匯出與匯入作業進度,請參閱管理長時間運行的作業

  • 您無法查看代管匯出與匯入作業的服務記錄。

  • 代管匯入服務向後兼容 Cloud Datastore Admin 備份文件。您可以使用代管會匯入服務,匯入一個 Cloud Datastore Admin 備份檔案,但無法透過 Cloud Datastore Admin 控制台匯入經由代管匯出作業匯出之項目。

匯入至 BigQuery

若要匯入某個代管匯出項目的資料至 BigQuery,請參考由 Datastore 模式備份載入資料

限制

  • 假如不指定實體篩選器,匯出的資料就無法載入 BigQuery。若您希望將該匯出項目的資料匯入至 BigQuery,則匯出時要求的實體篩選器中必須包含一或多個種類名稱。
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Datastore 說明文件