Как создать набор данных

Создание набора данных представляет собой двухэтапный процесс:

  1. Сделайте запрос на создание набора данных.

  2. Сделайте запрос на загрузку данных в набор данных.

После первоначальной загрузки данных вы можете загрузить в набор данных новые данные, чтобы создать новую версию набора данных.

Создайте набор данных

Создайте набор данных, отправив 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

  • Предыдущая успешная версия набора данных остается «активной» версией и используется вашим приложением.