Создание набора данных — двухэтапный процесс:
Оформите запрос на создание набора данных.
Сделайте запрос на загрузку данных в набор данных.
После первоначальной загрузки данных вы можете загрузить новые данные в набор данных, чтобы создать новую версию набора данных.
Создать набор данных
Создайте набор данных, отправив запрос 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"
Ответ содержит идентификатор набора данных в формате 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 для отслеживания состояния набора данных, чтобы определить, готов ли он к использованию или возникли ошибки. Подробнее см. в разделе Получение состояния обработки данных .
Загрузка данных из облачного хранилища
Вы загружаете данные из облачного хранилища в свой набор данных, отправляя запрос POST
на конечную точку набора данных , который также включает идентификатор набора данных:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
В теле JSON-запроса:
Используйте
inputUri
для указания пути к файлу ресурса, содержащего данные в облачном хранилище. Этот путь имеет видgs:// GCS_BUCKET / FILE
.Пользователь, выполняющий запрос, должен иметь роль « Просмотрщик объектов хранилища» или любую другую роль, включающую разрешение
storage.objects.get
. Подробнее об управлении доступом к облачному хранилищу см. в разделе «Обзор управления доступом» .Используйте
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
на конечную точку набора данных , указав также идентификатор набора данных:
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
набора данных, используйте функцию Get a dataset . Например, во время обработки данных 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
содержит одно сообщение с описанием ошибки. Однако одно сообщение об ошибке не всегда предоставляет достаточную информацию для выявления и устранения проблем.
Чтобы получить полную информацию об ошибках, вызовите API fetchDatasetErrors
. Этот 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
набора данных, см. раздел Получение набора данных .
Вы также можете загрузить новые данные в набор данных, чтобы создать его новую версию. Для загрузки новых данных используйте ту же процедуру, что и для загрузки данных из облачного хранилища или файла , и укажите новые данные для загрузки.
Если новые данные успешно загружены:
Состояние новой версии набора данных устанавливается на
STATE_COMPLETED
.Новая версия становится «активной» версией и используется вашим приложением.
Если при загрузке произошла ошибка:
Состояние новой версии набора данных устанавливается в одно из следующих состояний:
-
STATE_IMPORT_FAILED
-
STATE_PROCESSING_FAILED
-
STATE_PUBLISHING_FAILED
-
STATE_DELETION_FAILED
-
Предыдущая успешная версия набора данных остается «активной» версией и является версией, используемой вашим приложением.