创建数据集分为两个步骤:
发出创建数据集的请求。
发出将数据上传到数据集的请求。
初始数据上传后,您可以将新数据上传到数据集来创建 数据集的一个新版本。
前提条件
创建数据集时:
- 显示名称在 Google Cloud 项目中必须是唯一的。
- 显示名称长度必须少于 64 个字节(由于这些字符采用 UTF-8 编码表示,因此在某些语言中,每个字符可以由多个字节表示)。
- 说明文字长度必须少于 1,000 个字节。
上传数据时:
- 支持的文件类型为 CSV、GeoJSON 和 KML。
- 支持的文件大小上限为 350MB。
- 属性列名称不能以字符串“?_”开头。
- 不支持三维几何图形。此类图形在 WKT 格式中包含“Z”后缀,在 GeoJSON 格式中包含海拔高度坐标。
数据准备最佳做法
源数据复杂或大型(例如密集点、长线串或多边形) (通常超过 50 MB 的源文件属于此类别),考虑简化数据 然后再上传,以便在直观地图中实现最佳效果。
以下是一些准备数据的最佳做法:
- 最小化地图项属性。仅保留设置样式所需的地图项属性 您的地图,例如“id”和“category”您可以将其他媒体资源与客户端中的某项功能联接 在唯一标识符键上使用数据驱动型样式的应用。有关示例,请参见 使用数据驱动型样式设置实时查看数据。
- 尽可能为属性对象使用简单的数据类型,例如整数、 以尽量减小图块大小并提高地图性能。
- 在上传文件之前简化复杂的几何图形。您可以在 您选择的地理空间工具,例如开源的 Mapshaper.org 实用程序,或在 BigQuery 中使用 ST_Simplify 绘制复杂多边形几何图形。
- 聚类非常密集的点,然后再上传文件。您可以在 您选择的地理空间工具,例如开源的 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 具有以下要求:
- 所有网址都必须是文件本身的本地(或相对)网址。
- 支持点、线和多边形几何图形。
- 所有数据属性均被视为字符串。
- 在文件以外定义的图标或
<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
。
例如:
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
该请求包含:
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
上一个数据集成功版本仍保持“有效”状态版本为 您的应用所使用的版本。