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

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

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

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

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

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

Создайте набор данных, отправив запрос POST к конечной точке datasets:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

Передайте в запросе тело JSON, определяющее набор данных. Кроме того, вы должны выполнить следующее:

Укажите свойства displayName набора данных. Значение displayName должно быть уникальным для всех наборов данных.
Задайте для параметра usage значение USAGE_DATA_DRIVEN_STYLING.

Примечание. Для атрибута 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

Чтобы загрузить данные из Cloud Storage в набор данных, отправьте запрос POST к конечной точке datasets, указав идентификатор набора данных:

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"
}

Загрузка данных из файла

Чтобы загрузить данные из файла, отправьте HTTP-запрос POST конечной точке datasets, указав идентификатор набора данных:

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 набора данных, ознакомьтесь с разделом Получение набора данных.

Вы также можете загрузить в набор данных новые данные, чтобы создать его новую версию. Чтобы загрузить новые данные, выполните те же действия, что и при загрузке данных из Cloud Storage или загрузке данных из файла, и укажите новые данные для загрузки.

Если новые данные загружены успешно:

Статус новой версии набора данных – STATE_COMPLETED.
Новая версия становится активной и используется в приложении.

Если при загрузке произошла ошибка:

Новой версии набора данных присваивается один из следующих статусов:
- STATE_IMPORT_FAILED
- STATE_PROCESSING_FAILED
- STATE_PUBLISHING_FAILED
- STATE_DELETION_FAILED
Предыдущая успешная версия набора данных остается активной и используется приложением.

Как создать набор данных Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Как загрузить данные в набор данных

Как загрузить данные из Cloud Storage

Загрузка данных из файла

Получение статуса обработки данных

Как получить информацию об ошибках обработки данных

Загрузите новые данные в набор данных.

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