匯出與匯入實體

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

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

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

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

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

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

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

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

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

  • 如果只要匯入部分實體或將資料匯入 BigQuery,則必須在匯出時指定實體篩選器

事前準備

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

  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 值區在另一個專案中,則授予專案預設服務帳戶對該值區的存取權

設定環境

在匯出或匯入資料之前,必須先設定 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 命名空間路徑,請參閱物件名稱考量

啟用匯出與匯入代管作業

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

匯出所有實體

使用 gcloud datastore export 指令將資料庫中的所有實體匯出。您可以加上 --async 旗標,以避免 gcloud 工具為了等待作業完成而停頓。

gcloud

gcloud datastore export gs://${BUCKET} --async

rest

使用下列任何要求資料之前,請先替換以下項目:

  • project-id:您的專案 ID
  • bucket-name:您的 Cloud Storage 值區名稱

HTTP 方法和網址:

POST https://datastore.googleapis.com/v1/projects/project-id:export

JSON 要求主體:

{
  "outputUrlPrefix": "gs://bucket-name",
}

如要傳送要求,請展開以下其中一個選項:

匯出特定種類或命名空間

若要匯出部分特定種類及/或命名空間,請為「實體篩選器」提供種類和命名空間 ID 的值。

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET} --async

rest

使用下列任何要求資料之前,請先替換以下項目:

  • project-id:您的專案 ID
  • bucket-name:您的 Cloud Storage 值區名稱
  • kind:實體種類
  • namespace:命名空間 ID (預設的命名空間 ID 則使用 "")

HTTP 方法和網址:

POST https://datastore.googleapis.com/v1/projects/project-id:export

JSON 要求主體:

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

如要傳送要求,請展開以下其中一個選項:

匯出中繼資料檔案

在匯出作業中,會建立每個指定命名空間與種類組合的中繼資料檔案。中繼資料檔案名稱通常是 [NAMESPACE_NAME]_[KIND_NAME].export_metadata。但是,如果命名空間或種類建立的 Cloud Storage 物件名稱無效,檔案名稱就會是 export[NUM].export_metadata

中繼資料檔案為通訊協定緩衝區,可透過 protoc 通訊協定編譯器進行解碼。舉例來說,您可以將中繼資料檔案解碼,判斷匯出檔案中包含的命名空間和種類:

protoc --decode_raw < export0.export_metadata

匯入所有實體

使用 gcloud datastore import 指令,將先前透過匯出代管服務匯出的所有實體匯入。您可以加上 --async 旗標,以避免 gcloud 工具為了等待作業完成而停頓。

gcloud

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

rest

使用下列任何要求資料之前,請先替換以下項目:

  • project-id:您的專案 ID
  • bucket-name:您的 Cloud Storage 值區名稱
  • object-name:您的 Cloud Storage 物件名稱 (例如:2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)

HTTP 方法和網址:

POST https://datastore.googleapis.com/v1/projects/project-id:import

JSON 要求主體:

{
  "inputUrl": "gs://bucket-name/object-name",
}

如要傳送要求,請展開以下其中一個選項:

您可以使用 Google Cloud Platform Console 中的 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 --async

rest

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

匯入特定種類或命名空間

若要匯入部分特定種類和/或命名空間,請為實體篩選器提供種類和命名空間 ID 的值。

只有在匯出檔案是使用實體篩選器建立的情況下,您才能指定種類和命名空間。您無法從所有實體的匯出項目中,匯入一部分種類和命名空間。

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata --async

rest

使用下列任何要求資料之前,請先替換以下項目:

  • project-id:您的專案 ID
  • bucket-name:您的 Cloud Storage 值區名稱
  • object-name:您的 Cloud Storage 物件名稱 (例如:2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)
  • kind:實體種類
  • namespace:命名空間 ID (預設的命名空間 ID 則使用 "")

HTTP 方法和網址:

POST https://datastore.googleapis.com/v1/projects/project-id:import

JSON 要求主體:

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

如要傳送要求,請展開以下其中一個選項:

非同步匯出或匯入

匯出及匯入作業需要一段時間才能完成。執行匯出或匯入作業時,您可以加上 --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 datastore operations list 指令:

gcloud

gcloud datastore operations list

rest

使用下列任何要求資料之前,請先替換以下項目:

  • project-id:您的專案 ID

HTTP 方法和網址:

GET 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 值。

估算完成時間

作業執行時,可查看 state 欄位值,以瞭解作業的整體狀態。

用於取得長時間執行作業狀態的要求,也會傳回 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"
        },
        ...

作業完成時,作業說明中會包含 "done": true。查看 state 欄位值可得知作業結果。如果未在回應中設定 done 欄位,則其值為 false。若是進行中的作業,則不用考慮是否有 done 值。

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

在使用匯出與匯入代管服務前,您需要先為您的 Google Cloud Platform 專案啟用計費功能。匯出與匯入作業會以下列方式計入您的 Google Cloud Platform 費用:

匯出和匯入作業的費用不會計入您的 App Engine 支付上限金額。待匯出或匯入作業完成後,系統才會發出關於 Google Cloud Platform 預算的提醒。同樣地,在匯出或匯入作業期間執行的讀寫,將在作業完成後計入您的每日配額

權限

如要執行匯出和匯入作業,您的使用者帳戶和專案的預設服務帳戶必須具備以下所述的 Cloud Identity and Access Management 權限。

使用者帳戶權限

啟動作業的使用者帳戶或服務帳戶必須具備 datastore.databases.exportdatastore.databases.import 的 Cloud IAM 權限。如果您是專案擁有者,您的帳戶必須擁有必要權限。若非如此,下列 Cloud IAM 角色可授予必要權限:

  • Cloud Datastore 擁有者
  • Cloud Datastore 匯入匯出管理員

專案擁有者可以按照授予存取權一節的步驟,授予其中一個角色權限。

預設服務帳戶權限

每個 GCP 專案都會自動建立一個預設服務帳戶 PROJECT_ID@appspot.gserviceaccount.com。匯出和匯入作業會使用此服務帳戶來授權 Cloud Storage 作業。

您專案的預設服務帳戶,需要能夠存取匯出或匯入作業所用的 Cloud Storage 值區。根據預設,如果您的 Cloud Storage 值區與 Datastore 模式資料庫皆屬同一個專案,預設服務帳戶即可存取該值區

如果 Cloud Storage 值區在另一個專案中,則必須授予預設服務帳戶對 Cloud Storage 值區的存取權。

指派角色給預設服務帳戶

您可以使用 gsutil 指令列工具指派下列其中一種角色。例如,要將「Storage 管理員」角色指派給預設服務帳戶,請執行以下指令:

gsutil iam ch serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

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

匯出作業

對於涉及其他專案值區的匯出作業,請修改該值區的權限,將下列其中一個 Cloud Storage 角色指派給含有 Datastore 模式資料庫的專案預設服務帳戶:

  • Storage 管理員
  • Storage 物件管理員
  • Storage 繼承 Bucket 寫入者

您還可以建立具有以下權限的 Cloud IAM 自訂角色

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.list

匯入作業

對於涉及其他 Cloud Storage 值區的匯入作業,請修改該值區的權限,將下列其中一個 Cloud Storage 角色指派給含有 Datastore 模式資料庫的專案預設服務帳戶:

  • Storage 管理員
  • Storage 物件檢視者和 Storage 舊版值區讀取者

您還可以建立具有以下權限的 Cloud IAM 自訂角色

  • storage.buckets.get
  • storage.objects.get

與 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,請參閱載入 Cloud Datastore 匯出服務資料

限制

  • 假如不指定實體篩選器,匯出的資料就無法載入 BigQuery。如果希望將匯出的資料匯入 BigQuery,則匯出時要求的實體篩選器中必須包含一或多個種類名稱。