La creación de un conjunto de datos es un proceso de dos pasos:
Realiza una solicitud para crear el conjunto de datos.
Realiza una solicitud para subir datos al conjunto de datos.
Después de la carga inicial de datos, puedes subir datos nuevos al conjunto de datos para crear una versión nueva del conjunto de datos.
Crea el conjunto de datos
Envía una solicitud POST
al extremo datasets para crear un conjunto de datos:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Pasa un cuerpo JSON a la solicitud que define el conjunto de datos. Obligaciones:
Especifica el
displayName
del conjunto de datos. El valor dedisplayName
debe ser único para todos los conjuntos de datos.Establece
usage
enUSAGE_DATA_DRIVEN_STYLING
.
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, en el formato projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
, junto con información adicional. Usa el ID del conjunto de datos cuando realices solicitudes para 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 desde Google Cloud Storage o desde un archivo local al conjunto de datos.
La operación de carga es asíncrona. Después de subir los datos, estos se transfieren y procesan. Eso significa que debes realizar una solicitud HTTP GET para supervisar el estado del conjunto de datos y determinar cuándo está listo para usarse o si hubo algún error. Para obtener más información, consulta Cómo obtener el estado de procesamiento de datos.
Sube datos desde Cloud Storage
Para subir datos de Cloud Storage a tu conjunto de datos, envía una solicitud POST
al extremo de datasets que también incluya 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 formatogs://GCS_BUCKET/FILE
.El usuario que realiza la solicitud debe tener la función de visualizador de objetos de Storage o cualquier otra función que incluya el permiso
storage.objects.get
. 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 comoFILE_FORMAT_GEOJSON
(archivo GeoJSON),FILE_FORMAT_KML
(archivo KML) oFILE_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 de un archivo, envía una solicitud HTTP POST
al extremo datasets que también incluya el ID del conjunto de datos:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
La solicitud contiene lo siguiente:
El encabezado
Goog-Upload-Protocol
se estableció enmultipart
.La propiedad
metadata
que especifica la ruta de acceso a un archivo que especifica el tipo de datos que se subirán, comoFILE_FORMAT_GEOJSON
(archivo GeoJSON),FILE_FORMAT_KML
(archivo KML) oFILE_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 contiene los datos que se subirán.
En la siguiente solicitud, se usa la opción curl -F
para especificar la ruta de acceso 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" }
Cómo obtener el estado de procesamiento de datos
La operación de carga es asíncrona. Eso significa que, después de que se devuelve la llamada a la API para subir los datos al conjunto de datos, debes sondearlo para determinar si la transferencia y el procesamiento de datos se realizaron correctamente o no.
Para determinar el state
del conjunto de datos, usa Obtener un conjunto de datos. Por ejemplo, mientras se procesan los datos, el state
se establece en STATE_PROCESSING
. Cuando el conjunto de datos está listo para usarse en tu app, state
se establece en STATE_COMPLETED
.
Por ejemplo, realiza una llamada GET al conjunto de datos:
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"
Para que la carga se realice correctamente, el state
del conjunto de datos es 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 }
Cuando falla el procesamiento de datos, state
se establece en un valor distinto de STATE_COMPLETED
, como STATE_PUBLISHING_FAILED
o cualquier estado que finalice en la cadena _FAILED
.
Por ejemplo, subes datos a un conjunto de datos y, luego, realizas una solicitud GET para obtener los detalles del conjunto de datos. Junto con la propiedad state
, la respuesta también incluye una sola propiedad errorMessage
que contiene una descripción del error.
{ "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 }
Cómo obtener errores de procesamiento de datos
Cuando fallan la transferencia y el procesamiento de datos, la propiedad errorMessage
contiene un solo mensaje que describe el error. Sin embargo, un solo mensaje de error no siempre proporciona información suficiente para identificar y solucionar los problemas.
Para obtener información completa sobre el error, llama a la API de fetchDatasetErrors
. Esta API muestra todos los errores de procesamiento de datos asociados con un conjunto de datos:
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"
La respuesta contiene el array errors
. Este array contiene hasta 50 errores de tipo Status
por llamada y admite hasta 500 errores en total:
{ "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)" }, ... ] }
Si hay más de 50 errores, es decir, más de una página de errores, la respuesta contendrá un token de página en el campo nextPageToken
.
Pasa ese valor en el parámetro de consulta pageToken
de una llamada posterior para obtener la siguiente página de errores. Cuando nextPageToken
está vacío, significa que no hay más páginas.
Por ejemplo, para obtener la siguiente página de errores con el token de la respuesta anterior, haz lo siguiente:
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"
De forma predeterminada, la respuesta contiene un máximo de 50 errores por página. Usa el parámetro de consulta pageSize
para controlar el tamaño de la página.
Sube datos nuevos al conjunto de datos
Después de crear el conjunto de datos y subir los datos iniciales correctamente, el estado del conjunto de datos se establece en STATE_COMPLETED
. Esto significa que el conjunto de datos está listo para usarse en tu app. A fin de determinar el state
del conjunto de datos, consulta Obtén un conjunto de datos.
También puedes subir datos nuevos al conjunto de datos para crear una versión nueva de este. Para subir datos nuevos, usa el mismo proceso que seguiste 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, ocurrirá lo siguiente:
El estado de la versión nueva del conjunto de datos se establece en
STATE_COMPLETED
.La versión nueva se convierte en la versión "activa" y es la que usa tu app.
Si hay un error en la carga, haz lo siguiente:
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 anterior exitosa del conjunto de datos permanece como la versión "activa" y es la versión que usa tu app.