Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

Создать набор данных

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

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

Передайте JSON-тело в запрос, определяющий набор данных. Необходимо:

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

Например:

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
Предыдущая успешная версия набора данных остается «активной» версией и является версией, используемой вашим приложением.