L'API Maps Datasets è attualmente in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per saperne di più, consulta le descrizioni della fase di lancio.

Questa pagina è stata tradotta dall'API Cloud Translation.

Crea un set di dati

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

Effettua una richiesta per creare il set di dati.
Effettua 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 crearne una nuova versione.

Prerequisiti

Quando crei un set di dati:

I nomi visualizzati devono essere univoci all'interno del progetto Google Cloud.
I nomi visualizzati devono avere una lunghezza inferiore a 64 byte. Poiché questi caratteri sono rappresentati in UTF-8, in alcune lingue ogni carattere può essere rappresentato da più byte.
Le descrizioni devono essere inferiori a 1000 byte.

Durante il caricamento dei dati:

I tipi di file supportati sono CSV, GeoJSON e KML.
Le dimensioni massime supportate del file sono pari a 350 MB.
I nomi delle colonne degli attributi non possono iniziare con la stringa "?_".
Le geometrie tridimensionali non sono supportate. Sono inclusi il suffisso "Z" in formato WKT e le coordinate di altitudine in formato GeoJSON.

Best practice per la preparazione dei dati

Se i dati di origine sono complessi o di grandi dimensioni, ad esempio punti densi, lunghe stringhe di linee o poligoni (spesso le dimensioni dei file sorgente superiori a 50 MB rientrano in questa categoria), ti consigliamo di semplificare i dati prima di caricarli per ottenere le migliori prestazioni in una mappa visiva.

Di seguito sono riportate alcune best practice per la preparazione dei dati:

Riduci a icona le proprietà delle caratteristiche. Mantieni solo le proprietà delle caratteristiche necessarie per applicare uno stile alla mappa, ad esempio "id" e "category". Puoi unire proprietà aggiuntive a una funzionalità in un'applicazione client utilizzando gli stili basati sui dati in una chiave di identificatore univoco. Ad esempio, consulta Visualizzare i dati in tempo reale con gli stili basati sui dati.
Se possibile, utilizza tipi di dati semplici per gli oggetti della proprietà, ad esempio numeri interi, per ridurre al minimo le dimensioni dei riquadri e migliorare le prestazioni della mappa.
Semplifica geometrie complesse prima di caricare un file. Puoi farlo in uno strumento geospaziale a tua scelta, ad esempio l'utilità open source Mapshaper.org, oppure in BigQuery utilizzando ST_Simplify su geometrie di poligoni complesse.
Cluster con punti molto densi prima di caricare un file. Puoi farlo in uno strumento geospaziale di tua scelta, ad esempio le funzioni cluster open source turf.js, oppure in BigQuery utilizzando ST_CLUSTERDBSCAN su geometrie di punti densi.

Consulta ulteriori indicazioni sulle best practice per i set di dati in Visualizzare i dati con i set di dati e BigQuery.

Requisiti GeoJSON

L'API Maps Datasets supporta l'attuale specifica GeoJSON. L'API Maps Datasets supporta anche i file GeoJSON che contengono uno qualsiasi dei seguenti tipi di oggetti:

Oggetti geometrici. Un oggetto di geometria è una forma spaziale, descritta come un'unione di punti, linee e poligoni con fori opzionali.
Oggetti caratteristica. Un oggetto caratteristica contiene una geometria e ulteriori coppie nome/valore, il cui significato è specifico per l'applicazione.
Raccolte di funzionalità. Una raccolta di caratteristiche è un insieme di oggetti di caratteristiche.

L'API Maps Datasets non supporta i file GeoJSON contenenti dati in un sistema di riferimento di coordinate (CRS) diverso da WGS84.

Per maggiori informazioni su GeoJSON, consulta la pagina relativa alla conformità a RFC 7946.

Requisiti per i file KML

L'API Maps Datasets prevede i seguenti requisiti:

Tutti gli URL devono essere locali (o relativi) al file stesso.
Sono supportate le geometrie di punti, linee e poligoni.
Tutti gli attributi dei dati sono considerati stringhe.

Le seguenti funzionalità KML non sono supportate:

Icone o <styleUrl> definiti all'esterno del file.
Link di rete, ad esempio <NetworkLink>
Overlay del suolo, ad esempio <GroundOverlay>
Geometrie 3D o tag correlati all'altitudine, ad esempio <altitudeMode>
Specifiche della fotocamera come <LookAt>
Gli stili definiti all'interno del file KML.

Requisiti CSV

Per i file CSV, i nomi delle colonne supportati sono elencati di seguito in ordine di priorità:

latitude, longitude
lat, long
x, y
wkt (Testo noto)
address, city, state e zip
address
Una singola colonna contenente tutte le informazioni sull'indirizzo, ad esempio 1600 Amphitheatre Parkway Mountain View, CA 94043

Ad esempio, il tuo file contiene colonne denominate x, y e wkt. Poiché x e y hanno una priorità più elevata, come stabilito dall'ordine dei nomi delle colonne supportate nell'elenco precedente, vengono utilizzati i valori nelle colonne x e y e la colonna wkt viene ignorata.

Inoltre:

Ogni nome di colonna deve appartenere a una singola colonna. In altre parole, non puoi avere una colonna denominata xy che contiene dati delle coordinate x e y. Le coordinate x e y devono essere in colonne separate.
I nomi delle colonne non fanno distinzione tra maiuscole e minuscole.
L'ordine dei nomi delle colonne non è importante. Ad esempio, se il file CSV contiene lat e long colonne, queste possono apparire in qualsiasi ordine.

Gestire gli errori di caricamento dei dati

Quando carichi i dati in un set di dati, potresti riscontrare uno degli errori comuni descritti in questa sezione.

Errori GeoJSON

Gli errori più comuni di GeoJSON includono:

Campo type mancante oppure type non è una stringa. Il file di dati GeoJSON caricato deve contenere un campo stringa denominato type come parte di ogni oggetto Feature e definizione dell'oggetto Geometry.

Errori KML

Gli errori KML più comuni includono:

Il file di dati non deve contenere nessuna delle funzionalità KML non supportate elencate sopra, altrimenti l'importazione dei dati potrebbe non riuscire.

Errori CSV

Gli errori più comuni dei file CSV includono:

In alcune righe mancano valori per una colonna di geometria. Tutte le righe di un file CSV devono contenere valori non vuoti per le colonne di geometria. Le colonne della geometria includono:
- latitude, longitude
- lat, long
- x, y
- wkt
- address, city, state e zip
- address
- Una singola colonna contenente tutte le informazioni sull'indirizzo, ad esempio 1600 Amphitheatre Parkway Mountain View, CA 94043
Nota: questo errore viene spesso descritto da un messaggio nel formato "Impossibile convertire ' ' in un doppio" o "Impossibile analizzare l'input nell'area geografica.: Valore dell'area geografica mancante".
Se x e y sono le colonne di geometria, assicurati che le unità siano longitudine e latitudine. Alcuni set di dati pubblici utilizzano sistemi di coordinate diversi sotto le intestazioni x e y. Se vengono utilizzate le unità errate, il set di dati potrebbe essere importato correttamente, ma i dati visualizzati possono mostrare i punti del set di dati in posizioni impreviste.

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.

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 ulteriori informazioni. Usa 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.

Carica 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 richiede il ruolo Visualizzatore oggetti Storage o 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 dati da un file

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

Carica nuovi dati nel set di dati

Dopo aver creato il set di dati e aver 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 precedente del set di dati corretta rimane quella "attiva" e corrisponde alla versione utilizzata dalla tua app.