开始前的准备工作

本文档介绍了使用数据集时的前提条件、最佳实践和常见错误。

前提条件

创建数据集时：

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

上传数据时：

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

数据准备最佳做法

如果您的源数据复杂或庞大，例如密集点、长线串或多边形（通常源文件大小超过 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 下使用不同的坐标系。如果用错单位，或许能成功导入数据集，但渲染的数据可能会在非预期的位置显示数据集点。