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.

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.

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.

La operación de carga es asíncrona. Después de que subas los datos, estos se que se transfieren y procesan. Esto significa que debes realizar una solicitud GET HTTP para supervisar el estado del conjunto de datos para determinar cuándo está listo para usarse o si había errores. Para obtener más información, consulta Obtén procesamiento de datos estado.

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 siguiente 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

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

Obtén el estado del procesamiento de datos

La operación de carga es asíncrona. Eso significa que después de la llamada a la API para subir los datos que muestra el conjunto de datos, debes sondear el conjunto de datos para determinar si la transferencia y el procesamiento de datos se realizó correctamente o falló.

Para determinar el state de la usa Obtener un conjunto de datos. Por ejemplo, mientras se analizan los datos procesados, state se establece en STATE_PROCESSING. Cuando el conjunto de datos está listo para usar en tu app, state se configura como 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 el 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, el elemento también incluye una sola propiedad errorMessage con 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
}

Recibir errores en el procesamiento de datos

Cuando falla la transferencia y el procesamiento de datos, la propiedad errorMessage contiene una único que describe el error. Sin embargo, un solo mensaje de error no necesita proporcionar información suficiente para identificar y solucionar los problemas.

Para obtener información completa del error, llama al fetchDatasetErrors en la API de Cloud. 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 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 el campo nextPageToken está vacío, no hay más páginas.

Por ejemplo, para obtener la siguiente página de errores usando el token del anterior respuesta:

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 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.