Authentifizierung und Initialisierung

Bevor Sie über eine Clientbibliothek Anfragen an Earth Engine senden können, müssen Sie sich authentifizieren und die resultierenden Anmeldedaten verwenden, um den Earth Engine-Client zu initialisieren.

Earth Engine-Code-Editor und JavaScript

Authentifizierung und Initialisierung werden im Code-Editor automatisch verarbeitet. Sie können Anfragen über Ihr Login rechts oben im Code-Editor über ein Cloud-Projekt leiten.

Wenn Sie die JavaScript API außerhalb des Code-Editors verwenden, verwenden Sie einen der Authentifizierungshilfen in ee.data (z. B. ee.data.authenticateViaPopup()) gefolgt von ee.initialize(), wie in diesem Beispiel gezeigt.

Python und Befehlszeile

Bevor Sie die Earth Engine Python-Clientbibliothek verwenden können, müssen Sie sich authentifizieren (Ihre Identität bestätigen) und die resultierenden Anmeldedaten verwenden, um den Python-Client zu initialisieren. Bei den Authentifizierungsabläufen werden Cloud-Projekte zur Authentifizierung verwendet. Sie werden sowohl für die kostenlose (nicht kommerzielle) als auch für die kostenpflichtige Nutzung verwendet. Führen Sie zum Authentifizieren und Initialisieren Folgendes aus:

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

Dadurch wird zuerst der beste Authentifizierungsmodus für Ihre Umgebung ausgewählt und Sie werden aufgefordert, den Zugriff für Ihre Scripts zu bestätigen. Wenn bereits Anmeldedaten vorhanden sind, werden sie automatisch wiederverwendet. Führen Sie ee.Authenticate(force=True) aus, um neue Anmeldedaten zu erstellen.

Im Initialisierungsschritt wird geprüft, ob gültige Anmeldedaten vorhanden sind, die entweder über ee.Authenticate() erstellt wurden oder bereits als Google-Standardanmeldedaten vorhanden sind. Anschließend wird die Python-Clientbibliothek mit Methoden initialisiert, die vom Back-End-Server unterstützt werden. Sie müssen ein Projekt angeben, dessen Inhaber Sie sind oder für das Sie Berechtigungen haben. Weitere Informationen zum Registrieren des Projekts und zum Aktivieren der Earth Engine API finden Sie unter Cloud-Projekt einrichten. Dieses Projekt wird für die Ausführung aller Earth Engine-Vorgänge verwendet.

In der Befehlszeile lautet der entsprechende Aufruf earthengine authenticate. Wenn die Anmeldedaten abgelaufen oder ungültig sind, müssen Sie möglicherweise earthengine authenticate --force ausführen. Befehlszeilenaufrufe werden bei jedem Aufruf initialisiert. Sie können das Projekt mit dem Argument --project festlegen.

Sie können auch ein Projekt für alle zukünftigen Aufrufe konfigurieren, indem Sie earthengine set_project {my-project} ausführen. In der Befehlszeile und in ee.Initialize() wird dieser Wert verwendet, wenn kein Projekt direkt angegeben wird. Wenn die Authentifizierung über gcloud erfolgt (siehe unten), wird das von gcloud auth application-default set-quota-project {my-project} festgelegte Projekt als Endfall verwendet.

Authentifizierungsdetails

Ziel der Earth Engine-Authentifizierungsabläufe ist es, ein Sicherheitstoken aus Ihrem angemeldeten Konto abzurufen, das gespeichert werden kann, um Ihren Scripts die Berechtigung zum Zugriff auf Ihre Daten zu geben. Aus Sicherheitsgründen gibt das Authentifizierungssystem von Google solche Tokens nur an Systeme weiter, die gesichert werden können. Weitere Informationen finden Sie in den technischen Hinweisen unten.

Aufgrund der Sensibilität der beteiligten Systeme gibt es je nach Situation verschiedene Möglichkeiten, wie Sie vorgehen können. Die meisten Optionen werden über den Parameter auth_mode gesteuert: entweder als ee.Authenticate(auth_mode=...) oder earthengine authenticate --auth_mode=... in der Befehlszeile.

Wenn in Ihrer Umgebung bereits Google-Anmeldedaten vorhanden sind, müssen Sie ee.Authenticate() möglicherweise gar nicht aufrufen. Google Cloud-VMs, App Engine und andere Umgebungen bieten nutzbare „ambient credentials“ (Umgebungsanmeldedaten). gcloud auth application-default login erstellt diese auch.

Wir empfehlen jedoch, ee.Authenticate() am Anfang aller Scripts zu verwenden, um die Kompatibilität zu maximieren. Ohne auth_mode-Parameter sollte die Funktion in den meisten Fällen funktionieren. Wenn der Standardmodus jedoch nicht funktioniert, folge der Anleitung unten. So wählen Sie den Standardmodus aus:

• colab, wenn der Code in einem Google Colab-Notebook ausgeführt wird
• notebook, wenn in anderen Jupyter-Notebooks ausgeführt, die nicht zu Colab gehören
• localhost, wenn ein Webbrowser erkannt und keine gcloud-Binärdatei installiert ist
• gcloud, andernfalls. Für diesen Modus müssen Sie gcloud installieren.

Kurzanleitung und Tabelle

In diesem Entscheidungsleitfaden werden die möglichen Optionen beschrieben, wenn der von ee.Authenticate() ausgewählte Standardmodus nicht funktioniert. Wenn Sie beispielsweise in anderen Notebook-Umgebungen ausführen, müssen Sie notebook möglicherweise explizit angeben.

• Lokale Umgebung
  • „Lokal“ bedeutet, dass Sie Code in einer Python-Shell oder einem Python-Notebook auf dem Computer ausführen, auf dem Sie sich befinden – genauer gesagt auf demselben Computer, auf dem Ihr Webbrowser ausgeführt wird. Das gilt auch für Remote-Desktop-Situationen, in denen sich sowohl Python als auch der Browser auf demselben (Remote-)Computer befinden.
  • Die Verwendung von auth_mode=localhost ist am einfachsten und wird standardmäßig ausgewählt, wenn gcloud nicht installiert ist. Ihr Script funktioniert dann aber nur in lokalen Umgebungen.
  • Sowohl auth_mode=gcloud als auch auth_mode=notebook sind ebenfalls verfügbar.
• Remote-Umgebung.
  • „Remote“ bedeutet, dass sich Ihr Browser auf einem (lokalen) Computer befindet, Ihr Code aber an anderer Stelle ausgeführt wird, z. B. auf einer Remote-Workstation oder einem webbasierten Notebook.
  • Verwenden Sie in Colab auth_mode=colab oder gcloud, wenn Sie scopes für den Aufruf anderer APIs festlegen müssen.
  • Wenn Sie gcloud sowohl auf dem Remotecomputer als auch auf Ihrem lokalen Computer installieren können, verwenden Sie auth_mode=gcloud.
  • Wenn Sie ein Authentifizierungsprojekt verwenden können (siehe unten), verwenden Sie auth_mode=notebook.
  • Wenn Sie ein Projekt nicht verwenden, gcloud nicht installieren, Colab nicht verwenden oder auf demselben Computer keinen Browser verwenden können, gehen Sie so vor:
  • Wenden Sie sich noch einmal an einen Administrator, um Projekte zu erstellen. Beispiel:
    • Bitten Sie den Administrator, ein Projekt für Sie zu konfigurieren (als Inhaber, Bearbeiter oder OAuth-Konfigurationsbearbeiter).
    • Alternativ können Sie den Administrator bitten, Ihnen die Berechtigung zum Erstellen eines Projekts zu erteilen.

In dieser Tabelle sehen Sie, welche Kombinationen von Funktionen in den einzelnen Modi unterstützt werden.

	Für lokal oder remote?	Projekt erforderlich	Festlegbare Bereiche	Lokale Befehlszeile erforderlich	Projektinhaber
localhost	lokal	J	Ja	Nein	N
colab	Remote	J	Nein	Nein	N
gcloud	beide	J	Ja	Nein	N
notebook	beide	J	Ja	Nein	J

Anmeldedaten für Dienstkonten und Compute Engine

ee.Initialize() verwendet Earth Engine-Anmeldedaten (die ee.Authenticate() in ~/.config/earthengine/credentials speichert) oder ruft Anmeldedaten von google.auth.default() ab. Bei Bedarf können Sie jedoch ein credentials=-Argument übergeben, um Anmeldedaten von einem anderen Ort zu verwenden und diese Standardeinstellungen zu umgehen.

Wenn Sie Python-Code authentifizieren, der unbeaufsichtigt ausgeführt wird, sollten Sie sich mit einem Dienstkonto und nicht mit einem Nutzerkonto authentifizieren. In diesen Dokumenten finden Sie Informationen zur Verwendung von Dienstkonten mit Earth Engine. Weitere Methoden sind authenticate_service_account im Colab-Authentifizierungsmodul und die im Cloud-Leitfaden zur Authentifizierung als Dienstkonto beschriebenen Methoden.

Wenn Ihr Code auf einer Compute Engine-VM ausgeführt wird, wird für die Umgebung ein Standarddienstkonto erstellt, das ee.Initialize() standardmäßig verwendet. Möglicherweise müssen Sie das Dienstkonto für die Verwendung der Earth Engine registrieren, wenn das Cloud-Projekt, über das die VM gestartet wurde, nicht für die Verwendung mit der Earth Engine (kommerziell oder nicht kommerziell) registriert ist.

Details zu den Modi

auth_mode=colab. ee.Authenticate() erstellt oder ruft die von Colab unterstützten Standardanmeldedaten ab, indem bei Bedarf colab.auth.authenticate_user() ausgeführt wird. Die Anmeldedaten verwenden immer den Bereich cloud-platform und können auch zum Aufrufen anderer Cloud APIs verwendet werden.

auth_mode=gcloud. Dadurch wird die Authentifizierung an das gcloud-Tool delegiert. Das entspricht dem Ausführen von gcloud auth application-default login mit den Standardbereichen von Earth Engine (earthengine, cloud-platform und drive) oder den Bereichen im scopes-Argument. Der gcloud-Modus funktioniert sowohl lokal als auch remote.

Detaillierte Anleitung für den gcloud-Modus (lokal und remote)

In den folgenden Schritten wird beschrieben, wie Sie sich über eine Befehlszeile auf einem lokalen Computer authentifizieren.

1. Prüfen Sie, ob gcloud auf dem lokalen Computer installiert ist.
   • Führen Sie in einem Terminal gcloud help aus. Wenn gcloud nicht installiert ist, folgen Sie dieser Anleitung, um gcloud zu installieren.
2. Terminal des lokalen Computers
   • Führen Sie in einem Terminal earthengine authenticate aus.
   • In der Befehlsausgabe wird angezeigt, dass gcloud zum Abrufen von Anmeldedaten verwendet wird.
   • In einem Browserfenster wird eine Seite mit Kontoauswahl geöffnet. Wenn der Browser nicht automatisch geöffnet wird, klicken Sie auf die URL.
3. Browser: Kontoauswahl
   • Wählen Sie das Konto aus, das Sie für die Authentifizierung verwenden möchten.
4. Browser: Zustimmungsbildschirm
   • Geben Sie an, ob Sie die angeforderten Zugriffsbereiche gewähren möchten, und klicken Sie auf „Zulassen“.
5. Browser: Bestätigungsbildschirm
   • Im Browser wird eine Seite angezeigt, auf der bestätigt wird, dass Sie authentifiziert sind. Der Befehl earthengine authenticate im Terminalfenster gibt dann die Meldung „Autorisierungstoken erfolgreich gespeichert“ aus.
   • In seltenen Fällen erhalten Sie auf der Webseite einen Code, den Sie in die Python-Umgebung einfügen können.
6. Fahren Sie mit der Initialisierung fort.

auth_mode=localhost. Dieser Ablauf ähnelt dem von gcloud, wenn gcloud nicht installiert ist. Es führt dieselben Schritte wie gcloud aus, funktioniert aber nur lokal. Sie können eine optionale Internet-Portnummer angeben, z. B. localhost:8086, oder localhost:0 verwenden, um einen Port automatisch auszuwählen. Der Standardport ist 8085.

auth_mode=notebook. Dies ist ein allgemeiner Modus, der für Remote-Situationen entwickelt wurde, in denen keine lokalen Befehlszeilen verfügbar sind. Sie werden zur Seite „Notebook Authenticator“ weitergeleitet, auf der Sie ein „Authentifizierungsprojekt“ auswählen oder erstellen müssen. Weitere Informationen und eine Anleitung zur Fehlerbehebung finden Sie unten. Das an ee.Initialize() übergebene Projekt muss nicht mit diesem übereinstimmen. Sie können dasselbe Projekt für die Authentifizierung verwenden, während Sie in verschiedenen Projekten in verschiedenen Notizbüchern arbeiten. Es wird empfohlen, ee.Initialize() explizit ein Projekt zu übergeben. Standardmäßig wird jedoch das Authentifizierungsprojekt verwendet.

Detaillierte Anleitung für den Notebook-Modus

In den folgenden Schritten wird beschrieben, wie Sie sich über ein Notebook authentifizieren.

1. Browser: Notebook
   1. Führen Sie in einer Notebook-Codezelle den folgenden Code aus, um einen Authentifizierungsvorgang im Modus „Notebook“ zu starten.

      import ee
      ee.Authenticate()

      Klicken Sie auf den Link in der Zellenausgabe, um eine Seite des Notebook-Authentifikators in einem neuen Tab zu öffnen.
2. Browser: Notebook Authenticator
   1. Prüfen Sie, ob das richtige Nutzerkonto aufgeführt ist.
   2. Wählen Sie ein Google Cloud-Projekt für die Authentifizierung aus. Wenn Sie ein neues Projekt erstellen möchten, empfehlen wir die Namenskonvention „ee-xyz“, wobei xyz Ihr üblicher Earth Engine-Nutzername ist. Wenn Sie kein Cloud-Projekt auswählen oder erstellen können, lesen Sie den Abschnitt Fehlerbehebung unten.
   Sie müssen ausreichende IAM-Berechtigungen für die Authentifizierung haben, z. B. die Rolle „Inhaber“ oder „Bearbeiter“ für das Projekt oder die zusätzliche vordefinierte Rolle „OAuth-Konfigurationsbearbeiter“ zusätzlich zu den anderen zugewiesenen IAM-Rollen. Wenn eine andere Person in Ihrem Team bereits eine Authentifizierungskonfiguration für dieses Projekt erstellt hat, erhalten Sie eine zusätzliche Warnung. Fahren Sie nur fort, wenn der Creator ein vertrauenswürdiger Mitbearbeiter ist.
   3. Klicken Sie auf „Token generieren“.
3. Browser: Kontoauswahl
   • Daraufhin wird eine Seite mit Kontoauswahl angezeigt. Klicken Sie auf das Nutzerkonto, dem Sie über das Notebook Zugriff gewähren möchten.
4. Browser: Warnseite
   • Daraufhin wird eine Warnseite angezeigt, auf der steht, dass Google die App (d.h. den Code im Notebook) nicht erstellt hat. Klicken Sie auf „Weiter“, um die Bestätigung abzuschließen.
5. Browser: Zustimmungsbildschirm
   • Geben Sie an, ob Sie die angeforderten Berechtigungen gewähren möchten, und klicken Sie auf Weiter.
6. Browser: Bildschirm mit Autorisierungscode
   • Autorisierungsbestätigungscode kopieren
7. Browser: Notebook
   • Kehren Sie zum Notebook-Tab zurück und fügen Sie den Bestätigungscode in die Notebook-Zellenausgabe ein.
   • In der Zellenausgabe sollte „Autorisierungstoken wurde erfolgreich gespeichert“ angezeigt werden.
8. Fahren Sie mit der Initialisierung fort.

Der Notebook-Modus hat einen selten verwendeten Parameter quiet: Wenn er festgelegt ist, wird er „nicht interaktiv“ ausgeführt und es wird nicht nach dem Autorisierungscode gefragt und gewartet, bis Sie ihn eingegeben haben. Stattdessen wird ein Befehl zum Speichern des Codes ausgeführt.

Authentifizierungsprojekte

Sie müssen Inhaber, Bearbeiter oder OAuth-Konfigurationsbearbeiter des Authentifizierungsprojekts sein, das im Notebook-Modus verwendet wird. In vielen Fällen, insbesondere in kleineren Teams, kann das Authentifizierungsprojekt, das Sie auf der Seite „Notebook-Anmeldedaten-Manager“ verwenden, mit dem primären Projekt übereinstimmen, das Sie für andere Aufgaben verwenden.

Aus Sicherheitsgründen muss die „OAuth-Clientkonfiguration“ im Authentifizierungsprojekt nur einmal eingerichtet werden. Wenn Sie oder andere Nutzer aus anderen Gründen einen OAuth-Client für das Projekt eingerichtet haben, kann er nicht entfernt werden. Stattdessen wird die Fehlermeldung „Inkompatible OAuth2-Clientkonfiguration“ angezeigt. Sie müssen ein anderes Projekt für die Authentifizierung verwenden oder einen der oben genannten Modi „colab“, „localhost“ oder „gcloud“ verwenden.

Fehlerbehebung

Was kann ich tun, wenn ich kein Cloud-Projekt erstellen kann?

Einige Organisationen steuern, wer Cloud-Projekte erstellen kann. Wenn beim Erstellen eines Projekts auf der Seite „Notebook-Authentifikator“ eine Fehlermeldung angezeigt wird, können Sie Folgendes versuchen:

1. Versuchen Sie, direkt ein Projekt zu erstellen, um zu prüfen, ob Sie die erforderlichen Berechtigungen haben.
2. Fragen Sie den Administrator Ihrer Organisation, welche Prozesse für die Erstellung eines Projekts verfügbar sind.
3. Erstellen Sie ein Projekt über ein nicht geschäftliches Konto und fügen Sie das Konto, das Sie für die Arbeit verwenden, als Inhaber des Projekts hinzu. Hinweis: Einige Organisationen haben Sicherheitsrichtlinien, die den Zugriff auf OAuth-Clients von externen Projekten verhindern.

Fehler: „Die Earth Engine API wurde im Projekt XXX noch nicht verwendet oder ist deaktiviert“

Achten Sie zuerst darauf, dass Sie ein Projekt in ee.Initialize() oder in der Befehlszeile konfiguriert haben. In den Standardprojekten von Google Cloud und Colab ist Earth Engine nicht aktiviert. Zweitens muss die Earth Engine API für Ihr Projekt aktiviert sein.

Fehler: „Das Projekt hat eine inkompatible OAuth2-Clientkonfiguration“

Cloud-Projekte können nur eine OAuth2-Clientkonfiguration haben. Ob für ein Cloud-Projekt eine OAuth2-Clientkonfiguration festgelegt ist, können Sie anhand der OAuth 2.0-Client-IDs auf der Seite „Anmeldedaten“ prüfen. Sie müssen entweder ein anderes Cloud-Projekt auswählen, für das bereits eine kompatible Konfiguration vom Notebook-Authenticator eingerichtet wurde, oder ein Cloud-Projekt ohne OAuth2-Clients auswählen oder erstellen. Der Authenticator konfiguriert dieses Projekt automatisch. Leider können Nutzer mit dem OAuth-System keine Konfigurationen löschen. Sie müssen also ein anderes Projekt verwenden. Es muss nicht dasselbe Projekt sein, das für andere Earth Engine-Arbeiten verwendet wird. Dieser Fehler tritt nicht im Colab-Modus auf.

Fehler: „gcloud failed. Bitte prüfen Sie oben, ob Fehler vorliegen, und installieren Sie gegebenenfalls gcloud.

Dieser Fehler kann auftreten, wenn gcloud nicht installiert ist oder nicht in Ihrem PATH enthalten ist. Das kann auch passieren, wenn Sie ee.Authenticate(auth_mode='gcloud') in einer Notebook-Codezelle aufrufen. Verwenden Sie stattdessen ee.Authenticate(). Dabei wird standardmäßig die Authentifizierung im Notebookmodus verwendet. Wenn Sie kein Projekt erstellen können, lesen Sie die Lösung oben.

Was ist, wenn ich keinen Zugriff auf einen lokalen Computer habe, um gcloud zu installieren?

Wenn Sie in einer reinen Webumgebung ohne Zugriff auf ein lokales Terminal arbeiten und trotzdem ein Remote-Terminal verwenden müssen, können Sie das Befehlszeilentool trotzdem initialisieren, indem Sie den Notebook-Modus mit dem Befehl earthengine authenticate --auth_mode=notebook auslösen.

Fehler 400: redirect_uri_mismatch

Dieser Fehler kann auftreten, wenn Sie sich auf einem Remote-Computer authentifizieren, ohne Zugriff auf einen Webbrowser zu haben. Fügen Sie --quiet hinzu, wenn Sie earthengine authenticate über die Befehlszeile ausführen, oder ee.Authenticate(quiet=True), wenn Sie den Python-Client verwenden. Dazu müssen Sie sich auf einem Computer mit Zugriff auf einen Webbrowser mit gcloud authentifizieren.

Fehler: „Ihre Anwendung authentifiziert sich mit lokalen Standardanmeldedaten für Anwendungen. Für die earthengine.googleapis.com API ist ein Kontingentprojekt erforderlich, das standardmäßig nicht festgelegt ist.“

Dieser Fehler kann auftreten, wenn Earth Engine Ihre Projekt-ID nicht ermitteln kann. Wenn die Fehlerbehebungsoptionen von Google Cloud nicht funktionieren, versuchen Sie es mit earthengine set_project YOUR_PROJECT_ID oder gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Technische Hinweise

Für technisch Interessierte: Die Notwendigkeit dieser verschiedenen Mechanismen zur Erstellung von Anmeldedaten ergibt sich aus der Notwendigkeit, Anmeldedaten an eine bekannte und vertrauenswürdige Umgebung weiterzugeben. Im Folgenden finden Sie eine kurze Erläuterung der verschiedenen Fälle oben.

• Es gab früher einen paste-Modus, mit dem du ein Token erstellen und überall einfügen konntest. Dieser Modus wurde jedoch als zu riskant eingestuft und ist nicht mehr verfügbar.
• colab: auth.authenticate_user() fordert Sie auf, Anmeldedaten für den Authentifizierungsclient „Colab“ zu teilen, also für die Notebook-Umgebung selbst. Diese sind dann über google.auth.default() verfügbar und werden von ee.Initialize() verwendet.
• localhost: Anmeldedaten werden vom Browser an einen Port auf Ihrem lokalen Computer übergeben. In diesem Fall hängt die Ende-zu-Ende-Sicherheit davon ab, dass Ihr lokaler Computer nicht manipuliert wurde. Der Authentifizierungsclient, der angezeigt wird, ist „Earth Engine Authenticator“.
• gcloud: Dabei wird der in der gcloud-Referenz beschriebene Ablauf --launch-browser verwendet. Bei einem Remote-Computer wird --no-launch-browser verwendet. Der verwendete Authentifizierungsclient ist „Google Auth Library“.
• notebook: Wir erstellen einen neuen Authentifizierungsclient speziell für Ihre Arbeit. Ihre E-Mail-Adresse wird auf der Einwilligungsseite angezeigt. Dieser Client ist im Entwicklungsmodus. Dies ist ein Sonderfall, bei dem die älteren Tokens für den Einfügemodus zulässig sind. Wir müssen dafür Ihr eigenes Projekt verwenden, da solche Clients nicht für eine große Anzahl von Nutzern freigegeben werden können.