crea un set di dati

La creazione di un set di dati prevede due passaggi:

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

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

Prerequisiti

Quando crei un set di dati:

  • I nomi visualizzati devono essere univoci all'interno del tuo progetto Google Cloud.
  • I nomi visualizzati devono contenere meno di 64 byte. Poiché questi caratteri sono rappresentati in formato 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 per i file sono 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" nel formato WKT e le coordinate di altitudine nel formato GeoJSON.

Requisiti GeoJSON

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

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

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

Per ulteriori informazioni su GeoJSON, consulta la pagina conforme a RFC 7946.

Requisiti KML

L'API Maps Datasets prevede i seguenti requisiti:

  • Tutti gli URL devono essere locali (o relativi) rispetto al file stesso.
  • Geometrie di punti, linee e poligoni supportate.
  • Tutti gli attributi dei dati sono considerati stringhe.
Le seguenti funzionalità KML non sono supportate:
  • Icone o <styleUrl> definite all'esterno del file.
  • Link di rete, ad esempio <NetworkLink>
  • Overlay del suolo, ad esempio <GroundOverlay>
  • Geometrie 3D o tag correlati all'altitudine come <altitudeMode>
  • Specifiche della fotocamera come <LookAt>
  • 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, in base all'ordine dei nomi delle colonne supportati 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 sola colonna. Ciò significa che non puoi avere una colonna denominata xy contenente dati con le coordinate x e y. Le coordinate X e Y devono trovarsi 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 le colonne lat e long, possono essere presenti in qualsiasi ordine.

Gestione degli errori di caricamento dei dati

Durante il caricamento dei 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 della definizione dell'oggetto Geometry.

Errori KML

Gli errori KML più comuni sono:

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

Errori CSV

Gli errori CSV più comuni includono:

  • In alcune righe mancano valori per una colonna geometrica. Tutte le righe di un file CSV devono contenere valori non vuoti per le colonne geometriche. 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
  • Se x e y sono le colonne geometriche, assicurati che le unità siano longitudine e latitudine. Alcuni set di dati pubblici utilizzano sistemi di coordinate diversi nelle intestazioni x e y. Se vengono utilizzate unità errate, l'importazione del set di dati potrebbe essere eseguita correttamente, ma i dati visualizzati possono mostrare i punti del set di dati in posizioni impreviste.

Esegui una richiesta per creare 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 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 del set di dati quando effettui richieste di aggiornamento o modifica.

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

Effettua una richiesta per 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.

Carica i dati da Cloud Storage

Puoi eseguire il caricamento da Cloud Storage nel tuo set di dati inviando 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. Il percorso del percorso è 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 la 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 seguente 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 POST HTTP all'endpoint 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 richiesta seguente 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 seguente formato:

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