Autenticazione e inizializzazione

Prima di poter inviare richieste a Earth Engine tramite una libreria client, devi autenticarti e utilizzare le credenziali risultanti per inizializzare il client Earth Engine.

Editor di codice di Earth Engine e JavaScript

L'autenticazione e l'inizializzazione vengono gestite automaticamente nell'editor di codice. Puoi scegliere di inoltrare le richieste tramite un progetto Cloud dal tuo accesso in alto a destra nell'editor di codice.

Se utilizzi l'API JavaScript (al di fuori dell'editor di codice), utilizza uno degli helper di autenticazione in ee.data (ad esempio ee.data.authenticateViaPopup()) seguito da ee.initialize() come mostrato in questo esempio.

Python e riga di comando

Prima di utilizzare la libreria client Python di Earth Engine, devi autenticarti (verificare la tua identità) e utilizzare le credenziali risultanti per inizializzare il client Python. I flussi di autenticazione utilizzano Cloud Projects per l'autenticazione e vengono utilizzati sia per l'uso non a pagamento (senza costi, non commerciale) sia per l'uso a pagamento. Per eseguire l'autenticazione e l'inizializzazione, esegui

    ee.Authenticate()
    ee.Initialize(project='my-project')

Verrà prima selezionata la modalità di autenticazione migliore per il tuo ambiente e ti verrà chiesto di confermare l'accesso per i tuoi script. Se le credenziali esistono già, vengono riutilizzate automaticamente. Esegui ee.Authenticate(force=True) per creare nuove credenziali.

Il passaggio di inizializzazione verifica che esistano credenziali valide, create da ee.Authenticate() o preesistenti come credenziali predefinite di Google. Quindi inizializza la libreria client Python con i metodi supportati dal server di backend. Dovrai fornire un progetto di tua proprietà o di cui disponi delle autorizzazioni per l'utilizzo. Consulta la sezione Configurazione del progetto Cloud per registrare il progetto e attivare l'API Earth Engine. Questo progetto verrà utilizzato per eseguire tutte le operazioni di Earth Engine.

Nella riga di comando, la chiamata equivalente è earthengine authenticate. Se le credenziali sono scadute o non valide, potrebbe essere necessario eseguire earthengine authenticate --force. Le invocazioni della riga di comando verranno inizializzate a ogni chiamata e puoi utilizzare l'argomento --project per impostare il progetto.

Puoi anche configurare un progetto per tutte le chiamate future eseguendo earthengine set_project {my-project}. La riga di comando e ee.Initialize() lo utilizzeranno ogni volta che un progetto non viene specificato direttamente. Se utilizzi l'autenticazione tramite gcloud (vedi di seguito), il progetto impostato da gcloud verrà utilizzato come caso finale.gcloud auth application-default set-quota-project {my-project}

Dettagli di autenticazione

Lo scopo dei flussi di autenticazione di Earth Engine è ottenere un "token" di sicurezza dall'account con cui hai eseguito l'accesso, che può essere archiviato per concedere ai tuoi script l'autorizzazione ad accedere ai tuoi dati. Per motivi di sicurezza, il sistema di autenticazione di Google trasmetterà questi token solo ai sistemi che possono essere resi sicuri. Consulta le note tecniche di seguito.

A causa della sensibilità del tipo di sistemi coinvolti, esistono diversi modi per procedere a seconda della tua situazione specifica. La maggior parte delle opzioni è controllata dal parametro auth_mode: come ee.Authenticate(auth_mode=...) o earthengine authenticate --auth_mode=... sulla riga di comando.

Tieni presente che se le credenziali Google esistono già nel tuo ambiente, potresti non dover chiamare ee.Authenticate(). Le VM Google Cloud, App Engine e altri ambienti forniscono "credenziali di ambiente" utilizzabili e gcloud auth application-default login le crea anche.

Tuttavia, ee.Authenticate() è consigliato all'inizio di tutti gli script per massimizzare la compatibilità. Senza il parametro auth_mode, è progettato per funzionare nella maggior parte delle situazioni, ma segui i dettagli riportati di seguito se la modalità predefinita non funziona. La modalità predefinita viene selezionata come segue:

• colab se eseguito in un blocco note Google Colab
• notebook se eseguito in altri notebook Jupyter non Colab
• localhost se viene rilevato un browser web e non è installato alcun file binario gcloud
• gcloud, altrimenti. Per questa modalità devi installare gcloud.

Guida di riferimento rapido e tabella

Questa guida alla decisione illustra le possibili opzioni se la modalità predefinita selezionata da ee.Authenticate() non funziona. Ad esempio, se esegui l'operazione in altri ambienti di notebook, potrebbe essere necessario specificare notebook in modo esplicito.

• Ambiente locale.
  • "Locale" significa che stai eseguendo codice in una shell Python o in un blocco note Python sulla macchina di fronte a te o, più precisamente, sulla stessa macchina su cui è in esecuzione il browser web. Sono incluse le situazioni di desktop remoto in cui sia Python sia il browser si trovano sulla stessa macchina (remota).
  • L'utilizzo di auth_mode=localhost è più semplice e verrà selezionato per impostazione predefinita se gcloud non è installato, ma lo script funzionerà solo negli ambienti locali.
  • Sono disponibili anche auth_mode=gcloud e auth_mode=notebook.
• Ambiente remoto.
  • "Da remoto" indica che il browser si trova su una macchina (locale), ma il codice viene eseguito altrove, ad esempio su una workstation remota o su un notebook basato sul web.
  • Se sei in Colab, utilizza auth_mode=colab; in alternativa, utilizza gcloud se devi impostare scopes per chiamare altre API.
  • Se puoi installare gcloud sia sulla macchina remota sia sulla tua macchina locale, utilizza auth_mode=gcloud.
  • Se puoi utilizzare un progetto di autenticazione (vedi di seguito), usa auth_mode=notebook.
  • In caso contrario, se non riesci a utilizzare un progetto o a installare gcloud o Colab o un browser sulla stessa macchina:
  • Rivolgiti di nuovo a un amministratore per la creazione di progetti. Ad esempio:
    • Chiedi all'amministratore di configurare un progetto per te (come proprietario, editor o editor della configurazione OAuth)
    • In alternativa, chiedi all'amministratore di concederti le autorizzazioni per creare un progetto.

Questa tabella mostra le combinazioni di funzionalità supportate da ogni modalità.

Credenziali per gli account di servizio e Compute Engine

ee.Initialize() utilizzerà le credenziali di Earth Engine (che ee.Authenticate() memorizza in ~/.config/earthengine/credentials) o recupererà le credenziali da google.auth.default(), ma se necessario puoi passare un argomento credentials= per utilizzare le credenziali da un'altra posizione, ignorando queste predefinite.

Se stai autenticando il codice Python che verrà eseguito senza supervisione, ti consigliamo di eseguire l'autenticazione con un account di servizio anziché con un account utente. Consulta questa documentazione per informazioni sull'utilizzo dei service account con Earth Engine. Altri metodi includonoauthenticate_service_account nel modulo di autenticazione di Colab e i metodi descritti nella guida di Cloud per l'autenticazione come account di servizio.

Se il codice viene eseguito su una VM Compute Engine, viene creato un account di servizio predefinito per l'ambiente, che ee.Initialize() utilizzerà per impostazione predefinita. Potresti dover registrare l'account di servizio per utilizzare Earth Engine se il progetto cloud tramite il quale è stata avviata la VM non è registrato per l'utilizzo con Earth Engine (commerciale o non commerciale).

Dettagli sulle modalità

auth_mode=colab. ee.Authenticate() creerà o otterrà le credenziali predefinite supportate da Colab, eseguendo colab.auth.authenticate_user() se necessario. Le credenziali utilizzano sempre l'ambito cloud-platform e possono essere utilizzate anche per chiamare altre API Cloud.

auth_mode=gcloud. In questo modo l'autenticazione viene delegata allo strumento gcloud ed è equivalente all'esecuzione di gcloud auth application-default login con gli ambiti Earth Engine predefiniti (earthengine, cloud-platform e drive) o con gli ambiti nell'argomento scopes. La modalità gcloud funziona sia in locale che in remoto.

auth_mode=localhost. Si tratta di un flusso simile a gcloud per i casi in cui gcloud non sia installato. Esegue gli stessi passaggi di gcloud, ma funziona solo per il caso locale. Puoi fornire un numero di porta internet facoltativo, ad esempiolocalhost:8086, o utilizzare localhost:0 per selezionare automaticamente una porta. La porta predefinita è 8085.

auth_mode=notebook. Si tratta di una modalità generica progettata per funzionare in situazioni remote in cui le righe di comando locali non sono disponibili. Ti reindirizzerà alla pagina di Notebook Authenticator, dove dovrai scegliere o creare un "progetto di autenticazione". Consulta i dettagli e la guida alla risoluzione dei problemi di seguito. Il progetto passato a ee.Initialize() non deve corrispondere a questo. Puoi mantenere lo stesso progetto per l'autenticazione mentre lavori in progetti diversi in notebook diversi. Ti consigliamo di passare un progetto esplicitamente a ee.Initialize(), ma per impostazione predefinita verrà utilizzato il progetto di autenticazione.

La modalità Notebook ha un parametro quiet raramente utilizzato: se impostato, viene eseguito "senza interazione" e non richiede e non attende che tu inserisca il codice di autenticazione. Fornisce invece un comando da eseguire per salvare il codice.

Progetti di autenticazione

Devi essere un proprietario, un editor o un editor di configurazione OAuth del progetto di autenticazione utilizzato in modalità notebook. In molti casi, in particolare in team più piccoli, il progetto di autenticazione che utilizzi nella pagina di Authenticator di Notebook può essere lo stesso del progetto principale che utilizzi per altri lavori.

Per motivi di sicurezza, la "configurazione del client OAuth" nel progetto di autenticazione è una configurazione una tantum. Se tu o altri utenti avete configurato un client OAuth nel progetto per altri motivi, non può essere rimosso e visualizzerai il messaggio di errore "Configurazione del client OAuth2 incompatibile". Dovrai utilizzare un progetto diverso per l'autenticazione o le modalità colab, localhost o gcloud riportate sopra.

Risoluzione dei problemi

Cosa succede se non riesco a creare un progetto Cloud?

Alcune organizzazioni controllano chi può creare progetti Cloud. Se ricevi un messaggio di errore nella pagina di Notebook Authenticator quando provi a creare un progetto, puoi provare alcune soluzioni:

1. Prova a creare un progetto direttamente per verificare se disponi o meno delle autorizzazioni necessarie.
2. Rivolgiti all'amministratore della tua organizzazione per scoprire quali procedure sono disponibili per la creazione di un progetto.
3. Crea un progetto da un account non aziendale e aggiungi l'account che utilizzi per il lavoro come proprietario del progetto. Nota: alcune organizzazioni hanno criteri di sicurezza che impediscono l'accesso ai client OAuth da progetti esterni.

Errore: "L'API Earth Engine non è stata utilizzata in precedenza nel progetto XXX o è disabilitata"

Innanzitutto, assicurati di aver configurato un progetto in ee.Initialize() o sulla riga di comando (nei progetti predefiniti forniti da Cloud e Colab non sarà attivato Earth Engine). In secondo luogo, assicurati che l'API Earth Engine sia attivata nel tuo progetto.

Errore: "Il progetto ha una configurazione del client OAuth2 incompatibile"

I progetti Cloud possono avere una sola configurazione del client OAuth2. Puoi verificare se un progetto Cloud ha una configurazione del client OAuth2 impostata controllando gli ID client OAuth 2.0 nella pagina Credenziali. Devi selezionare un altro progetto Cloud con una configurazione compatibile già configurata dall'autenticatore di Notebook oppure selezionare o creare un progetto Cloud senza client OAuth2. L'autenticatore configurerà automaticamente questo progetto. Purtroppo, il sistema OAuth non consente agli utenti di eliminare le configurazioni, quindi è necessario utilizzare un progetto diverso. Non deve essere necessariamente lo stesso progetto utilizzato per altri lavori di Earth Engine. Tieni presente che questo errore non si verifica in modalità Colab.

Errore: "gcloud non è riuscito. Controlla se ci sono errori sopra e installa gcloud, se necessario."

Questo errore può verificarsi se gcloud non è installato o non è presente nel tuo PATH. Può verificarsi anche se chiami ee.Authenticate(auth_mode='gcloud') da una cella di codice del blocco note. Utilizza ee.Authenticate(), che per impostazione predefinita utilizza l'autenticazione in modalità notebook. Se non riesci a creare un progetto, consulta la soluzione riportata sopra.

Cosa succede se non ho accesso a una macchina locale per installare gcloud?

Se stai lavorando in un ambiente solo web senza accesso a un terminale locale e devi comunque utilizzare un terminale remoto, puoi comunque inizializzare lo strumento a riga di comando attivando la modalità notebook eseguendo il comando earthengine authenticate --auth_mode=notebook.

Errore 400: redirect_uri_mismatch

Potresti visualizzare questo errore se esegui l'autenticazione su un computer remoto senza accesso a un browser web. Prova ad aggiungere --quiet se esegui earthengine authenticate dalla riga di comando o ee.Authenticate(quiet=True) se utilizzi il client Python. Dovrai autenticarti con gcloud da un computer che ha accesso a un browser web.

Errore: "L'applicazione si autentica utilizzando le credenziali predefinite dell'applicazione locali. L'API earthengine.googleapis.com richiede un progetto quota, che non è impostato per impostazione predefinita."

Questo errore può verificarsi quando Earth Engine non riesce a determinare l'ID progetto. Se le opzioni per la risoluzione dei problemi di Google Cloud non funzionano, prova a eseguire earthengine set_project YOUR_PROJECT_ID o gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Note tecniche

Per chi è interessato alla tecnologia: la necessità di questi diversi meccanismi di creazione delle credenziali deriva dalla necessità di trasmettere le credenziali a un ambiente noto e attendibile. Ecco una breve descrizione dei diversi casi sopra riportati.

• In precedenza esisteva una modalità paste che forniva un token da incollare ovunque, ma è stata considerata troppo rischiosa e non è più disponibile.
• colab: auth.authenticate_user() ti chiederà di condividere le credenziali con il client di autenticazione "Colab", ovvero l'ambiente del notebook stesso. Questi dati sono quindi disponibili tramite google.auth.default() e utilizzati da ee.Initialize().
• localhost: le credenziali vengono passate dal browser a una porta sulla macchina locale. In questa situazione, la sicurezza end-to-end dipende dal fatto che la tua macchina locale non sia stata compromessa. Il client di autenticazione visualizzato è "Earth Engine Authenticator".
• gcloud: utilizza il flusso --launch-browser descritto nella documentazione di riferimento di gcloud e --no-launch-browser se su una macchina remota. Il client di autenticazione utilizzato è "Google Auth Library".
• notebook: creiamo un nuovo client di autenticazione appositamente per il tuo lavoro. Vedrai il tuo indirizzo email nella pagina del consenso. Questo client è impostato in modalità "sviluppo", un caso speciale che consente i token della modalità di incolla precedente. Per questo motivo, dobbiamo utilizzare il tuo progetto, perché questi clienti non possono essere condivisi con un numero elevato di utenti.