Caricamento manifest della tabella

Se hai bisogno di una maggiore flessibilità per il caricamento delle tabelle in Google Earth Engine (EE) rispetto a quanto fornito dall'interfaccia utente di Code Editor o dal comando upload dello strumento a riga di comando "earthengine", puoi farlo descrivendo un caricamento di tabelle utilizzando un file JSON noto come "manifest" e utilizzando il comando upload table --manifest dello strumento a riga di comando.

Configurazione una tantum

  1. I caricamenti dei manifest funzionano solo con i file in Google Cloud Storage. Per iniziare a utilizzare Google Cloud Storage, crea un progetto Google Cloud, se non ne hai già uno. Tieni presente che la configurazione richiede la specifica di una carta di credito per la fatturazione. Al momento EE non addebita alcun costo, ma il trasferimento dei file su Google Cloud Storage prima di caricarli su EE comporta un piccolo costo. Per dimensioni dei dati di caricamento tipicamente elevate (decine o centinaia di gigabyte), il costo sarà piuttosto basso.
  2. Nel progetto, abilita l'API Cloud Storage e crea un bucket.
  3. Installa il client Earth Engine per Python. Include lo strumento a riga di comando earthengine, che useremo per caricare i dati.
  4. Per i caricamenti automatici, ti consigliamo di utilizzare un account di servizio Google Cloud associato al tuo progetto. Non è necessario un account di servizio per i test, ma quando hai tempo, inizia a familiarizzare con il loro utilizzo.

ID e nomi delle risorse

Per gli asset nei progetti Cloud, utilizza projects/my_cloud_project/assets/my_asset.

Per i progetti precedenti, il nome della risorsa nel manifest deve essere leggermente diverso dall'ID risorsa visibile altrove in Earth Engine. Per caricare asset i cui ID iniziano con users/some_user o projects/some_project, al nome della risorsa nel manifest deve essere anteposta la stringa projects/earthengine-legacy/assets/ all'ID. Ad esempio, l'ID risorsa EE users/username/my_table deve essere caricato utilizzando il nome projects/earthengine-legacy/assets/users/username/my_table.

Sì, questo significa che ID come projects/some_projects/some_asset vengono convertiti in nomi in cui projects viene menzionato due volte: projects/earthengine-legacy/assets/projects/some_projects/some_asset. Questo può creare confusione, ma è necessario per rispettare gli standard delle API Google Cloud.

Utilizzo dei manifest

Di seguito è riportato il manifest più semplice possibile. Carica un file denominato small.csv da un bucket Google Cloud Storage denominato gs://earthengine-test.

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/small.csv"
      ]
    }
  ]
}

Per utilizzarlo, salvalo in un file denominato manifest.json ed esegui:

earthengine upload table --manifest /path/to/manifest.json

Il file gs://earthengine-test/small.csv esiste ed è pubblicamente leggibile, puoi utilizzarlo per i test.

Per i caricamenti di shapefile, specifica solo il file .shp; gli altri file verranno rilevati automaticamente.

Più fonti

È possibile specificare più origini CSV o shapefile, con un file per origine. In questo caso, ogni file CSV deve avere la stessa struttura. Ad esempio, abbiamo due file CSV, region1.csv e region2.csv:

id forma
1 {"type":"Point","coordinates":[-119,36]}
2 {"type":"Point","coordinates":[-118,37]}
3 {"type":"Point","coordinates":[-117,38]}
id forma
4 {"type":"Point","coordinates":[-112,40]}
5 {"type":"Point","coordinates":[-111,41]}
6 {"type":"Point","coordinates":[-110,42]}

Hanno la stessa struttura, ma contenuti diversi. Sono stati caricati in un bucket Cloud Storage: gs://earthengine-test/region1.csv e gs://earthengine-test/region2.csv. Per importarli come asset Earth Engine, crea un manifest con due voci nell'elenco sources, come segue:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/region1.csv"
      ]
    },
    {
      "uris": [
        "gs://earthengine-test/region2.csv"
      ]
    }
  ]
}

Ora di inizio e ora di fine

Per tutti gli asset è necessario specificare l'ora di inizio e di fine per fornire un contesto più ampio ai dati, soprattutto se sono inclusi nelle raccolte. Questi campi non sono obbligatori, ma ti consigliamo vivamente di utilizzarli, se possibile.

In genere, l'ora di inizio e di fine indica l'ora dell'osservazione, non l'ora in cui è stato prodotto il file di origine.

Per semplicità, l'ora di fine viene trattata come un confine esclusivo. Ad esempio, per gli asset che coprono esattamente un giorno, utilizza la mezzanotte di due giorni consecutivi (ad esempio 1980-01-31T00:00:00 e 1980-02-01T00:00:00) per l'ora di inizio e di fine. Se la risorsa non ha durata, imposta l'ora di fine uguale a quella di inizio. Rappresenta le ore nei manifest come stringhe ISO 8601. Per semplificare i valori della data, ti consigliamo di assumere che l'ora di fine sia esclusa (ad esempio la mezzanotte del giorno successivo per gli asset giornalieri).

Esempio:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://bucket/table_20190612.csv"
      ]
    }
  ],
  "startTime": "1980-01-31T00:00:00Z",
  "endTime": "1980-02-01T00:00:00Z"
}

Riferimento alla struttura del manifest

La seguente struttura JSON include tutti i possibili campi del manifest per il caricamento delle tabelle. Trova le definizioni dei campi nella seguente sezione Definizioni dei campi del manifest.

{
  "name": <string>,
  "sources": [
    {
      "uris": [
        <string>
      ],
      "charset": <string>,
      "maxErrorMeters": <double>,
      "maxVertices": <int32>,
      "crs": <string>,
      "geodesic": <boolean>,
      "primaryGeometryColumn": <string>,
      "xColumn": <string>,
      "yColumn": <string>,
      "dateFormat": <string>,
      "csvDelimiter": <string>,
      "csvQualifier": <string>,
    }
  ],
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

Definizioni dei campi del manifest

nome

string

Il nome dell'asset da creare. name sia nel formato "projects/*/assets/**" (ad esempio projects/earthengine-legacy/assets/users/USER/ASSET).

sorgenti

list

Un elenco di campi che definiscono le proprietà di un file di tabella e dei relativi sidecar. Per ulteriori informazioni, consulta i seguenti campi elemento del dizionario sources.

sources[i].uris

list

Un elenco di URI dei dati da importare. Al momento sono supportati solo gli URI di Google Cloud Storage. Ogni URI deve essere specificato nel seguente formato: gs://bucket-id/object-id. L'oggetto principale deve essere il primo elemento dell'elenco e i sidecar devono essere elencati successivamente. A ogni URI viene anteposto il prefisso TableManifest.uri_prefix, se impostato.

sources[i].charset

string

Il nome del set di caratteri predefinito da utilizzare per la decodifica delle stringhe. Se è vuoto, per impostazione predefinita viene assunto il set di caratteri "UTF-8".

sources[i].maxErrorMeters

double

L'errore massimo consentito in metri durante la trasformazione della geometria tra sistemi di coordinate. Se non viene specificato, l'errore massimo è 1 metro per impostazione predefinita.

sources[i].maxVertices

int32

Il numero massimo di vertici. Se non è zero, la geometria verrà suddivisa in pezzi spazialmente sconnessi, ciascuno al di sotto di questo limite.

sources[i].crs

string

Il codice CRS o la stringa WKT predefiniti che specificano il sistema di riferimento di coordinate di qualsiasi geometria per la quale non è stato specificato un sistema. Se non viene specificato, il valore predefinito sarà EPSG:4326. Solo per origini CSV/TFRecord.

sources[i].geodesic

boolean

La strategia predefinita per l'interpretazione degli spigoli nella geometria che non ne hanno uno specificato diversamente. Se è false, i bordi sono dritti nella proiezione. Se true, i bordi sono curvi per seguire il percorso più breve sulla superficie della Terra. Se non viene specificato, il valore predefinito è false se il sistema di riferimento cartografico è un sistema di coordinate proiettato. Solo per origini CSV/TFRecord.

sources[i].primaryGeometryColumn

string

La colonna della geometria da utilizzare come geometria principale di una riga quando sono presenti più di una colonna della geometria.

Se viene lasciato vuoto e esiste più di una colonna di geometria, viene utilizzata la prima colonna di geometria trovata. Solo per origini CSV/TFRecord.

sources[i].xColumn

string

Il nome della colonna della coordinata x numerica per dedurre la geometria del punto. Se viene specificato anche yColumn e entrambe le colonne contengono valori numerici, verrà creata una colonna di geometria punto con i valori x,y nel sistema di coordinate specificato nel CRS. Se viene lasciato vuoto e il sistema di riferimento cartografico non specifica un sistema di coordinate proiettato, il valore predefinito è "longitudine". Se viene lasciato vuoto e il sistema di riferimento cartografico specifica un sistema di coordinate proiettato, viene utilizzato per impostazione predefinita una stringa vuota e non viene generata alcuna geometria punto.

Una colonna della geometria del punto generata avrà il nome {xColumn}_{yColumn}_N a cui viene aggiunto N in modo che {xColumn}_{yColumn}_N sia univoco se esiste già una colonna con il nome {xColumn}_{yColumn}. Solo per origini CSV/TFRecord.

sources[i].yColumn

string

Il nome della colonna della coordinata y numerica per dedurre la geometria del punto. Se viene specificato anche xColumn e entrambe le colonne contengono valori numerici, verrà creata una colonna di geometria punto con i valori x,y nel sistema di coordinate specificato nel CRS. Se viene lasciato vuoto e il sistema di riferimento cartografico non specifica un sistema di coordinate proiettato, il valore predefinito è "latitudine". Se viene lasciato vuoto e il sistema di riferimento cartografico specifica un sistema di coordinate proiettato, viene utilizzato per impostazione predefinita una stringa vuota e non viene generata alcuna geometria punto.

Una colonna della geometria del punto generata avrà il nome {xColumn}_{yColumn}_N a cui viene aggiunto N in modo che {xColumn}_{yColumn}_N sia univoco se esiste già una colonna con il nome {xColumn}_{yColumn}. Solo per origini CSV/TFRecord.

sources[i].dateFormat

string

Un formato con cui analizzare i campi che codificano le date. Il pattern di formato deve essere come descritto nella documentazione della classe DateTimeFormat di Joda-Time. Se viene lasciato vuoto, le date verranno importate come stringhe. Solo per origini CSV/TFRecord.

sources[i].csvDelimiter

string

Durante l'importazione dei file CSV, un singolo carattere utilizzato come delimitatore tra i valori delle colonne in una riga. Se non viene specificato, il valore predefinito è ','. Solo per origini CSV.

sources[i].csvQualifier

string

Durante l'importazione dei file CSV, un carattere che racchiude i valori delle colonne (noto anche come "carattere di virgolette"). Se non viene specificato, il valore predefinito è ". Solo per origini CSV.

Se un valore di colonna non è racchiuso tra qualificatori, gli spazi iniziali e finali vengono tagliati. Ad esempio: 

    ..., test,...            <== this value is not qualified
becomes the string value:
    "test"                   <== leading whitespace is stripped
 while: 
    ...," test",...          <== this value IS qualified with quotes
becomes the string value:
    " test"                  <== leading whitespace remains!

uriPrefix

string

Un prefisso facoltativo anteposto a tutti i uris definiti nel manifest.

startTime

integer

Il timestamp associato alla risorsa, se presente. In genere corrisponde all'ora in cui sono stati raccolti i dati. Per gli asset che corrispondono a un intervallo di tempo, ad esempio i valori medi su un mese o un anno, questo timestamp corrisponde all'inizio dell'intervallo. Specificato come secondi e (facoltativamente) nanosecondi dall'epoca (1970-01-01). Si presume che sia nel fuso orario UTC.

endTime

integer

Per gli asset che corrispondono a un intervallo di tempo, ad esempio i valori medi su un mese o un anno, questo timestamp corrisponde alla fine dell'intervallo (esclusivo). Specificato come secondi e (facoltativamente) nanosecondi dall'epoca (1970-01-01). Si presume che sia nel fuso orario UTC.

proprietà

dictionary

Un dizionario piatto arbitrario di coppie chiave/valore. Le chiavi devono essere stringhe e i valori possono essere numeri o stringhe. I valori di elenco non sono ancora supportati per gli asset caricati dagli utenti.

columnDataTypeOverrides

dictionary

Se il rilevamento automatico del tipo non funziona correttamente, utilizza questo campo con i nomi delle colonne come chiavi e una delle seguenti costanti come valori: COLUMN_DATA_TYPE_STRING, COLUMN_DATA_TYPE_NUMERIC, COLUMN_DATA_TYPE_LONG.

Limitazioni

Dimensioni del file manifest JSON

La dimensione massima del file manifest JSON è 10 MB. Se hai molti file da caricare, valuta la possibilità di ridurre il numero di caratteri necessari per descrivere il set di dati. Ad esempio, utilizza il campo uriPrefix per eliminare la necessità di fornire il percorso del bucket Google Cloud per ogni URI nell'elenco uris. Se è necessaria un'ulteriore riduzione delle dimensioni, prova ad abbreviare i nomi file.