Questa pagina è stata tradotta dall'API Cloud Translation.

Crea un set di dati

La creazione di un set di dati è una procedura in due passaggi:

Effettua una richiesta per creare il set di dati.
Invia una richiesta per caricare i dati nel set di dati.

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

Crea il set di dati

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

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

Nota: USAGE_DATA_DRIVEN_STYLING è l'unico valore supportato per usage.

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

Caricare 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 il caricamento, i dati vengono importati ed elaborati. Ciò significa che devi effettuare una richiesta HTTP GET per monitorare lo stato del set di dati per determinare quando è pronto per l'uso o se si sono verificati errori. Per maggiori informazioni, consulta Ottenere lo stato di elaborazione dei dati.

Caricare dati da Cloud Storage

Carichi i dati da Cloud Storage al tuo set di dati inviando una richiesta POST all'endpoint datasets 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 richiede il ruolo Visualizzatore oggetti di archiviazione o qualsiasi altro ruolo che includa l'autorizzazione storage.objects.get. Per maggiori informazioni sulla gestione dell'accesso 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 indica 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"
}

Ottenere lo stato del trattamento dati

L'operazione di caricamento è asincrona. Ciò significa che, dopo la restituzione della 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 meno.

Per determinare il state del set di dati, utilizza Recupera un set di dati. Ad esempio, mentre i dati vengono elaborati, state è impostato su STATE_PROCESSING. Quando il set di dati è pronto per l'uso nella tua app, state è impostato su STATE_COMPLETED.

Ad esempio, esegui 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 riesce, state viene impostato su un valore diverso da STATE_COMPLETED, ad esempio STATE_PUBLISHING_FAILED o 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 ottenere 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
}

Visualizzare gli errori di elaborazione dei dati

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

Per ottenere informazioni complete sugli errori, chiama l'API fetchDatasetErrors. Questa API restituisce tutti gli errori di trattamento 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 contiene un token di pagina nel campo nextPageToken. Passa questo valore nel parametro di query pageToken di una chiamata successiva per ottenere la pagina successiva degli errori. Quando nextPageToken è vuoto, non ci sono altre pagine.

Ad esempio, per ottenere 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 della query pageSize per controllare le dimensioni della pagina.

Caricare 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 Recuperare un set di dati.

Puoi anche caricare nuovi dati nel set di dati per creare una nuova versione del set di dati. Per caricare nuovi dati, utilizza la stessa procedura che hai seguito per caricare dati da Cloud Storage o caricare dati da un file e specifica 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 la versione "attiva" ed è quella utilizzata dalla tua app.

Se si verifica un errore nel 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 precedente del set di dati rimane la versione "attiva" ed è quella utilizzata dalla tua app.