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 creare una nuova versione del set di dati.
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. È inclusa la "Z" in formato WKT, e la coordinata dell'altitudine nel formato GeoJSON.
Best practice per la preparazione dei dati
Se i dati di origine sono complessi o grandi, ad esempio punti densi, lunghe stringhe di linee o poligoni (spesso le dimensioni dei file di origine superiori a 50 MB rientrano in questa categoria), ti consigliamo di semplificare i dati prima del caricamento 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 lo stile la mappa, ad esempio "id" e "category". Puoi unire altre proprietà a una funzionalità in un cliente utilizzando stili basati sui dati su una chiave di identificazione univoca. Ad esempio, vedi Visualizza i dati in tempo reale con gli stili basati sui dati.
- Se possibile, utilizzare tipi di dati semplici per gli oggetti delle proprietà, come numeri interi, per ridurre al minimo le dimensioni del riquadro e migliorare le prestazioni della mappa.
- Semplifica geometrie complesse prima di caricare un file. Puoi farlo in una strumento geospaziale di tua scelta, come l'open source Mapshaper.org o in BigQuery utilizzando ST_Simplify su geometrie poligonali complesse.
- Cluster con punti molto densi prima di caricare un file. Puoi farlo in una strumento geospaziale di tua scelta, come l'open source funzioni cluster turf.js o in BigQuery utilizzando ST_CLUSTERDBSCAN per 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 la classe attuale Specifiche 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 più 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 ulteriori informazioni su GeoJSON, vedi Conforme 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.
- 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
ezip
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
.
Perché x
e y
hanno una priorità più alta, in base a quanto stabilito dall'ordine dei
nomi delle colonne supportati nell'elenco precedente, i valori nelle colonne x
e y
e la colonna wkt
viene ignorata.
Inoltre:
- Ogni nome di colonna deve appartenere a una singola colonna. Ciò significa che non puoi avere una colonna denominata
xy
che contiene dati delle coordinate x e y. Le coordinate x e y devono essere nel formato 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
elong
colonne, possono verificarsi 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 .
Errori GeoJSON
Gli errori più comuni di GeoJSON includono:
- Campo
type
mancante oppuretype
non è una stringa. L'oggetto caricato Il file di dati GeoJSON deve contenere un campo stringa denominatotype
Definizione degli oggetti feature e 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 i valori 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
ezip
address
- Una singola colonna contenente tutte le informazioni sull'indirizzo, ad esempio
1600 Amphitheatre Parkway Mountain View, CA 94043
- Se
x
ey
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
ey
. Se vengono utilizzate le unità errate, il set di dati potrebbe importare 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'oggetto
Endpoint set di dati:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Trasmettere un corpo JSON. alla richiesta che definisce il set di dati. Devi:
Specifica il valore
displayName
del set di dati. Il valoredisplayName
deve univoco per tutti i set di dati.Imposta
usage
suUSAGE_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, nella forma
projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
insieme a informazioni aggiuntive. Utilizza l'ID del set di dati quando effettui richieste a
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 al set di dati.
Carica dati da Cloud Storage
Per caricare dati da Cloud Storage al tuo set di dati, invia una richiesta POST
all'oggetto
dell'endpoint set di dati
include 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 formatogs://GCS_BUCKET/FILE
.L'utente che effettua la richiesta richiede un oggetto Storage Visualizzatore o qualsiasi altro ruolo che includa l'autorizzazione
storage.objects.get
. Per per ulteriori 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) oFILE_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 al
dell'endpoint set di dati
include 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 sumultipart
.La proprietà
metadata
che specifica il percorso di un file che specifica tipo di dati da caricare, comeFILE_FORMAT_GEOJSON
(file GeoJSON),FILE_FORMAT_KML
(file KML) oFILE_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 caricato i dati iniziali correttamente, lo stato
del set di dati è impostato su STATE_COMPLETED
. Ciò significa che il set di dati è pronto
utilizzare nella tua app. Per determinare il valore state
del set di dati, consulta Ottenere un
del set di dati.
Puoi anche caricare nuovi dati nel set di dati per creare una nuova versione del del set di dati. Per caricare nuovi dati, utilizza la stessa procedura utilizzata per il caricamento dei dati. da Cloud Storage o Carica 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 dell'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 corretta del set di dati precedente rimane "attiva" della versione precedente ed è la versione utilizzata dalla tua app.