创建数据集

创建数据集分为两个步骤：

1. 发出创建数据集的请求。

2. 发出将数据上传到数据集的请求。

初始数据上传后，您可以将新数据上传到数据集来创建 数据集的一个新版本。

前提条件

创建数据集时：

• 显示名称在 Google Cloud 项目中必须是唯一的。
• 显示名称长度必须少于 64 个字节（由于这些字符采用 UTF-8 编码表示，因此在某些语言中，每个字符可以由多个字节表示）。
• 说明文字长度必须少于 1,000 个字节。

上传数据时：

• 支持的文件类型为 CSV、GeoJSON 和 KML。
• 支持的文件大小上限为 350MB。
• 属性列名称不能以字符串“?_”开头。
• 不支持三维几何图形。此类图形在 WKT 格式中包含“Z”后缀，在 GeoJSON 格式中包含海拔高度坐标。

。

注意 ：根据数据文件的大小，上传 可能需要几分钟甚至几小时才能完成如果在上传过程中出错，您会收到一条错误消息。在数据集返回响应之前，请勿尝试删除数据集 上传操作。

注意 ：使用 Maps Datasets API 可能会在低缩放级别下放置或简化密集或复杂的数据。例如，当 当用户缩小到某个州或国家/地区（例如，缩放级别 5-12）时，平铺数据可能看起来 与放大到城市或社区时不同（例如，缩放级别 13-18）。这种情况会发生 以便结合使用图块和地图渲染程序，让图块精简且高效。

提示 ：如果您的数据文件很大且包含许多属性， 但对于样式，并且您希望优化渲染性能，请修改 文件移除不需要的属性。减少 属性可减小地图图块的大小，从而提高渲染性能。

数据准备最佳做法

源数据复杂或大型（例如密集点、长线串或多边形） （通常超过 50 MB 的源文件属于此类别），考虑简化数据 然后再上传，以便在直观地图中实现最佳效果。

以下是一些准备数据的最佳做法：

1. 最小化地图项属性。仅保留设置样式所需的地图项属性 您的地图，例如“id”和“category”您可以将其他媒体资源与客户端中的某项功能联接 在唯一标识符键上使用数据驱动型样式的应用。有关示例，请参见 使用数据驱动型样式设置实时查看数据。
2. 尽可能为属性对象使用简单的数据类型，例如整数、 以尽量减小图块大小并提高地图性能。
3. 在上传文件之前简化复杂的几何图形。您可以在 您选择的地理空间工具，例如开源的 Mapshaper.org 实用程序，或在 BigQuery 中使用 ST_Simplify 绘制复杂多边形几何图形。
4. 聚类非常密集的点，然后再上传文件。您可以在 您选择的地理空间工具，例如开源的 turf.js 集群函数，或者在 BigQuery 中 （使用 ST_CLUSTERDBSCAN） 来预测密集点几何图形

如需更多关于数据集最佳做法的指南，请参阅 使用数据集和 BigQuery 直观呈现您的数据。

与 GeoJSON 相关的要求

Maps Datasets API 支持当前的 GeoJSON 规范。 Maps Datasets API 还支持包含以下任何对象类型的 GeoJSON 文件：

• 几何图形对象。几何图形对象是一种空间形状，由一组点、线和具有可选孔的多边形所组成。
• 地图项对象。地图项对象包含几何图形以及其他“名称-值”对，其含义因应用而异。
• 地图项集合。地图项集合是一组地图项对象。

Maps Datasets API 不支持在坐标参考系统中拥有数据的 GeoJSON 文件 (CRS)（除 WGS84 以外）。

如需详细了解 GeoJSON，请参阅符合 RFC 7946 标准。

与 KML 相关的要求

Maps Datasets API 具有以下要求：

• 所有网址都必须是文件本身的本地（或相对）网址。
• 支持点、线和多边形几何图形。
• 所有数据属性均被视为字符串。

不支持以下 KML 地图项：

• 在文件以外定义的图标或 <styleUrl>。
• 网络链接，例如 <NetworkLink>
• 地面叠加层，例如 <GroundOverlay>
• 三维几何图形或与海拔高度相关的任何标记，例如 <altitudeMode>
• 摄像头规范，例如 <LookAt>
• 在 KML 文件内定义的样式。

与 CSV 相关的要求

下方列出了 CSV 文件支持的列名称（按优先级顺序）：

• latitude、longitude
• lat、long
• x、y
• wkt（已知文本）
• address、city、state、zip
• address
• 包含所有地址信息的单个列，例如 1600 Amphitheatre Parkway Mountain View, CA 94043

例如，您的文件包含名为 x、y 和 wkt 的列。根据上面列表中受支持的列名称的顺序，x 和 y 的优先级较高，因此，系统将使用 x 和 y 列中的值，并忽略 wkt 列。

此外：

• 每个列名称都必须属于单个列。也就是说，不能有同时包含 x 和 y 坐标数据的名为 xy 的列。x 坐标和 y 坐标的数据必须位于不同的列中。
• 列名称不区分大小写。
• 列名称的顺序无关紧要。例如，如果您的 CSV 文件包含 lat 列和 long 列，这两列可以按任意顺序显示。

处理数据上传错误

将数据上传到数据集时，您可能会遇到本部分所述的某种常见错误。

GeoJSON 错误

常见的 GeoJSON 错误包括：

• 缺少 type 字段，或者 type 不是字符串。上传的 GeoJSON 数据文件必须在每个地图项对象和几何图形对象的定义中包含名为 type 的字符串字段。

KML 错误

常见的 KML 错误包括：

• 数据文件不得包含上面列出的不受支持的 KML 地图项，否则数据导入操作可能会失败。

CSV 错误

常见的 CSV 错误包括：

• 某些行缺少几何图形列的值。CSV 文件中的所有行都必须包含几何图形列的非空值。几何图形列包括：
  • latitude、longitude
  • lat、long
  • x、y
  • wkt
  • address、city、state、zip
  • address
  • 包含所有地址信息的单个列，例如 1600 Amphitheatre Parkway Mountain View, CA 94043
  注意：出现这种错误时，系统通常会显示“无法将 ' ' 转换为双精度浮点值”或“无法解析地理位置输入内容：缺少地理位置值”之类的消息。
• 如果 x 和 y 是几何图形列，请确保相应单位分别为经度和纬度。某些公共数据集会在标头 x 和 y 下使用不同的坐标系。如果用错单位，或许能成功导入数据集，但渲染的数据可能会在非预期的位置显示数据集点。

创建数据集

如需创建数据集，请将 POST 请求发送到 数据集端点：

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

传递 JSON 正文 传递给定义数据集的请求。您必须：

• 指定数据集的 displayName。displayName 的值必须 在所有数据集中都是唯一的。

• 将 usage 设置为 USAGE_DATA_DRIVEN_STYLING。

  注意 ：USAGE_DATA_DRIVEN_STYLING 是唯一支持的值 usage.

例如：

curl -X POST -d '{
    "displayName": "My Test Dataset", 
    "usage": "USAGE_DATA_DRIVEN_STYLING"
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

响应包含数据集的 ID，格式为 projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID 以及其他信息向 更新或修改数据集。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "createTime": "2022-08-15T17:50:00.189682Z",
  "updateTime": "2022-08-15T17:50:00.189682Z" 
}

将数据上传到数据集

创建数据集后，从以下位置上传数据： Google Cloud Storage 或是从本地文件复制到数据集。

从 Cloud Storage 上传数据

您可以通过发送 POST 请求从 Cloud Storage 上传到您的数据集， 数据集端点， 包含数据集的 ID：

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

在 JSON 请求正文中：

• 使用 inputUri 指定包含数据的资源的文件路径 Cloud Storage 中的资源。此路径格式为 gs://GCS_BUCKET/FILE。

  发出请求的用户需要 Storage Object 查看者 角色或包含 storage.objects.get 权限的任何其他角色。对于 如需详细了解如何管理对 Cloud Storage 的访问权限，请参阅 访问权限控制概览。

• 使用 fileFormat 将数据的文件格式指定为以下任一项： FILE_FORMAT_GEOJSON（GeoJson 文件）、FILE_FORMAT_KML（KML 文件）或 FILE_FORMAT_CSV（CSV 文件）。

例如：

curl -X POST  -d '{
    "gcs_source":{
      "inputUri": "gs://my_bucket/my_csv_file",
      "fileFormat": "FILE_FORMAT_CSV"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

响应的格式如下：

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

从文件上传数据

要从文件上传数据，请将 HTTP POST 请求发送到 数据集端点， 包含数据集的 ID：

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

注意： 用于从文件上传数据的请求网址不同于网址 从 Google Cloud Storage 上传数据。

该请求包含：

• Goog-Upload-Protocol 标头设置为 multipart。

• metadata 属性，用于指定一个文件的路径，该文件指定了 要上传的数据类型，例如 FILE_FORMAT_GEOJSON（GeoJSON 文件）、 FILE_FORMAT_KML（KML 文件）或 FILE_FORMAT_CSV（CSV 文件）。

  此文件的内容格式如下：

  {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

• rawdata 属性，用于指定 GeoJSON、KML 或 CSV 文件的路径 包含要上传的数据

以下请求使用 curl -F 选项指定 文件：

curl -X POST \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Goog-Upload-Protocol: multipart" \
  -F "metadata=@csv_metadata_file" \
  -F "rawdata=@csv_data_file" \
  https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

响应的格式如下：

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

将新数据上传到数据集

创建数据集并成功上传初始数据后，状态 设置为 STATE_COMPLETED。这意味着数据集已准备好 。要确定数据集的 state，请参阅获取 数据集。

您还可以将新数据上传到数据集，以创建 数据集。如需上传新数据，请按照与上传数据相同的流程操作 从 Cloud Storage 上传数据或从文件上传数据， 并指定要上传的新数据

如果新数据上传成功：

• 新版数据集的状态设置为 STATE_COMPLETED。

• 新版本会变为“有效”版本即您的 应用。

如果上传过程中出错：

• 新数据集版本的状态会设置为以下状态之一：

  • STATE_IMPORT_FAILED
  • STATE_PROCESSING_FAILED
  • STATE_PUBLISHING_FAILED
  • STATE_DELETION_FAILED

• 上一个数据集成功版本仍保持“有效”状态版本为 您的应用所使用的版本。