创建数据集

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

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

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

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

创建数据集

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

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

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

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

  • 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 或是从本地文件复制到数据集。

上传操作是异步的。在您上传数据后,系统会 提取和处理也就是说,您必须发出 HTTP GET 请求 数据集的状态,用于确定数据集何时可供使用,或 出现任何错误。如需了解详情,请参阅获取数据处理 状态

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

获取数据处理状态

上传操作是异步的。也就是说,在调用 API 之后 返回数据集的数据,之后必须轮询数据集以确定 数据注入和处理是否成功。

为了确定state 请参阅获取数据集。例如,当数据被 处理后,state 会设为 STATE_PROCESSING。数据集准备就绪后 state 会设为 STATE_COMPLETED

例如,对数据集进行 GET 调用:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

如果上传成功,数据集的 stateSTATE_COMPLETED

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

当数据处理失败时,系统会将 state 设置为 STATE_COMPLETED(例如 STATE_PUBLISHING_FAILED 或任何以 字符串 _FAILED

例如,将数据上传到数据集后,执行 GET 请求 用于获取数据集详情的请求。除了 state 属性之外, 响应还包含一个 errorMessage 属性,该属性包含说明 错误。

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

获取数据处理错误

当数据注入和处理失败时,errorMessage 属性会包含 一条描述错误的单条消息。但是,一条错误消息不会 必须提供足够的信息来找出并解决问题。

要获取完整的错误信息,请调用 fetchDatasetErrors API。此 API 会返回与数据集关联的所有数据处理错误:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

响应包含 errors 数组。此数组包含最多 50 个 类型 Status 每次调用,总共最多支持 500 个错误:

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

如果错误超过 50 个,则意味着有多个网页 错误,则响应的 nextPageToken 字段中会包含页面令牌。 将该值传入后续调用的 pageToken 查询参数以获取 下一页的错误信息。当 nextPageToken 为空时,没有其他页面。

例如,如需使用上一页面中的令牌获取下一页错误, 回答:

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

默认情况下,每页响应最多包含 50 个错误。使用 pageSize 查询参数来控制页面大小。

将新数据上传到数据集

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

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

如果新数据上传成功:

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

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

如果上传过程中出错:

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

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