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

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

  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-запрос. Дополнительную информацию см. в разделе « Получение состояния обработки данных» .

Загрузка данных из облачного хранилища.

Загрузка данных из облачного хранилища в ваш набор данных осуществляется путем отправки 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 . Дополнительную информацию об управлении доступом к облачному хранилищу см. в разделе «Обзор управления доступом» .

  • Используйте 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

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