Crea un set di dati

La creazione di un set di dati è un processo in due passaggi:

  1. Effettua una richiesta per creare il set di dati.

  2. Effettua una richiesta per caricare i dati nel set di dati.

Dopo il caricamento iniziale dei dati, puoi caricarne di nuovi nel set di dati per creare una nuova versione.

Crea il set di dati

Crea un set di dati inviando una richiesta POST all'endpoint set di dati:

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

Passa un corpo JSON alla richiesta che definisce il set di dati. Devi:

  • Specifica il valore displayName del set di dati. Il valore di displayName deve essere univoco per tutti i set di dati.

  • Imposta usage su USAGE_DATA_DRIVEN_STYLING.

Ad esempio:

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 risposta contiene l'ID del set di dati, nel formato projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID insieme a informazioni aggiuntive. Utilizza l'ID set di dati quando effettui richieste per aggiornare o modificare il set di dati.

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

Carica i dati nel set di dati

Dopo aver creato il set di dati, carica i dati da Google Cloud Storage o da un file locale nel set di dati.

L'operazione di caricamento è asincrona. Dopo averli caricati, i dati vengono importati ed elaborati. Ciò significa che devi inviare una richiesta GET HTTP per monitorare lo stato del set di dati al fine di determinare quando è pronto per l'uso o se si sono verificati errori. Per ulteriori informazioni, consulta Ottenere lo stato dell'elaborazione dei dati.

Carica i dati da Cloud Storage

Per eseguire il caricamento da Cloud Storage nel tuo set di dati, invia una richiesta POST all'endpoint set di dati che include anche l'ID del set di dati:

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

Nel corpo della richiesta JSON:

  • Utilizza inputUri per specificare il percorso del file della risorsa contenente i dati in Cloud Storage. Questo percorso ha il formato gs://GCS_BUCKET/FILE.

    L'utente che effettua la richiesta deve disporre del ruolo Visualizzatore di oggetti dello spazio di archiviazione o di qualsiasi altro ruolo che includa l'autorizzazione storage.objects.get. Per ulteriori informazioni sulla gestione degli accessi a Cloud Storage, consulta Panoramica del controllo dell'accesso.

  • Utilizza fileFormat per specificare il formato file dei dati come: FILE_FORMAT_GEOJSON (file GeoJson), FILE_FORMAT_KML (file KML) o FILE_FORMAT_CSV (file CSV).

Ad esempio:

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 risposta è nel formato:

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

Caricare i dati da un file

Per caricare i dati da un file, invia una richiesta HTTP POST all'endpoint datasets che include anche l'ID del set di dati:

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

La richiesta contiene:

  • L'intestazione Goog-Upload-Protocol è impostata su multipart.

  • La proprietà metadata che specifica il percorso di un file che specifica il tipo di dati da caricare, come: FILE_FORMAT_GEOJSON (file GeoJSON), FILE_FORMAT_KML (file KML) o FILE_FORMAT_CSV (file CSV).

    I contenuti di questo file hanno il seguente formato:

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

  • La proprietà rawdata che specifica il percorso del file GeoJSON, KML o CSV contenente i dati da caricare.

La seguente richiesta utilizza l'opzione curl -F per specificare il percorso dei due file:

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 risposta è nel formato:

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

Ottieni stato di elaborazione dati

L'operazione di caricamento è asincrona. Ciò significa che una volta restituita la chiamata API per caricare i dati nel set di dati, devi eseguire il polling del set di dati per determinare se l'importazione e l'elaborazione dei dati sono riuscite o non sono riuscite.

Per determinare la state del set di dati, utilizza Ottieni un set di dati. Ad esempio, durante l'elaborazione dei dati, state è impostato su STATE_PROCESSING. Quando il set di dati è pronto per essere utilizzato nella tua app, state è impostato su STATE_COMPLETED.

Ad esempio, effettua una chiamata GET sul set di dati:

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"

Per un caricamento riuscito, il state del set di dati è 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
}

Quando l'elaborazione dei dati non va a buon fine, state viene impostato su un valore diverso da STATE_COMPLETED, ad esempio STATE_PUBLISHING_FAILED o su qualsiasi stato che termina con la stringa _FAILED.

Ad esempio, carichi i dati in un set di dati e poi effettui una richiesta GET per recuperare i dettagli del set di dati. Oltre alla proprietà state, la risposta include anche una singola proprietà errorMessage contenente una descrizione dell'errore.

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

Ricevere errori di elaborazione dei dati

Quando l'importazione e l'elaborazione dei dati non riescono, la proprietà errorMessage contiene un singolo messaggio che descrive l'errore. Tuttavia, un singolo messaggio di errore non fornisce necessariamente informazioni sufficienti per identificare e risolvere i problemi.

Per informazioni complete sugli errori, chiama l'API fetchDatasetErrors. Questa API restituisce tutti gli errori di elaborazione dei dati associati a un set di dati:

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 risposta contiene l'array errors. Questo array contiene fino a 50 errori di tipo Status per chiamata e supporta fino a 500 errori in totale:

{
  "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)"
    },
    ...
  ]
}

Se sono presenti più di 50 errori, ovvero più di una pagina di errori, la risposta conterrà un token di pagina nel campo nextPageToken. Passa questo valore nel parametro di query pageToken di una chiamata successiva per visualizzare la pagina di errori successiva. Quando nextPageToken è vuoto, non ci sono altre pagine.

Ad esempio, per visualizzare la pagina successiva di errori utilizzando il token della risposta precedente:

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"

Per impostazione predefinita, la risposta contiene un massimo di 50 errori per pagina. Utilizza il parametro di query pageSize per controllare le dimensioni della pagina.

Carica nuovi dati nel set di dati

Dopo aver creato il set di dati e caricato correttamente i dati iniziali, lo stato del set di dati viene impostato su STATE_COMPLETED. Ciò significa che il set di dati è pronto per essere utilizzato nella tua app. Per determinare il state del set di dati, consulta Ottenere un set di dati.

Puoi anche caricare nuovi dati nel set di dati per crearne una nuova versione. Per caricare nuovi dati, utilizza la stessa procedura utilizzata per Caricare i dati da Cloud Storage o Caricare i dati da un file e specificare i nuovi dati da caricare.

Se i nuovi dati vengono caricati correttamente:

  • Lo stato della nuova versione del set di dati è impostato su STATE_COMPLETED.

  • La nuova versione diventa "attiva" ed è la versione utilizzata dalla tua app.

Se si verifica un errore durante il caricamento:

  • Lo stato della nuova versione del set di dati è impostato su uno dei seguenti stati:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • La versione riuscita del set di dati precedente rimane la versione "attiva" ed è la versione utilizzata dalla tua app.