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 datos, puedes subir datos nuevos al conjunto de datos para crear una versión nueva del conjunto de datos.

Crea el conjunto de datos

Para crear un conjunto de datos, envía una solicitud POST al extremo datasets:

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 de displayName debe ser único para todos los conjuntos de datos.

  • Establece usage en USAGE_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 actualizarlo o modificarlo.

{
  "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 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 Obtén 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 al archivo correspondiente al recurso que contiene los datos en Cloud Storage. Esta ruta tiene el formato gs://GCS_BUCKET/FILE.

    El usuario que realiza la solicitud debe tener el rol de visualizador de objetos de Storage o cualquier otro rol 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 como 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 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 establece en multipart.

  • La propiedad metadata que especifica la ruta de acceso a un archivo que especifica el 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 de acceso al archivo GeoJSON, KML o CSV que contiene los datos que deseas subir

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, state se establece en STATE_PROCESSING. Cuando el conjunto de datos esté listo para usarse en tu app, state se establecerá en STATE_COMPLETED.

Por ejemplo, realiza una llamada GET en el 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 debe ser 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 que no es 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 falla 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 contiene 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. Eso significa que el conjunto de datos está listo para usarse en tu app. Para 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 nueva versión 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 versión del conjunto de datos nuevo se establece en uno de los siguientes estados:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • La versión correcta del conjunto de datos anterior permanece como la versión "activa" y es la que usa tu app.