Cómo crear un conjunto de datos

La creación de un conjunto de datos es un proceso de dos pasos:

1. Realiza una solicitud para crear el conjunto de datos.

2. Realiza una solicitud para subir datos al conjunto de datos.

Después de la carga inicial de los datos, puedes subir datos nuevos al conjunto de datos para crear una nueva versión del conjunto de datos.

Requisitos previos

Cuando crees un conjunto de datos, ten en cuenta lo siguiente:

• Los nombres visibles deben ser únicos para tu proyecto de Google Cloud.
• Los nombres visibles deben tener menos de 64 bytes (dado que estos caracteres se representan en UTF-8, cada carácter puede representarse mediante varios bytes en algunos idiomas).
• Las descripciones deben tener menos de 1,000 bytes.

Cuando subas datos, ten en cuenta lo siguiente:

• Los tipos de archivo admitidos son CSV, GeoJSON y KML.
• El tamaño de archivo máximo que se admite es 350 MB.
• Los nombres de las columnas de atributos no pueden comenzar con la cadena "?_".
• No se admiten las geometrías tridimensionales. Esto incluye el sufijo "Z" en el formato WKT y la coordenada de altitud en el formato GeoJSON.

Nota: Según el tamaño del archivo de datos, la carga puede tardar minutos o incluso horas en completarse. Si la carga falla, recibirás un mensaje de error. No intentes borrar el conjunto de datos hasta que se haya devuelto una respuesta de la operación de carga.

Nota: Los mosaicos de mapas creados con datos cargados con el La API de Maps Datasets puede disminuir o simplificar los datos densos o complejos a niveles de zoom bajos. Por ejemplo, cuando un usuario alejado de un estado o país (por ejemplo, nivel de zoom 5-12), los mosaicos de datos pueden verse es diferente al zoom de una ciudad o un vecindario (por ejemplo, el nivel de zoom 13-18). Esto sucede para mantener las tarjetas delgadas y eficaces usando un procesador de mapas.

Sugerencia: Si el archivo de datos es grande y tiene muchos atributos en que no necesitas para definir el estilo y quieres optimizar el rendimiento de la renderización, edita el para quitar los atributos innecesarios. Reducir la cantidad de reduce el tamaño de los mosaicos del mapa, lo que mejora el rendimiento de la renderización.

Prácticas recomendadas para la preparación de datos

Si tus datos de origen son complejos o grandes, como puntos densos, LineString largas o polígonos (a menudo, esta categoría incluye archivos de origen superiores a 50 MB), considera simplificar los datos antes de subirlos para lograr el mejor rendimiento en un mapa visual.

Estas son algunas de las prácticas recomendadas para preparar tus datos:

1. Minimiza las propiedades de las características. Conserva solo las propiedades del componente necesarias para aplicar ajustes de diseño tu mapa (por ejemplo, "id" y "category". Puedes unir propiedades adicionales a un componente de un cliente aplicación usando estilos basados en datos en una clave de identificador única. Por ejemplo, consulta Visualiza tus datos en tiempo real con el diseño basado en datos.
2. Usa tipos de datos simples para los objetos de propiedad cuando sea posible, como números enteros, para minimizar el tamaño de los mosaicos y mejorar el rendimiento del mapa.
3. Simplifica geometrías complejas antes de subir un archivo. Puedes hacer esto en un la herramienta geoespacial de tu preferencia, como la herramienta Mapshaper.org o en BigQuery mediante ST_Simplify con geometrías complejas de polígonos.
4. Agrupa puntos muy densos antes de subir un archivo. Puedes hacer esto en un la herramienta geoespacial de tu preferencia, como la herramienta funciones de clúster turf.js o en BigQuery con ST_CLUSTERDBSCAN en geometrías de puntos densas.

Consulta orientación adicional sobre las prácticas recomendadas de los conjuntos de datos en Visualiza tus datos con conjuntos de datos y BigQuery.

Requisitos de GeoJSON

La API de Maps Datasets admite la configuración Especificación de GeoJSON. La API de Maps Datasets también admite archivos GeoJSON que contienen cualquiera de los siguientes tipos de objetos:

• Objetos de geometría. Un objeto de geometría es una forma espacial descrita como una unión de puntos, líneas y polígonos con agujeros opcionales.
• Objetos de componente. Un objeto de componente contiene una geometría y pares de nombre/valor adicionales cuyo significado es específico para cada aplicación.
• Colecciones de componentes: Una colección de características es un conjunto de objetos de características.

La API de Maps Datasets no admite archivos GeoJSON que tengan datos en un sistema de referencia de coordenadas (CRS) distinta de WGS84.

Para obtener más información sobre GeoJSON, consulta el artículo sobre el cumplimiento de RFC 7946.

Requisitos de KML

La API de Maps Datasets tiene los siguientes requisitos:

• Todas las URLs deben ser locales (o relativas) al archivo.
• Se admiten las geometrías de punto, línea y polígono.
• Todos los atributos de datos se consideran cadenas.

No se admiten los siguientes componentes de KML:

• Los íconos o <styleUrl> que se definan fuera del archivo
• Los vínculos de red, como <NetworkLink>
• Las superposiciones de suelo, como <GroundOverlay>
• Las geometrías 3D o cualquier etiqueta relacionada con la altitud, como <altitudeMode>
• Las especificaciones de cámara, como <LookAt>
• Los diseños definidos dentro del archivo KML

Requisitos de CSV

Para los archivos CSV, los nombres de columnas admitidos se indican a continuación, en orden de prioridad:

• latitude, longitude
• lat, long
• x, y
• wkt (Well-Known Text)
• address, city, state, zip
• address
• Una sola columna que contiene toda la información de la dirección, como 1600 Amphitheatre Parkway Mountain View, CA 94043

Por ejemplo, tu archivo contiene columnas llamadas x, y y wkt. Dado que x e y tienen una prioridad más alta, según el orden de los nombres de columna admitidos en la lista anterior, los valores en las columnas x y y se utilizan, y la columna wkt se ignora.

Además:

• Cada nombre de columna debe pertenecer a una sola columna. Esto significa que no puedes tener una columna llamada xy que contenga datos de coordenadas "x" e "y". Las coordenadas "x" e "y" deben estar en columnas separadas.
• Los nombres de las columnas no distinguen mayúsculas de minúsculas.
• El orden de los nombres de columna no es relevante. Por ejemplo, si tu archivo CSV contiene columnas lat y long, estas pueden mostrarse en cualquier orden.

Cómo solucionar errores de carga de datos

Cuando subes datos a un conjunto de datos, es posible que experimentes uno de los errores comunes que se describen en esta sección.

Errores de GeoJSON

Estos son algunos de los errores comunes de GeoJSON:

• Falta el campo type, o bien type no es una cadena. El archivo de datos GeoJSON subido debe contener un campo de cadena llamado type como parte de la definición de cada objeto de componente y objeto de geometría.

Errores de KML

Estos son algunos de los errores comunes de KML:

• El archivo de datos no debe contener ninguno de los componentes KML no admitidos que se mencionaron en la lista anterior. De lo contrario, la importación de datos podría fallar.

Errores de CSV

Estos son algunos de los errores comunes de CSV:

• A algunas filas les faltan valores para una columna de geometría. Todas las filas de un archivo CSV deben contener valores no vacíos para las columnas de geometría. Entre las columnas de geometría, se incluyen las siguientes:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • Una sola columna que contiene toda la información de la dirección, como 1600 Amphitheatre Parkway Mountain View, CA 94043
  Nota: Este error suele describirse con un mensaje similar al siguiente: "Unable to convert ' ' to a double" o "Could not parse input to geography.: Geography value is missing".
• Si x y y son las columnas de geometría, asegúrate de que las unidades sean de longitud y latitud. Algunos conjuntos de datos públicos usan diferentes sistemas de coordenadas bajo los encabezados x e y. Si se usan unidades incorrectas, el conjunto de datos podría importarse de forma correcta, pero los datos renderizados podrían mostrar puntos del conjunto de datos en ubicaciones inesperadas.

Crea el conjunto de datos

Envía una solicitud POST al conjunto de datos para crear un conjunto de datos Extremo datasets:

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

Pasa un cuerpo de JSON hasta la solicitud que define el conjunto de datos. Obligaciones:

• Especifica el displayName del conjunto de datos. El valor de displayName debe ser único para todos los conjuntos de datos.

• Establece usage en USAGE_DATA_DRIVEN_STYLING.

  Nota: USAGE_DATA_DRIVEN_STYLING es el único valor admitido para usage.

Por ejemplo:

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

La respuesta contiene el ID del conjunto de datos, con el siguiente formato: projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID junto con información adicional. Usa el ID del conjunto de datos cuando realices solicitudes a actualizar o modificar el conjunto de datos.

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

Sube datos al conjunto de datos

Después de crear el conjunto de datos, sube los datos de Google Cloud Storage o de un archivo local al conjunto de datos.

Sube datos desde Cloud Storage

Subes tu conjunto de datos desde Cloud Storage a través del envío de una solicitud POST al datasets que también incluye el ID del conjunto de datos:

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

En el cuerpo de la solicitud JSON, haz lo siguiente:

• Usa inputUri para especificar la ruta de acceso del archivo al recurso que contiene los datos. en Cloud Storage. Esta ruta tiene el formato gs://GCS_BUCKET/FILE

  El usuario que realiza la solicitud necesita el Objeto de almacenamiento Visualizador o cualquier otro que incluya el permiso storage.objects.get. Para para obtener más información sobre cómo administrar el acceso a Cloud Storage, consulta Descripción general del control de acceso.

• Usa fileFormat para especificar el formato de archivo de los datos de la siguiente manera: FILE_FORMAT_GEOJSON (archivo GeoJson), FILE_FORMAT_KML (archivo KML) o FILE_FORMAT_CSV (archivo CSV).

Por ejemplo:

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

La respuesta tiene el siguiente formato:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Sube datos desde un archivo

Para subir datos desde un archivo, envía una solicitud POST HTTP al datasets que también incluye el ID del conjunto de datos:

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

Nota: La URL de solicitud para subir datos desde un archivo es diferente de la URL. para subir datos desde Google Cloud Storage.

La solicitud contiene lo siguiente:

• El encabezado Goog-Upload-Protocol se estableció en multipart.

• La propiedad metadata que especifica la ruta a un archivo que especifica la tipo de datos que se subirán, como FILE_FORMAT_GEOJSON (archivo GeoJSON), FILE_FORMAT_KML (archivo KML) o FILE_FORMAT_CSV (archivo CSV).

  El contenido de este archivo tiene el siguiente formato:

  {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

• La propiedad rawdata que especifica la ruta al archivo GeoJSON, KML o CSV que contenga los datos que se subirán.

En la siguiente solicitud, se usa la opción curl -F para especificar la ruta a los dos. archivos:

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

La respuesta tiene el siguiente formato:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Sube datos nuevos al conjunto de datos

Después de crear el conjunto de datos y cargar los datos iniciales correctamente, el estado del conjunto de datos se configura como STATE_COMPLETED. Eso significa que el conjunto de datos está listo para usar en tu app. Para determinar el state del conjunto de datos, consulta Obtén un conjunto de datos.

También puedes cargar nuevos datos al conjunto de datos para crear una nueva versión del de tu conjunto de datos. Para subir datos nuevos, utilice el mismo proceso que para Subir datos. desde Cloud Storage o subir datos desde un archivo, y especifica los datos nuevos que deseas subir.

Si los datos nuevos se suben correctamente:

• El estado de la versión nueva del conjunto de datos se establece en STATE_COMPLETED.

• La versión nueva se convierte en la "activa". actual y es la versión que usa tu .

Si se produce un error en la carga:

• El estado de la nueva versión del conjunto de datos se establece en uno de los siguientes estados:

  • STATE_IMPORT_FAILED
  • STATE_PROCESSING_FAILED
  • STATE_PUBLISHING_FAILED
  • STATE_DELETION_FAILED

• La versión exitosa del conjunto de datos anterior permanece “activa” y es la versión que usa tu app.