此页面由 Cloud Translation API 翻译。

创建数据集

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

发出创建数据集的请求。
发出将数据上传到数据集的请求。

在初始数据上传后，您可以向数据集上传新数据，以创建数据集的新版本。

创建数据集

通过向 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 或本地文件上传至数据集。

上传操作是异步的。上传数据后，系统会注入并处理数据。这意味着您必须发出 HTTP GET 请求来监控数据集的状态，以确定数据集何时可供使用或是否存在任何错误。如需了解详情，请参阅获取数据处理状态。

从 Cloud Storage 上传数据

您可以通过向 datasets 端点发送 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"
}

通过文件上传数据

如需上传文件中的数据，请向 datasets 端点发送 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"

如果上传成功，数据集的 state 为 STATE_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
之前的成功版本会保留为“有效”版本，并成为应用使用的版本。

创建数据集 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

创建数据集

将数据上传到数据集

从 Cloud Storage 上传数据

通过文件上传数据

获取数据处理状态

获取数据处理错误

将新数据上传到数据集

创建数据集