Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

匯出與匯入實體

本頁面說明如何使用代管匯出和匯入服務，匯出及匯入 Datastore 模式的 Firestore 實體。您可以透過 Google Cloud 控制台、Google Cloud CLI 和 Datastore Admin API (REST、RPC) 使用代管匯出和匯入服務。

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

匯出服務使用最終一致性讀取。您不能假設匯出在一個單一時間點發生。該匯出項目能夠包含匯出開始後寫入的實體並且不會包含匯出開始前寫入的實體。
匯出項目不包含任何索引。當您匯入資料時，系統會使用您資料庫現行的索引定義自動重建所需索引。個別實體屬性值索引設定會被匯出並在匯入作業期間發揮其作用。
匯入作業不會為實體指派新 ID。匯入項目會使用匯出時存在的 ID，並覆寫任何 ID 相同的現有實體。在匯入期間，系統會在匯入實體時保留這些 ID。如果在匯入作業執行時啟用了寫入，則此功能可防止與新實體的 ID 衝突。
若您資料庫中的實體沒有受到匯入影響，則匯入後將會保留在資料庫中。
從 Datastore 模式資料庫匯出的資料可以匯入到另一個 Datastore 模式資料庫中，即使其中一個資料庫在其他專案中亦是如此。
代管匯出和匯入服務會將並行匯出和匯入數量限制為 50 個，且每項專案每分鐘最多可提出 20 項匯出和匯入要求。每項要求中，服務限制實體篩選器組合數量最多為 100 個。
代管匯出項目輸出內容採用 LevelDB 記錄檔格式。
如果只要匯入部分實體或將資料匯入 BigQuery，則必須在匯出時指定實體篩選器。
.overall_export_metadata 檔案名稱必須與其上層資料夾的名稱相符：

gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

如果您移動或複製匯出的輸出檔案，請保留 PARENT_FOLDER_NAME、子資料夾的內容，以及 .overall_export_metadata 檔案名稱。

事前準備

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

啟用 Google Cloud 專案的計費功能。只有已啟用計費功能的 Google Cloud 專案，才能使用匯出和匯入功能。
在 Firestore (Datastore 模式) 資料庫所在位置建立 Cloud Storage bucket。您無法使用「要求者付費」bucket 或 Rapid bucket 執行匯出和匯入作業。
指派 IAM 角色給您的使用者帳戶，如要匯出資料，則授予 datastore.databases.export 權限；或要匯入資料，則授予 datastore.databases.import 權限。舉例來說，可將這兩種權限授予 Datastore Import Export Admin 角色。
如果 Cloud Storage bucket 位於其他專案，請授予 Firestore 服務代理存取 bucket 的權限。

為專案設定 `gcloud`

如果您打算使用 gcloud 啟動匯入和匯出作業，請設定 gcloud，並透過下列其中一種方式連線至專案：

使用 Cloud Shell，從 Google Cloud 控制台存取 gcloud。

啟動 Cloud Shell

將 gcloud CLI 設為使用目前的專案：
```
gcloud config set project project-id
```
安裝並初始化 Google Cloud CLI。

權限

如要執行匯出和匯入作業，您的使用者帳戶和專案的 Datastore 模式服務代理，必須具備下列 Identity and Access Management 權限。

使用者帳戶權限

啟動作業的使用者帳戶或服務帳戶必須具備 datastore.databases.export 和 datastore.databases.import IAM 權限。如果您是專案擁有者，您的帳戶必須擁有必要權限。否則，下列 IAM 角色會授予必要權限：

資料儲存庫擁有者
Datastore 匯入匯出管理員

您也可以透過自訂角色指派這些權限。

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

服務代理權限

匯出和匯入作業會使用 Firestore 服務代理，授權 Cloud Storage 作業。Firestore 服務代理程式採用下列命名慣例：

Firestore 服務代理: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

如要進一步瞭解服務代理，請參閱「服務代理」。

Firestore 服務代理需要存取匯出或匯入作業使用的 Cloud Storage bucket。如果 Cloud Storage bucket 與 Firestore 資料庫位於相同專案，Firestore 服務代理預設可以存取該 bucket。

如果 Cloud Storage bucket 位於其他專案，則必須授予 Firestore 服務代理 Cloud Storage bucket 的存取權。

將角色指派給服務代理

您可以使用 gsutil 指令列工具指派下列其中一種角色。舉例來說，如要將 Storage 管理員角色指派給 Firestore 服務代理，請執行下列指令：

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

將 PROJECT_NUMBER 替換為專案編號，用於命名 Firestore 服務代理。如要查看服務代理名稱，請參閱「查看服務代理名稱」。

或者，您也可以使用 Google Cloud 控制台指派這個角色。

查看服務代理名稱

您可以在 Google Cloud 控制台的「Import/Export」(匯入/匯出) 頁面，查看匯入和匯出作業用於授權要求的帳戶。您也可以查看資料庫使用的是 Firestore 服務代理，還是舊版 App Engine 服務帳戶。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
查看「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的授權帳戶。

匯出作業

如果匯出作業涉及其他專案中的 bucket，請修改 bucket 的權限，將下列其中一個身分與存取權管理角色指派給 Datastore 模式資料庫所在專案的 Datastore 模式服務代理：

儲存空間管理員
擁有者 (基本角色)

您也可以建立 IAM 自訂角色，其權限與上述角色所含權限略有不同：

storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.list

匯入作業

如果匯入作業涉及其他專案中的 Cloud Storage bucket，請修改 bucket 的權限，將下列其中一個 Cloud Storage 角色指派給 Datastore 模式資料庫所在專案的 Datastore 模式服務代理：

儲存空間管理員
Storage 物件檢視者和 Storage 舊版值區讀取者

您也可以建立具備下列權限的 IAM 自訂角色：

storage.buckets.get
storage.objects.get

啟用匯出與匯入代管作業

本節說明如何啟動代管匯出或匯入作業。

匯出所有實體

控制台

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。

在導覽選單中，按一下「匯入/匯出」。
按一下 [匯出]。
將「Namespace」(命名空間) 欄位設為 All Namespaces，並將「Kind」(種類) 欄位設為 All Kinds。
在「目的地」下方，輸入 Cloud Storage bucket 的名稱。
按一下 [匯出]。

控制台會返回「Import/Export」(匯入/匯出) 頁面。快訊會回報代管匯出要求的成功或失敗。

gcloud

使用 gcloud firestore export 指令匯出資料庫中的所有實體。

 gcloud firestore export gs://bucket-name --async --database=DATABASE

其中 bucket-name 是 Cloud Storage bucket 的名稱和選用前置字串，例如 bucket-name/datastore-exports/export-name。您無法在其他匯出作業中重複使用相同的前置字串。如未提供檔案前置字串，代管匯出服務會根據目前時間建立一個。

使用 --async 旗標，防止 gcloud 等待作業完成。如果省略 --async 旗標，可以輸入 Ctrl+c 停止等待作業。這項操作不會取消作業。

將 --database 旗標設為要匯出實體的資料庫名稱。如要使用預設資料庫，請使用 --database='(default)'。

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID
bucket-name：Cloud Storage bucket 名稱

HTTP 方法和網址：

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

JSON 要求主體：

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

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}

回應是長時間執行的作業，您可以檢查是否完成。

匯出特定種類或命名空間

如要匯出特定種類和/或命名空間子集，請提供實體篩選器，並指定種類和命名空間 ID 的值。每項要求最多只能有 100 個實體篩選器組合，其中每個篩選種類和命名空間組合都會計為一個篩選器，計入這項限制。

控制台

在控制台中，您可以選取所有種類或特定種類。同樣地，您可以選取所有命名空間或特定命名空間。

如要指定要匯出的命名空間和種類清單，請改用 gcloud。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
按一下 [匯出]。
將「Namespace」(命名空間) 欄位設為 All Namespaces 或其中一個命名空間的名稱。
將「Kind」(種類) 欄位設為 All Kinds 或種類名稱。
在「目的地」下方，輸入 Cloud Storage bucket 的名稱。
按一下 [匯出]。

控制台會返回「Import/Export」(匯入/匯出) 頁面。快訊會回報代管匯出要求的成功或失敗。

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

使用 --async 旗標，防止 gcloud 等待作業完成。如果省略 --async 旗標，可以輸入 Ctrl+c 停止等待作業。這項操作不會取消作業。

將 --database 旗標設為要匯出特定種類或命名空間的資料庫名稱。如要使用預設資料庫，請使用 --database='(default)'。

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID
bucket-name：Cloud Storage bucket 名稱
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"],
  },
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}

回應是長時間執行的作業，您可以檢查是否完成。

中繼資料檔案

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

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

protoc --decode_raw < export0.export_metadata

匯入所有實體

控制台

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
按一下「匯入」。
在「File」欄位中，按一下「Browse」(瀏覽)，然後選取 .overall_export_metadata 檔案。

請確認 .overall_export_metadata 檔案未從預設位置移出。
將「Namespace」(命名空間) 欄位設為 All Namespaces，並將「Kind」(種類) 欄位設為 All Kinds。
按一下「匯入」。

控制台會返回「Import/Export」(匯入/匯出) 頁面。系統會發出快訊，回報代管匯入要求成功或失敗。

gcloud

使用 gcloud firestore import 指令，匯入先前透過代管匯出服務匯出的所有實體。

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

其中 bucket-name/file-path/file-name 是 Cloud Storage bucket 中 overall_export_metadata 檔案的路徑。

使用 --async 旗標，防止 gcloud 等待作業完成。如果省略 --async 旗標，可以輸入 Ctrl+c 停止等待作業。這項操作不會取消作業。

將 --database 旗標設為要匯入所有實體的資料庫名稱。如要使用預設資料庫，請使用 --database='(default)'。

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID
bucket-name：Cloud Storage bucket 名稱
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",
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}

回應是長時間執行的作業，您可以檢查是否完成。

找出 `overall_export_metadata` 檔案

您可以使用 Google Cloud 控制台中的 Cloud Storage 瀏覽器，判斷要用於匯入位置的值：

開啟 Cloud Storage 瀏覽器

您也可以列出並說明已完成的操作。outputURL 欄位會顯示 overall_export_metadata 檔案的名稱：

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

匯入特定種類或命名空間

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

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

控制台

在控制台中，您可以選取所有種類或特定種類。同樣地，您可以選取所有命名空間或特定命名空間。

如要指定要匯入的命名空間和種類清單，請改用 gcloud。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
按一下「匯入」。
在「File」欄位中，按一下「Browse」(瀏覽)，然後選取 .overall_export_metadata 檔案。

請務必匯入 .overall_export_metadata 檔案，而非 .export_metadata 檔案。
將「Namespace」(命名空間) 欄位設為 All Namespaces 或特定命名空間。
將「Kind」(種類) 欄位設為 All Kinds 或特定種類。
按一下「匯入」。

控制台會返回「Import/Export」(匯入/匯出) 頁面。系統會發出快訊，回報代管匯入要求成功或失敗。

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

其中 bucket-name/file-path/file-name 是 Cloud Storage bucket 中 overall_export_metadata 檔案的路徑。

使用 --async 旗標，防止 gcloud 等待作業完成。如果省略 --async 旗標，可以輸入 Ctrl+c 停止等待作業。這項操作不會取消作業。

將 --database 旗標設為要匯入特定種類或命名空間的資料庫名稱。如要使用預設資料庫，請使用 --database='(default)'。

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID
bucket-name：Cloud Storage bucket 名稱
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"],
  },
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}

回應是長時間執行的作業，您可以檢查是否完成。

從 PITR 資料匯出及匯入

您可以將資料庫從 PITR 資料匯出至 Cloud Storage。您可以匯出 PITR 資料，時間戳記為過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記已無資料，匯出作業就會失敗。

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

匯出 PITR 資料前，請注意下列事項：

在資料庫啟用 PITR。如果停用 PITR，則無法在快照時間戳記匯出，即使時間戳記在 earliestVersionTime 之後的過去一小時內也一樣。匯出作業會傳回 Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp 錯誤。
請以 RFC 3339 格式指定時間戳記。例如：2023-05-26T10:20:00.00Z。
請確認您指定的時間戳記是過去七天內的整分鐘時間戳記，但不得早於 earliestVersionTime。如果指定時間戳記已無資料，系統會產生錯誤。
如果 PITR 匯出作業失敗，系統不會收取費用。

控制台

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。
前往「資料庫」
從資料庫清單中選取資料庫。
在導覽選單中，按一下「匯入/匯出」。
按一下 [匯出]。
選擇要匯出的命名空間
選取要匯出的種類。
在「Choose the state of your database to export」(選取要匯出的資料庫狀態) 區段中，選取「Export from an earlier point in time」(匯出較早時間點的資料)。

選取要用於匯出的快照時間
在「Destination」(目的地) 區段中，輸入 Cloud Storage bucket 的名稱，或使用「Browse」(瀏覽) 按鈕選取 bucket。
按一下 [匯出]。

控制台會返回「Import/Export」(匯入/匯出) 頁面。如果作業成功啟動，頁面會將項目新增至最近匯入和匯出頁面。如果失敗，頁面會顯示錯誤訊息。

gcloud

您可以使用 gcloud firestore export 指令，將資料庫從 PITR 資料匯出至 Cloud Storage。PITR 匯出作業支援所有篩選器，包括匯出所有實體，以及匯出特定種類或命名空間。

匯出資料庫，並將 snapshot-time 參數指定為復原時間戳記。執行下列指令，將資料庫匯出至 bucket。

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。

匯入轉換

從其他專案匯入實體時，請注意實體索引鍵包含專案 ID。匯入作業會以目的地專案的專案 ID，更新匯入資料中的實體索引鍵和索引鍵參照屬性。如果這項更新會增加實體大小，匯入作業可能會發生「實體過大」或「索引項目過大」錯誤。

如要避免發生上述錯誤，請匯入至專案 ID 較短的目的地專案。這不會影響從相同專案匯入資料的操作。

管理長時間執行的作業

代管匯入和匯出作業是長時間執行的作業。這些方法呼叫可能需要相當長的時間才能完成。

啟動匯出或匯入作業後，Datastore 模式會為作業指派專屬名稱。您可以使用作業名稱來刪除、取消或檢查作業狀態。

作業名稱的前置字串為 projects/[PROJECT_ID]/databases/(default)/operations/，例如：

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

為 gcloud 指令指定作業名稱時，可以省略前置字元。

列出所有長時間執行的作業

您可以透過下列方式，查看進行中和最近完成的操作。作業完成後，會列出幾天：

控制台

您可以在 Google Cloud 控制台的「Import/Export」(匯入/匯出)頁面中，查看長時間執行的作業清單。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。

gcloud

如要列出長時間執行的作業，請使用 gcloud datastore operations list 指令。

gcloud datastore operations list

舉例來說，最近完成的匯出作業會顯示下列資訊：

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/operations

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

請查看以下回應的相關資訊。

舉例來說，最近完成的匯出作業會顯示下列資訊：

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

查看作業狀態

如要查看長時間執行的作業狀態，請按照下列步驟操作：

控制台

您可以在 Google Cloud 控制台的「Import/Export」(匯入/匯出) 頁面中，查看最近匯出和匯入作業的清單。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。

gcloud

使用 operations describe 指令，顯示長時間執行的作業狀態。

gcloud datastore operations describe operation-name

rest

使用任何要求資料之前，請先修改下列項目的值：

project-id：專案 ID
operation-name：作業名稱

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

估算完成時間

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

要求長時間執行的作業狀態時，會傳回 workEstimated 和 workCompleted 指標。每項指標都會以位元組數和實體數傳回：

workEstimated 會顯示作業預計處理的位元組和文件總數。如果無法預估，Datastore 模式可能會省略這項指標。
workCompleted 顯示目前處理的位元組和文件數量。作業完成後，這個值會顯示實際處理的位元組和文件總數，可能大於 workEstimated 的值。

將 workCompleted 除以 workEstimated 可得出進度的粗估值。這項預估值可能不準確，因為取決於延遲的統計資料收集。

例如，以下是匯出作業的進度狀態：

{
  "operations": [
    {
      "name": "projects/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 控制台的「Import/Export」(匯入/匯出) 頁面中，取消執行中的匯出或匯入作業。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。

在「Recent imports and exports」(近期匯入和匯出作業) 表格中，目前執行的作業在「Completed」(已完成) 欄中會顯示「Cancel」(取消) 按鈕。按一下「Cancel」(取消) 按鈕即可停止作業。按鈕會先變成「Cancelling」(取消中) 訊息，然後在作業完全停止時變成「Cancelled」(已取消)。

gcloud

使用 operations cancel 指令停止進行中的作業：

gcloud datastore operations cancel operation-name

取消執行中的作業並不會復原該作業。取消匯出作業後，已匯出的文件會保留在 Cloud Storage 中；取消匯入作業後，資料庫中已完成的更新會保留在原處。您無法匯入部分完成的匯出作業。

刪除作業

gcloud

使用 operations delete 指令，從近期作業清單中移除作業。這個指令不會從 Cloud Storage 刪除匯出檔案。

gcloud datastore operations delete operation-name

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

您必須先為 Google Cloud 專案啟用計費功能，才能使用代管匯出和匯入服務。匯出和匯入作業會以下列方式產生 Google Cloud 費用：

匯出和匯入作業執行的實體讀取和寫入作業，會計入 Datastore 模式 Firestore 費用。每匯出一個實體，匯出作業就會產生一項讀取作業。匯入作業每匯入一個實體，就會產生一項寫入作業。
儲存在 Cloud Storage 中的輸出檔案，會計入您的 Cloud Storage 資料儲存空間費用。

匯出或匯入作業完成後，才會觸發Google Cloud 預算快訊。同樣地，在匯出或匯入作業期間執行的讀寫，將在作業完成後計入您的每日配額。

查看匯出和匯入費用

匯出和匯入作業會將 goog-firestoremanaged:exportimport 標籤套用至計費作業。在 Cloud Billing 帳單報表頁面，您可以使用這個標籤查看與匯入和匯出作業相關的費用：

從篩選器選單存取 goog-firestoremanaged 標籤。

與 Datastore 管理員備份的差異

如果您先前使用 Datastore 管理控制台進行備份，請注意下列差異：

由代管匯出作業建立的匯出作業不會顯示在 Datastore 管理控制台中。代管匯出和匯入是一項新服務，不會與 App Engine 的備份和還原功能共用資料，該功能是透過 Google Cloud 控制台管理。
代管匯出和匯入服務不支援與 Datastore 管理員備份相同的中繼資料，也不會將進度狀態儲存在資料庫中。如要瞭解如何查看匯出和匯入作業的進度，請參閱「管理長時間執行的作業」
您無法查看代管匯出與匯入作業的服務記錄。
代管匯入服務與 Datastore Admin 備份檔案回溯相容。您可以使用代管匯入服務匯入 Datastore 管理員備份檔案，但無法使用 Datastore 管理員控制台匯入代管匯出作業的輸出內容。

匯入至 BigQuery

如要將代管匯出作業中的資料匯入 BigQuery，請參閱「載入 Datastore 匯出服務資料」。

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

BigQuery 資料欄限制

BigQuery 規定每個資料表最多只能有 10,000 個資料欄。匯出作業會為每個種類產生 BigQuery 資料表結構定義。在這個結構定義中，種類實體中的每個不重複屬性都會成為結構定義資料欄。

如果某個種類的 BigQuery 結構定義超過 10,000 個資料欄，匯出作業會將嵌入的實體視為 blob，盡可能不超過資料欄限制。如果轉換後，結構定義中的資料欄數量少於 10,000 個，您就可以將資料載入 BigQuery，但無法查詢嵌入實體中的屬性。如果資料欄數量仍超過 10,000 個，匯出作業就不會為該種類產生 BigQuery 結構定義，您也無法將其資料載入 BigQuery。

服務代理遷移

Firestore 會使用 Firestore 服務代理 (而非 App Engine 服務帳戶) 授權匯入和匯出作業。服務代理和服務帳戶採用下列命名慣例：

Firestore 服務代理: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Firestore 先前使用的是 App Engine 預設服務帳戶，而非 Firestore 服務代理。如果資料庫仍使用 App Engine 服務帳戶匯入或匯出資料，建議您按照本節的操作說明，改用 Firestore 服務代理。

App Engine 服務帳戶: PROJECT_ID@appspot.gserviceaccount.com

Firestore 服務代理是 Firestore 專用，因此建議使用。App Engine 服務帳戶由多項服務共用。

查看授權帳戶

您可以在 Google Cloud 控制台的「Import/Export」(匯入/匯出) 頁面，查看匯入和匯出作業使用哪個帳戶授權要求。您也可以查看資料庫是否已使用 Firestore 服務代理。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
查看「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的授權帳戶。

如果專案未使用 Firestore 服務代理，您可以使用下列任一技術，遷移至 Firestore 服務代理：

檢查並更新 Cloud Storage bucket 權限，藉此遷移專案 (建議做法)。
新增組織層級政策限制，影響組織內的所有專案。

建議您採用第一種技術，因為這種技術會將影響範圍限制在單一 Datastore 模式專案。第二種技術不會遷移現有的 Cloud Storage bucket 權限，因此不建議使用。不過，這項服務確實提供組織層級的安全法規遵循。

檢查並更新 Cloud Storage bucket 權限，完成遷移作業

遷移程序包含兩個步驟：

更新 Cloud Storage bucket 權限。詳情請參閱下節。
確認遷移至 Firestore 服務代理。

服務代理值區權限

如果匯出或匯入作業使用「其他」專案中的 Cloud Storage bucket，您必須為該 bucket 授予 Firestore 服務代理權限。例如，將資料移至其他專案的作業需要存取該專案中的 bucket。否則，遷移至 Firestore 服務代理後，這些作業會失敗。

如果匯入和匯出工作流程都在同一個專案中，則不需變更權限。根據預設，Firestore 服務代理可以存取相同專案中的 bucket。

更新其他專案的 Cloud Storage bucket 權限，將存取權授予service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com服務代理。將 Firestore Service Agent 角色授予服務代理。

Firestore Service Agent 角色會授予 Cloud Storage bucket 的讀取和寫入權限。如果只需要授予讀取或寫入權限，請使用自訂角色。

請按照下一節說明的遷移程序，找出可能需要更新權限的 Cloud Storage bucket。

將專案遷移至 Firestore 服務代理

請完成下列步驟，從 App Engine 服務帳戶遷移至 Firestore 服務代理。遷移完成後即無法復原。

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
如果專案尚未遷移至 Firestore 服務代理，您會看到說明遷移作業的橫幅和「Check Bucket Status」(檢查 bucket 狀態) 按鈕。下一步可協助您找出並修正潛在的權限錯誤。

按一下「Check Bucket Status」(檢查 bucket 狀態)。

畫面上會顯示選單，其中包含完成遷移的選項和 Cloud Storage bucket 清單。清單可能需要幾分鐘才能載入完畢。

這份清單包含最近用於匯入和匯出作業的 bucket，但目前未向 Datastore 模式服務代理授予讀取和寫入權限。
記下專案 Datastore 模式服務代理的主體名稱。服務代理名稱會顯示在「Service agent to give access to」(要授予存取權的服務代理) 標籤下方。
針對清單中日後要用於匯入或匯出作業的任何 bucket，請完成下列步驟：
1. 在值區的表格列中，按一下「修正」。系統會在新分頁開啟該值區的權限頁面。
2. 按一下「新增」。
3. 在「New principals」(新增主體) 欄位中，輸入 Firestore 服務代理的名稱。
4. 在「Select a role」(選取角色) 欄位中，依序選取「Service Agents」(服務代理) >「Firestore Service Agent」(Firestore 服務代理)。
5. 按一下「儲存」。
6. 返回 Datastore 模式「匯入/匯出」頁面的分頁。
7. 對清單中的其他 bucket 重複執行這些步驟。請務必查看清單的所有頁面。
按一下「Migrate to Firestore Service Agent」(遷移至 Firestore 服務代理)。如果仍有 bucket 未通過權限檢查，請按一下「Migrate」(遷移) 確認遷移。

遷移作業完成後，系統會發出快訊通知。遷移作業無法復原。

查看遷移狀態

如要確認專案的遷移狀態，請按照下列步驟操作：

前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。

前往「資料庫」
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「匯入/匯出」。
找出「Import/Export jobs run as」(匯入/匯出工作執行身分) 標籤旁的主體。

如果主體是 service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com，代表專案已遷移至 Firestore 服務代理。遷移作業無法復原。

如果專案尚未遷移，頁面頂端會顯示橫幅，並附有「Check Bucket Status」(檢查 bucket 狀態) 按鈕。請參閱「遷移至 Firestore 服務代理」一文，完成遷移作業。

新增組織層級政策限制

在組織政策中設定下列限制：

必須使用 Firestore 服務代理才能執行匯入/匯出工作 (firestore.requireP4SAforImportExport)。

這項限制規定匯入和匯出作業必須使用 Firestore 服務代理來授權要求。如要設定這項限制，請參閱「建立及管理組織政策」。

套用這項組織政策限制，不會自動為 Firestore 服務代理授予適當的 Cloud Storage bucket 權限。

如果限制導致匯入或匯出工作流程發生權限錯誤，您可以停用限制，改回使用預設服務帳戶。檢查並更新 Cloud Storage bucket 權限後，即可再次啟用限制。

匯出與匯入實體 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

為專案設定 gcloud

權限

使用者帳戶權限

服務代理權限

將角色指派給服務代理

查看服務代理名稱

匯出作業

匯入作業

啟用匯出與匯入代管作業

匯出所有實體

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

匯出特定種類或命名空間

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

中繼資料檔案

匯入所有實體

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

找出 overall_export_metadata 檔案

匯入特定種類或命名空間

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

從 PITR 資料匯出及匯入

控制台

gcloud

匯入轉換

管理長時間執行的作業

列出所有長時間執行的作業

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

查看作業狀態

控制台

gcloud

rest

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

估算完成時間

取消作業

控制台

gcloud

刪除作業

gcloud

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

查看匯出和匯入費用

與 Datastore 管理員備份的差異

匯入至 BigQuery

BigQuery 資料欄限制

服務代理遷移

查看授權帳戶

檢查並更新 Cloud Storage bucket 權限，完成遷移作業

服務代理值區權限

將專案遷移至 Firestore 服務代理

查看遷移狀態

新增組織層級政策限制

匯出與匯入實體

為專案設定 `gcloud`

找出 `overall_export_metadata` 檔案