Создание набора данных представляет собой двухэтапный процесс:
Сделайте запрос на создание набора данных.
Сделайте запрос на загрузку данных в набор данных.
После первоначальной загрузки данных вы можете загрузить в набор данных новые данные, чтобы создать новую версию набора данных.
Создайте набор данных
Создайте набор данных, отправив запрос 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 для отслеживания состояния набора данных, чтобы определить, когда набор данных готов к использованию или возникли ли какие-либо ошибки. Дополнительные сведения см. в разделе Получение состояния обработки данных .
Загрузить данные из облачного хранилища
Вы загружаете из Cloud Storage в свой набор данных, отправляя запрос POST
на конечную точку набора данных , который также включает идентификатор набора данных:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
В теле запроса JSON:
Используйте
inputUri
, чтобы указать путь к файлу ресурса, содержащего данные в Cloud Storage. Этот путь имеет видgs:// GCS_BUCKET / FILE
.Пользователю, делающему запрос, требуется роль «Просмотр объектов хранилища» или любая другая роль, включающая разрешение
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
в конечную точку наборов данных , который также включает идентификатор набора данных:
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
содержит одно сообщение, описывающее ошибку. Однако одно сообщение об ошибке не обязательно предоставляет достаточную информацию для выявления и устранения проблем.
Чтобы получить полную информацию об ошибке, вызовите 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
-
Предыдущая успешная версия набора данных остается «активной» версией и используется вашим приложением.