导出和导入实体

本页面介绍如何使用托管式导出和导入服务来导出和导入 Datastore 模式 Firestore 实体。您可以通过 Cloud Console、Google Cloud CLI 和 Datastore Admin API(RESTRPC)使用托管式导出和导入服务。

通过托管式导出和导入服务,您可以恢复意外删除的数据,并导出数据以供离线处理。您可以导出所有实体,也可以仅导出特定类型的实体。同样,您可以导入某次导出的所有数据,或仅导入特定类型的数据。使用代管式导出和导入服务时,请考虑以下事项:

  • 导出服务使用最终一致性读取。您不能假设导出发生在单一时间点。导出内容可能包括导出开始后写入的实体,并排除导出开始前写入的实体。

  • 导出的数据不包含任何索引。在您导入数据时,系统将使用数据库当前的索引定义自动重建所需的索引。每个实体的属性值索引设置会被导出,并在导入时得以支持。

  • 导入操作不向实体分配新 ID。导入使用导出时存在的 ID,并覆盖具有相同 ID 的任何现有实体。在导入过程中,正在导入的实体的 ID 将被预留。如果在导入运行过程中启用了写入,此功能可防止与新实体发生 ID 冲突。

  • 如果数据库中某个实体未受到导入的影响,导入后该实体将保留在您的数据库中。

  • 从一个 Datastore 模式数据库导出的数据可导入到另一个 Datastore 模式数据库中,甚至可以导入另一个项目中的数据库。

  • 托管式导出和导入服务将并发导出和导入数限制为 50,并且每分钟最多允许 20 个导出和导入请求。对于每个请求,服务会将实体过滤条件组合的数量限制为 100。

  • 代管式导出的输出使用 LevelDB 日志格式

  • 如需仅导入一部分实体,或者将数据导入 BigQuery,您必须在导出中指定实体过滤条件

开始前须知

您必须先完成以下任务,才能使用代管式导出和导入服务。

  1. 为 Google Cloud 项目启用结算功能。 只有启用了结算功能的 Google Cloud 项目才能使用导出和导入功能。

  2. Datastore 模式 Firestore 数据库所在的位置创建 Cloud Storage 存储分区。您不能使用“请求者付款”存储分区执行导出和导入操作。

  3. 如果要导出数据,请为您的用户帐号分配一个能够授予 datastore.databases.export 权限的 IAM 角色;如果要导入数据,请为您的服务帐号授予一个 datastore.databases.import 权限。例如,Datastore Import Export Admin 角色可同时授予这两种权限。

  4. 如果 Cloud Storage 存储分区位于其他项目中,则为您项目的默认服务帐号授予对该存储分区的访问权限

为您的项目设置 gcloud

如果您打算使用 gcloud 启动导入和导出操作,请设置 gcloud 并通过以下方式之一关联到您的项目:

启动托管式导出和导入操作

本部分介绍如何开始执行托管式导出或导入操作。

导出所有实体

控制台

  1. 转到 Google Cloud Console 中的 Datastore 导入/导出页面。

    转到“导入/导出”页面

  2. 点击导出

  3. 命名空间字段设置为 All Namespaces,并将种类字段设置为 All Kinds

  4. 目标下,输入您的 Cloud Storage 存储分区的名称。

  5. 点击导出

控制台会返回到导入/导出页面。系统会显示提醒,说明您的托管导出请求是成功还是失败。

gcloud

使用 gcloud datastore export 命令导出数据库中的所有实体。

 gcloud datastore export gs://bucket-name --async

其中,bucket-name 是您的 Cloud Storage 存储分区的名称和可选前缀,例如 bucket-name/datastore-exports/export-name。您不能将同一前缀重复用于其他导出操作。如果您不提供文件前缀,代管式导出服务会根据当前时间创建一个。

使用 --async 标志可阻止 gcloud 等待操作完成。如果您省略 --async 标志,则可以输入 Ctrl+c 以停止等待操作。此操作不会取消操作。

休息

在使用任何请求数据之前,请先进行以下替换:

  • project-id:您的项目 ID
  • bucket-name:您的 Cloud Storage 存储分区名称

HTTP 方法和网址:

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

请求 JSON 正文:

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

如需发送请求,请展开即可下选项之一:

您应该收到类似以下内容的 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

  1. 转到 Google Cloud Console 中的 Datastore 导出页面。

    转到“Datastore 导出”页面

  2. 点击导出

  3. 命名空间字段设置为 All Namespaces 或其中一个命名空间的名称。

  4. 种类字段设置为 All Kinds 或种类名称。

  5. 目标下,输入您的 Cloud Storage 存储分区的名称。

  6. 点击导出

控制台会返回到导入/导出页面。系统会显示提醒,说明您的托管导出请求是成功还是失败。

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name --async

其中,bucket-name 是您的 Cloud Storage 存储分区的名称和可选前缀,例如 bucket-name/datastore-exports/export-name。您不能将同一前缀重复用于其他导出操作。如果您不提供文件前缀,代管式导出服务会根据当前时间创建一个。

使用 --async 标志可阻止 gcloud 等待操作完成。如果您省略 --async 标志,则可以输入 Ctrl+c 以停止等待操作。此操作不会取消操作。

休息

在使用任何请求数据之前,请先进行以下替换:

  • 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"],
  },
}

如需发送请求,请展开即可下选项之一:

您应该收到类似以下内容的 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

导入所有实体

控制台

  1. 转到 Google Cloud Console 中的 Datastore 导入页面。

    转到“Datastore 导入”页面

  2. 点击导入

  3. File 字段中,点击浏览,然后选择一个 overall_export_metadata 文件。

  4. 命名空间字段设置为 All Namespaces,并将种类字段设置为 All Kinds

  5. 点击导入

控制台会返回到导入/导出页面。系统会显示提醒,说明您的托管式导入请求的成功或失败。

gcloud

使用 gcloud datastore import 命令导入之前使用托管式导出服务导出的所有实体。

gcloud datastore import gs://bucket-name/file-path/file-name.overall_export_metadata --async

其中,bucket-name/file-path/file-name 是 Cloud Storage 存储分区中 overall_export_metadata 文件的路径。

使用 --async 标志可阻止 gcloud 等待操作完成。如果您省略 --async 标志,则可以输入 Ctrl+c 以停止等待操作。此操作不会取消操作。

休息

在使用任何请求数据之前,请先进行以下替换:

  • 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",
}

如需发送请求,请展开即可下选项之一:

您应该收到类似以下内容的 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 Console 中的 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

  1. 转到 Google Cloud Console 中的 Datastore 导入页面。

    转到“Datastore 导入”页面

  2. 点击导入

  3. File 字段中,点击浏览,然后选择一个 overall_export_metadata 文件。

  4. 命名空间字段设置为 All Namespaces 或特定命名空间。

  5. 种类字段设置为 All Kinds 或特定种类。

  6. 点击导入

控制台会返回到导入/导出页面。系统会显示提醒,说明您的托管式导入请求的成功或失败。

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name/file-path/file-name.overall_export_metadata --async

其中,bucket-name/file-path/file-name 是 Cloud Storage 存储分区中 overall_export_metadata 文件的路径。

使用 --async 标志可阻止 gcloud 等待操作完成。如果您省略 --async 标志,则可以输入 Ctrl+c 以停止等待操作。此操作不会取消操作。

休息

在使用任何请求数据之前,请先进行以下替换:

  • 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"],
  },
}

如需发送请求,请展开即可下选项之一:

您应该收到类似以下内容的 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"
  }
}
该响应是一个长时间运行的操作,您可以检查其完成情况。

导入转换

从其他项目导入实体时,请注意实体键包含项目 ID。导入操作会使用目标项目的 ID 更新导入数据中的实体键和键引用属性。如果此更新增加实体大小,则可能会导致“实体太大”或“索引条目过大”错误对导入操作产生影响。

为避免出现任一错误,请导入项目 ID 较短的目标项目。这不会影响来自同一项目的数据的导入操作。

管理长时间运行的操作

代管式导入和导出操作是长时间运行的操作。这些方法调用可能需要大量时间。

在您启动导出或导入操作后,Datastore 模式会为操作分配唯一的名称。您可以使用操作名称来删除、取消操作或检查操作状态。

操作名称的前缀为 projects/[PROJECT_ID]/databases/(default)/operations/,例如:

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

您可以在指定 gcloud 命令的操作名称时省略前缀。

列出所有长时间运行的操作

您可以通过以下方式查看正在进行和最近完成的操作。最近几天内完成的操作都会列出:

控制台

您可以在 Google Cloud Console 的 Datastore 模式导入/导出页面中查看最近的导出和导入操作列表。

转到“导入/导出”页面

gcloud

如需列出长时间运行的操作,请使用 gcloud datastore actions 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"
      }
    }
  ]
}

休息

在使用任何请求数据之前,请先进行以下替换:

  • project-id:您的项目 ID

HTTP 方法和网址:

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

如需发送请求,请展开即可下选项之一:

请参阅下方响应的相关信息。

例如,最近完成的导出操作会显示以下信息:

{
  "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 Console 的 Datastore 模式导入/导出页面中查看最近的导出和导入操作列表。

转到“导入/导出”页面

gcloud

使用 operations describe 命令可显示长时间运行的操作的状态。

gcloud datastore operations describe operation-name

休息

在使用任何请求数据之前,请先进行以下替换:

  • project-id:您的项目 ID
  • operation-name:操作名称

HTTP 方法和网址:

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

如需发送请求,请展开即可下选项之一:

您应该收到类似以下内容的 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 字段的值可了解操作的总体状态。

用于获取长时间运行的操作的状态的请求会返回指标 workEstimatedworkCompleted。返回的这两个指标均包含字节数和实体数:

  • workEstimated 表示操作将处理的预估总字节数和文档数。

  • 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 Console 的 Datastore 模式导入/导出页面中取消正在运行的导出或导入操作。

转到“导入/导出”页面

“近期导入和导出”表中,当前正在执行的操作在“已完成”列中有一个取消按钮。点击取消按钮可停止操作。按钮会变为“正在取消”消息,然后当操作完全停止时,变为“已取消”。

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 费用:

导出和导入操作的费用不计入 App Engine 支出限额。导出或导入操作在完成之前不会触发任何 Google Cloud 预算提醒。同样,在导出或导入操作期间执行的读写会在操作完成后计入您的每日配额

查看导出和导入费用

导出和导入操作会为收费操作添加 goog-firestoremanaged:exportimport 标签。在 Cloud Billing 报告页面中,您可以使用此标签查看与导入和导出操作相关的费用:

从过滤条件菜单访问 goog-firestoremanaged 标签。

权限

如需运行导出和导入操作,您的用户帐号和项目的默认服务帐号需要具备下述 Identity and Access Management 权限。

用户帐号权限

发起该操作的用户帐号或服务帐号需要 datastore.databases.exportdatastore.databases.import IAM 权限。如果您是项目所有者,那么您的帐号将具有所需权限。否则,以下 IAM 角色会授予必要的权限:

  • Datastore 所有者
  • Datastore 导入/导出管理员

您还可以使用自定义角色分配这些权限。

项目所有者可以按照授予访问权限中的步骤授予其中一个角色。

默认服务帐号权限

每个 Google Cloud 项目都会自动创建一个名为 PROJECT_ID@appspot.gserviceaccount.com 的默认服务帐号。导出和导入操作使用此服务帐号授权 Cloud Storage 操作。

您的项目的默认服务帐号需要访问导出或导入操作中使用的 Cloud Storage 存储分区。如果您的 Cloud Storage 存储分区与您的 Datastore 模式数据库位于同一项目中,则默认情况下,默认服务帐号能够访问该存储分区

如果 Cloud Storage 存储分区位于其他项目中,则您必须为默认服务帐号授予对 Cloud Storage 存储分区的访问权限。

为默认服务帐号分配角色

您可以使用 gsutil 命令行工具分配以下角色之一。例如,如需将 Storage Admin 角色分配给默认服务帐号,请运行以下命令:

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

或者,您也可以使用 Cloud Console 分配此角色

导出操作次数

对于涉及其他项目中的存储分区的导出操作,请修改存储分区的权限,将以下 Cloud Storage 角色之一分配给您的 Datastore 模式数据库所属项目的默认服务帐号:

  • 存储管理员
  • 存储对象管理员
  • Storage Legacy Bucket Writer

您还可以创建 IAM 自定义角色,其权限与上述角色包含的权限略有不同:

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

导入操作

对于涉及其他项目中的 Cloud Storage 存储分区的导入操作,请修改存储分区的权限,将以下 Cloud Storage 角色之一分配给您的 Datastore 模式数据库所属项目的默认服务帐号:

  • 存储管理员
  • Storage Object Viewer 和 Storage Legacy Bucket Reader

您还可以创建具备以下权限的 IAM 自定义角色

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

已停用或删除默认服务帐号

如果您停用或删除 App Engine 默认服务帐号,您的 App Engine 应用将无法访问 Datastore 模式数据库。 如果您停用了 App Engine 服务帐号,可以重新启用该帐号,请参阅启用服务帐号。如果您在过去 30 天内删除了 App Engine 服务帐号,可以恢复此服务帐号,请参阅恢复删除的服务帐号

与 Datastore 管理员备份的区别

如果您之前使用过 Datastore 管理控制台进行备份,则应注意以下差异:

  • 代管式导出所创建的导出操作不会显示在 Datastore 管理控制台中。托管式导出和导入是一项新服务,不会与 App Engine 的备份和恢复功能共享数据(您可通过 Cloud Console 进行管理)。

  • 代管式导出和导入服务不支持与 Datastore 管理员备份相同的元数据,也不会将进度状态存储在数据库中。如需了解如何检查导出和导入操作的进度,请参阅管理长时间运行的操作

  • 您无法查看代管式导出和导入操作的服务日志。

  • 托管式导入服务向后兼容 Datastore 管理员备份文件。您可以使用代管式导入服务导入 Datastore 管理员备份文件,但无法使用 Datastore 管理控制台导入代管式导出的输出。

导入 BigQuery

如需将数据从托管式导出服务导入 BigQuery,请参阅加载 Datastore 导出服务数据

如果在未指定实体过滤条件的情况下导出了数据,则这些数据无法加载到 BigQuery 中。如果您想要将数据导入 BigQuery,则导出请求的实体过滤条件中必须包含一个或多个种类名称。

BigQuery 列限制

BigQuery 对表格施加的列数上限为 10000。导出操作会生成每种类型的 BigQuery 表架构。在此架构中,种类实体内的每个唯一属性都会变为架构列。

如果种类的 BigQuery 架构超过 10000 列,则导出操作会尝试将嵌入式实体视为 Blob,从而保持在列限制以下。如果此转化使架构中的列数低于 10000,您可以将数据加载到 BigQuery 中,但无法查询嵌入式实体中的属性。如果列数仍然超过 10000,则导出操作不会为该种类生成 BigQuery 架构,而且您无法将其数据加载到 BigQuery 中。

服务代理迁移

您现在可以使用 Firestore 服务代理(而不是 App Engine 服务帐号)来授权导入和导出操作。服务代理和服务帐号使用以下命名惯例:

Firestore 服务代理
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
App Engine 服务帐号
project_id@appspot.gserviceaccount.com

最好使用 Firestore 服务代理,因为它是 Firestore 专用的。App Engine 服务帐号由多个服务共享。

您可以使用以下任一方法迁移到 Firestore 服务代理:

第一种方法是首选,因为它会将效果范围本地化为单个 Datastore 模式项目。不建议采用第二种方法,因为它不会迁移现有的 Cloud Storage 存储分区权限。但是,它确实提供组织级别的安全合规性。

通过检查和更新 Cloud Storage 存储分区权限进行迁移

迁移过程包含两个步骤:

  1. 更新 Cloud Storage 存储分区权限。如需了解详情,请参阅以下部分。
  2. 确认迁移到 Firestore 服务代理。

Service Agent 存储分区权限

对于其他项目中使用 Cloud Storage 存储分区的任何导出或导入操作,您必须向 Firestore 服务代理授予该存储分区的权限。例如,将数据移到另一个项目的操作需要访问该项目中的存储分区。否则,这些操作在迁移到 Firestore 服务代理后会失败。

导入和导出项目中的工作流不需要更改权限。默认情况下,Firestore 服务代理可以访问同一项目中的存储分区。

更新其他项目中的 Cloud Storage 存储分区权限,以授予对 service-project_number@gcp-sa-firestore.iam.gserviceaccount.com 服务代理的访问权限。向服务代理授予 Firestore Service Agent 角色。

Firestore Service Agent 角色授予对 Cloud Storage 存储分区的读写权限。如果您只需要授予读取或写入权限,请使用自定义角色

以下部分中介绍的迁移过程可帮助您确定可能需要权限更新的 Cloud Storage 存储分区。

将项目迁移到 Firestore 服务代理

完成以下步骤即可从 App Engine 服务帐号迁移到 Firestore 服务代理。迁移完成后,迁移将无法撤消。

  1. 转到 Google Cloud Console 中的 Datastore 导入/导出页面。

    转到“导入/导出”页面

  2. 如果您的项目尚未迁移到 Firestore 服务代理,您将看到一个描述迁移的横幅和一个检查存储分区状态按钮。下一步可帮助您识别并修复潜在的权限错误。

    点击检查存储分区状态

    此时将显示一个菜单,其中包含用于完成迁移的选项以及一个 Cloud Storage 存储分区列表。列表可能需要几分钟才能加载完毕。

    此列表包括最近在导入和导出操作中使用的存储分区,但这些存储分区目前不向 Datastore 模式服务代理授予读写权限。

  3. 记下项目的 Datastore 模式服务代理的主名称。服务代理名称会显示在向其授予访问权限的 Service Agent 标签下方。
  4. 对于列表中将用于未来导入或导出操作的任何存储分区,请完成以下步骤:

    1. 在此存储分区表中的行,点击修复。 此时会在新标签页中打开该存储分区的权限页面。

    2. 点击添加
    3. 新主帐号字段中,输入您的 Firestore 服务代理的名称。
    4. 选择角色字段中,选择 Service Agents >Firestore Service Agent
    5. 点击保存
    6. 返回包含“Datastore 模式导入/导出”页面的标签页。
    7. 对列表中的其他存储分区重复上述步骤。请务必查看列表的所有页面。
  5. 点击迁移到 Firestore 服务代理。如果您的存储分区仍未通过权限检查,则需要点击迁移来确认迁移。

    迁移完成后,系统会向您发送提醒。迁移操作无法撤消。

查看迁移状态

如需验证项目的迁移状态,请转到 Google Cloud Console 中的导入/导出页面:

转到“导入/导出”页面

已用服务帐号:标签旁边找到主帐号。

如果主帐号为 service-project_number@gcp-sa-firestore.iam.gserviceaccount.com,则表示您的项目已迁移至 Firestore 服务代理。迁移操作无法撤消。

如果项目尚未迁移,则页面顶部会显示一个包含检查存储分区状态按钮的横幅。请参阅迁移到 Firestore 服务代理以完成迁移。

添加组织范围的政策限制

在组织政策中设置以下限制条件:

需要 Firestore Service Agent 才能导入/导出 (firestore.requireP4SAforImportExport)。

此限制条件要求导入和导出操作以使用 Firestore 服务代理来授权请求。

如需设置此限制条件,请参阅创建和管理组织政策

应用此组织政策限制条件不会自动为 Firestore 服务代理授予相应的 Cloud Storage 存储分区权限。

如果该限制条件为任何导入或导出工作流创建了权限错误,您可以将其停用以重新使用默认服务帐号。检查和更新 Cloud Storage 存储分区权限后,您可以再次启用该限制条件。