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

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

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

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

Предварительные условия

При создании набора данных:

  • Отображаемые имена должны быть уникальными в рамках вашего проекта Google Cloud.
  • Отображаемые имена должны быть меньше 64 байтов (поскольку эти символы представлены в кодировке UTF-8, в некоторых языках каждый символ может быть представлен несколькими байтами).
  • Описания должны быть меньше 1000 байт.

При загрузке данных:

  • Поддерживаемые типы файлов: CSV, GeoJSON и KML.
  • Максимальный поддерживаемый размер файла — 350 МБ.
  • Имена столбцов атрибутов не могут начинаться со строки «?_».
  • Трехмерная геометрия не поддерживается. Сюда входит суффикс «Z» в формате WKT и координата высоты в формате GeoJSON.

Требования GeoJSON

API наборов данных Карт поддерживает текущую спецификацию GeoJSON . API наборов данных Карт также поддерживает файлы GeoJSON, содержащие любые из следующих типов объектов:

  • Геометрические объекты . Геометрический объект — это пространственная форма, описываемая как объединение точек, линий и многоугольников с дополнительными отверстиями.
  • Особенности объектов . Объект объекта содержит геометрию плюс дополнительные пары имя/значение, значение которых зависит от приложения.
  • Коллекции функций . Коллекция объектов — это набор объектов объектов.

API наборов данных Карт не поддерживает файлы GeoJSON, содержащие данные в системе координат (CRS), отличной от WGS84 .

Дополнительную информацию о GeoJSON см. в разделе «Соответствие RFC 7946» .

Требования KML

К API наборов данных Карт предъявляются следующие требования:

  • Все URL-адреса должны быть локальными (или относительными) по отношению к самому файлу.
  • Поддерживаются точечные, линейные и полигональные геометрии.
  • Все атрибуты данных считаются строками.
Следующие функции KML не поддерживаются:
  • Значки или <styleUrl> , определенные вне файла.
  • Сетевые ссылки, например <NetworkLink>
  • Наложения земли, например <GroundOverlay>
  • 3D-геометрия или любые теги, связанные с высотой, такие как <altitudeMode>
  • Характеристики камеры, такие как <LookAt>
  • Стили, определенные в файле KML.

Требования к CSV

Для файлов CSV поддерживаемые имена столбцов перечислены ниже в порядке приоритета:

  • latitude longitude
  • lat , long
  • x , y
  • wkt (хорошо известный текст)
  • address , city , state , zip
  • address
  • Один столбец, содержащий всю адресную информацию, например 1600 Amphitheatre Parkway Mountain View, CA 94043

Например, ваш файл содержит столбцы с именами x , y и wkt . Поскольку x и y имеют более высокий приоритет, что определяется порядком поддерживаемых имен столбцов в приведенном выше списке, используются значения в столбцах x и y , а столбец wkt игнорируется.

Кроме того:

  • Каждое имя столбца должно принадлежать одному столбцу. То есть у вас не может быть столбца с именем xy , который содержит данные координат x и y. Координаты x и y должны быть в отдельных столбцах.
  • Имена столбцов нечувствительны к регистру.
  • Порядок имен столбцов не имеет значения. Например, если ваш CSV-файл содержит столбцы lat и long , они могут располагаться в любом порядке.

Обработка ошибок загрузки данных

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

Ошибки GeoJSON

К частым ошибкам GeoJSON относятся:

  • Поле type отсутствует, или type не является строкой. Загруженный файл данных GeoJSON должен содержать строковое поле с именем type как часть каждого объекта Feature и определения объекта Geometry.

Ошибки KML

К частым ошибкам KML относятся:

  • Файл данных не должен содержать ни одной из неподдерживаемых функций KML, перечисленных выше, иначе импорт данных может завершиться неудачно.

CSV-ошибки

Распространенные ошибки CSV включают в себя:

  • В некоторых строках отсутствуют значения для столбца геометрии. Все строки в файле CSV должны содержать непустые значения столбцов геометрии. Столбцы геометрии включают в себя:
    • latitude longitude
    • lat , long
    • x , y
    • wkt
    • address , city , state , zip
    • address
    • Один столбец, содержащий всю адресную информацию, например 1600 Amphitheatre Parkway Mountain View, CA 94043
  • Если x и y – это столбцы геометрии, убедитесь, что в качестве единиц измерения используются долгота и широта. Некоторые общедоступные наборы данных используют разные системы координат под заголовками x и y . Если используются неправильные единицы измерения, набор данных может быть успешно импортирован, но визуализированные данные могут отображать точки набора данных в неожиданных местах.

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

Создайте набор данных, отправив запрос 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 или из локального файла в набор данных.

Загрузить данные из облачного хранилища

Вы загружаете из 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"
}