创建数据集

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

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

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

前提条件

创建数据集时：

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

上传数据时：

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

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

提示：如果您的数据文件较大，其中有许多无需设置样式的属性，并且您希望优化渲染性能，请修改该文件以移除不需要的属性。减少属性的数量可缩减地图图块的大小，从而提高渲染性能。

与 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 下使用不同的坐标系。如果用错单位，或许能成功导入数据集，但渲染的数据可能会在非预期的位置显示数据集点。

发出创建数据集的请求

向 datasets 端点发送 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 或本地文件上传数据的请求后，您无法再次将数据上传到同一数据集。如果上传过程中出错，您必须重新创建数据集，然后再次尝试上传。

从 Cloud Storage 上传数据

如需从 Cloud Storage 上传到数据集，您可以向数据集端点（还包含数据集 ID）发送 POST 请求：

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