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

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

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 .

  Примечание. В настоящее время 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 или из локального файла в набор данных.

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

Примечание. URL-адрес запроса для загрузки данных из файла отличается от URL-адреса для загрузки данных из Google Cloud Storage.

Запрос содержит:

• Заголовку 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"
}