Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Crea un set di dati

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

Invia 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 POST richiesta all' endpoint dei 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:

Specificare il displayName del set di dati. Il valore di displayName deve essere univoco per tutti i set di dati.
Impostare 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 del 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 aver caricato i dati, questi vengono importati ed elaborati. Ciò significa che devi effettuare una richiesta GET HTTP per monitorare lo stato del set di dati e determinare quando è pronto per l'uso o se si sono verificati errori. Per ulteriori informazioni, consulta Recupera lo stato di trattamento dei dati.

Carica i dati da Cloud Storage

Per caricare i dati da Cloud Storage al set di dati, invia una richiesta POST all'endpoint dei 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 è nel formato gs://GCS_BUCKET/FILE.

L'utente che effettua la richiesta richiede il ruolo Visualizzatore oggetti Storage o qualsiasi altro ruolo che includa l'autorizzazione storage.objects.get. Per ulteriori informazioni sulla gestione dell'accesso a Cloud Storage, consulta Panoramica del controllo dell'accesso.
Utilizza fileFormat per specificare il formato del 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"
}

Carica i dati da un file

Per caricare i dati da un file, invia una richiesta HTTP POST all'endpoint dei set di dati 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"
}

Recupera lo stato di trattamento dei dati

L'operazione di caricamento è asincrona. Ciò significa che, dopo che la chiamata API per caricare i dati nel set di dati restituisce un valore, devi eseguire il polling del set di dati per determinare se l'importazione dati e il trattamento sono riusciti o meno.

Per determinare lo state del set di dati, utilizza Recupera un set di dati. Ad esempio, durante il trattamento dei dati, lo state è impostato su STATE_PROCESSING. Quando il set di dati è pronto per l'uso nella tua app, lo 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, lo 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 il trattamento 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 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
}

Recupera gli errori di trattamento dei dati

Quando l'importazione e il trattamento 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 ottenere informazioni complete sugli errori, chiama l' fetchDatasetErrors API. 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 della query pageToken di una chiamata successiva per ottenere la pagina successiva di 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.

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 l'uso nella tua app. Per determinare lo state del set di dati, consulta Recupera 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 utilizzata per Caricare i dati da Cloud Storage o Caricare i 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 è 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 precedente del set di dati rimane la versione "attiva" ed è la versione utilizzata dalla tua app.