创建数据集

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

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 不支持所含数据采用 WGS84 以外的坐标参考系统 (CRS) 的 GeoJSON 文件。

如需详细了解 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）以及其他信息。在发出请求以更新或修改数据集时，请使用数据集 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请求（该端点还包含数据集 ID）来从 Cloud Storage 上传到您的数据集：

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

在 JSON 请求正文中：

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

  发出请求的用户需要 Storage Object Viewer 角色或包含 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

• 上一个数据集成功版本将保持为“活动”版本，并且是您的应用使用的版本。