Uwierzytelnianie i inicjowanie

Zanim będzie można wysyłać żądania do Earth Engine za pomocą biblioteki klienta, należy uwierzytelnić użytkownika i użyć uzyskanych danych logowania, aby zainicjować klienta Earth Engine.

Edytowanie kodu i JavaScript w Earth Engine

Uwierzytelnianie i inicjowanie są obsługiwane automatycznie w Edytorze kodu. Możesz przekierowywać żądania przez projekt Cloud, korzystając z danych logowania w prawym górnym rogu Edytora kodu.

Jeśli używasz interfejsu JavaScript API (poza edytorem kodu), użyj jednego z elementów ee.data (np. ee.data.authenticateViaPopup()), a następnie ee.initialize(), jak pokazano w tym przykładzie.

Python i wiersz poleceń

Zanim zaczniesz korzystać z biblioteki klienta Pythona Earth Engine, musisz się uwierzytelnić (potwierdzić swoją tożsamość) i użyć uzyskanych danych logowania, aby zainicjować klienta Pythona. Przepływy uwierzytelniania używają projektów Cloud do uwierzytelniania. Są one używane zarówno do bezpłatnego (niekomercyjnego) korzystania, jak i do płatnego korzystania. Aby uwierzytelnić i zainicjować, uruchom

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

Najpierw zostanie wybrany najlepszy tryb uwierzytelniania dla Twojego środowiska, a następnie wyświetli się prośba o potwierdzenie dostępu dla skryptów. Jeśli dane logowania już istnieją, zostaną automatycznie użyte ponownie. Aby utworzyć nowe dane logowania, uruchom ee.Authenticate(force=True).

Krok inicjalizacji sprawdza, czy istnieją prawidłowe dane logowania utworzone za pomocą funkcji ee.Authenticate() lub istniejące jako domyślne dane logowania Google. Następnie inicjalizuje bibliotekę klienta w Pythonie za pomocą metod obsługiwanych przez serwer zaplecza. Musisz podać projekt, którego jesteś właścicielem lub do którego masz uprawnienia. Aby zarejestrować projekt i włączyć interfejs Earth Engine API, zapoznaj się z artykułem Konfigurowanie projektu w Google Cloud. Ten projekt będzie używany do wykonywania wszystkich operacji w Earth Engine.

W wierszu poleceń odpowiednim wywołaniem jest earthengine authenticate. Jeśli dane uwierzytelniające są nieprawidłowe lub wygasły, konieczne może być uruchomienie earthengine authenticate --force. Wywołania wiersza poleceń będą inicjowane przy każdym wywołaniu, a aby ustawić projekt, możesz użyć argumentu --project.

Możesz też skonfigurować projekt na potrzeby wszystkich przyszłych wywołań, uruchamiając earthengine set_project {my-project}. Wiersz poleceń i ee.Initialize() będą używać tego parametru, gdy nie zostanie bezpośrednio określony projekt. Jeśli używasz uwierzytelniania za pomocą funkcji gcloud (patrz poniżej), jako ostateczny przypadek zostanie użyty projekt ustawiony przez gcloud auth application-default set-quota-project {my-project}.

Szczegóły uwierzytelniania

Celem przepływów uwierzytelniania Earth Engine jest uzyskanie „tokena” bezpieczeństwa z Twojego zalogowanego konta, który można przechowywać, aby umożliwić skryptom dostęp do Twoich danych. Ze względów bezpieczeństwa system uwierzytelniania Google będzie przekazywał te tokeny tylko do systemów, które można zabezpieczyć (patrz notatki techniczne poniżej).

Ze względu na wrażliwość danych systemów istnieją różne sposoby postępowania w zależności od konkretnej sytuacji. Większość opcji jest kontrolowana przez parametr auth_mode: jako ee.Authenticate(auth_mode=...) lub earthengine authenticate --auth_mode=... w wierszu poleceń.

Jeśli w Twoim środowisku są już dane logowania Google, możesz w ogóle nie potrzebować funkcji ee.Authenticate(). Maszyny wirtualne Google Cloud, App Engine i inne środowiska zapewniają użyteczne „dane logowania”, a gcloud auth application-default login również je tworzy.

Zalecamy jednak umieszczenie na początku wszystkich skryptów polecenia ee.Authenticate(), aby zmaksymalizować zgodność. W większości przypadków wystarczy użycie parametru auth_mode bez żadnych parametrów dodatkowych, ale jeśli tryb domyślny nie działa, postępuj zgodnie z instrukcjami podanymi poniżej. Tryb domyślny jest wybierany w następujący sposób:

  • colab jeśli jest uruchomiony w notatniku Google Colab,
  • notebook jeśli są uruchamiane w innych notatnikach Jupyter poza Colab
  • localhost jeśli wykryto przeglądarkę internetową, a nie zainstalowano binarnego pakietu gcloud
  • gcloud, w innych przypadkach W tym trybie musisz zainstalować gcloud.

Krótki przewodnik i tabela

Ten przewodnik pomoże Ci wybrać opcje, jeśli domyślny tryb wybrany za pomocą ee.Authenticate() nie działa. Jeśli na przykład używasz innych środowisk notebooków, może być konieczne jawne określenie notebook.

  • Środowisko lokalne.
    • „Lokalny” oznacza, że uruchamiasz kod w powłoce Python lub notatniku Python na maszynie, na której się znajdujesz – a dokładniej na tej samej maszynie, na której działa Twoja przeglądarka. Dotyczy to sytuacji, gdy Python i przeglądarka są na tym samym (zdalnym) komputerze.
    • Najłatwiej jest użyć opcji auth_mode=localhost, która zostanie wybrana domyślnie, jeśli gcloud nie jest zainstalowany. Skrypt będzie działać tylko w środowiskach lokalnych.
    • Dostępne są też opcje auth_mode=gcloud i auth_mode=notebook.
  • Środowisko zdalne.
    • „Zdalnie” oznacza, że przeglądarka jest na jednym (lokalnym) urządzeniu, ale kod jest uruchamiany gdzie indziej, np. na zdalnej stacji roboczej lub w internetowym notatniku.
    • Jeśli używasz Colab, użyj auth_mode=colab. Jeśli chcesz ustawić scopes, aby wywołać inne interfejsy API, użyj gcloud.
    • Jeśli możesz zainstalować gcloud zarówno na komputerze zdalnym, jak i na komputerze lokalnym, użyj auth_mode=gcloud.
    • Jeśli możesz użyć projektu uwierzytelniania (patrz poniżej), użyj znacznika auth_mode=notebook.
    • Jeśli nie możesz użyć projektu, zainstalować gcloud, korzystać z Colab lub przeglądarki na tym samym komputerze:
    • Skontaktuj się ponownie z administratorem w sprawie tworzenia projektów. Na przykład:
      • Poproś administratora o skonfigurowanie projektu (jako właściciela, edytującego lub edytującego konfigurację OAuth).
      • Możesz też poprosić administratora o przyznanie Ci uprawnień do tworzenia projektów.

Tabela pokazuje, które kombinacje funkcji są obsługiwane w danym trybie.

Lokalny czy zdalny? Wymagane informacje o projekcie Zakresy, które można ustawić Wymagane lokalne środowisko wiersza poleceń właściciel projektu
localhost lokalne T T N N
colab pilot T N N N
gcloud jedno i drugie T T N N
notebook jedno i drugie T T N T

Dane logowania do kont usługi i Compute Engine

ee.Initialize() użyje danych logowania Earth Engine (które ee.Authenticate() przechowuje w ~/.config/earthengine/credentials) lub pobierze dane logowania z google.auth.default(). W razie potrzeby możesz przekazać argument credentials=, aby użyć danych logowania z innego źródła, pomijając te domyślne.

Jeśli uwierzytelniasz kod Pythona, który będzie działać bez nadzoru, możesz to zrobić za pomocą konta usługi, a nie konta użytkownika. Więcej informacji o używaniu kont usługi w Earth Engine znajdziesz w tych dokumentach. Inne metody to authenticate_service_account w module uwierzytelniania Colab oraz metody opisane w przewodniku Cloud na temat uwierzytelniania za pomocą konta usługi.

Jeśli kod jest uruchamiany w maszynie wirtualnej Compute Engine, dla środowiska zostanie utworzone domyślne konto usługi, którego ee.Initialize() będzie używać domyślnie. Jeśli projekt Cloud, za pomocą którego uruchomiono maszynę wirtualną, nie jest zarejestrowany do korzystania z Earth Engine (w celach komercyjnych lub niekomercyjnych), konieczne może być zarejestrowanie konta usługi, aby móc korzystać z Earth Engine.

Szczegóły dotyczące trybów

auth_mode=colab. ee.Authenticate() utworzy lub uzyska domyślne poświadczenia obsługiwane przez Colab, uruchamiając w razie potrzeby colab.auth.authenticate_user(). Dane logowania zawsze używają zakresu cloud-platform i można ich używać do wywoływania innych interfejsów Cloud API.

auth_mode=gcloud. To deleguje uwierzytelnianie do narzędzia gcloud i jest to to samo, co wykonanie polecenia gcloud auth application-default login z domyślnymi zakresami Earth Engine (earthengine, cloud-platform i drive) lub zakresami w argumencie scopes. Tryb gcloud działa zarówno w przypadku lokalnych, jak i zdalnych przypadków.

Szczegółowe instrukcje dotyczące trybu gcloud (przypadki lokalne i zdalne)

  1. Sprawdź, czy na komputerze lokalnym jest zainstalowany gcloud.
    • W terminalu uruchom gcloud help. Jeśli gcloud nie jest zainstalowany, wykonaj te instrukcje, aby zainstalować gcloud.
  2. Terminal lokalnego komputera
    • W terminalu uruchom earthengine authenticate.
    • Dane wyjściowe polecenia wskazują, że do pobierania danych logowania używane jest narzędzie gcloud.
    • Otworzy się okno przeglądarki z stroną wyboru konta. Jeśli przeglądarka nie otworzy się automatycznie, kliknij adres URL.
  3. Przeglądarka: wybór konta
    • Wybierz konto, którego chcesz używać do uwierzytelniania.
  4. Przeglądarka: ekran zgody
    • Potwierdź, że chcesz przyznać wymagane uprawnienia, i kliknij „Zezwól”.
  5. Przeglądarka: ekran potwierdzenia
    • Przeglądarka wyświetli stronę z potwierdzeniem uwierzytelnienia, a polecenie earthengine authenticate w oknie terminala wyświetli komunikat „Token autoryzacji został zapisany”.
    • W rzadkich przypadkach strona internetowa może zawierać kod, który należy wkleić z powrotem do środowiska Pythona.
  6. Przejdź do inicjalizacji.

auth_mode=localhost. Jest to proces podobny do gcloud w przypadku, gdy gcloud nie jest zainstalowany. Wykonuje te same czynności co gcloud, ale działa tylko w przypadku lokalnego przypadku użycia. Możesz podać opcjonalny numer portu internetowego, np. localhost:8086, lub użyć wartości localhost:0, aby automatycznie wybrać port. Domyślny port to 8085.

auth_mode=notebook. Jest to tryb ogólny, który działa w odległych sytuacjach, gdy nie można użyć lokalnych wierszy poleceń. Spowoduje to przejście na stronę usługi Notebook Authenticator, na której musisz wybrać lub utworzyć „projekt uwierzytelniania” (szczegóły i przewodnik dotyczący rozwiązywania problemów znajdziesz poniżej). Projekt przekazany do ee.Initialize() nie musi być identyczny – możesz używać tego samego projektu do uwierzytelniania podczas pracy nad różnymi projektami w różnych notatnikach. Zalecamy przekazywanie projektu bezpośrednio do funkcji ee.Initialize(), ale domyślnie będzie używany projekt uwierzytelniania.

Szczegółowe instrukcje dotyczące trybu notebooka

  1. Przeglądarka: Notatnik
    1. W komórce kodu notatnika uruchom ten kod, aby rozpocząć proces uwierzytelniania w trybie „notebook”. 
      import ee
ee.Authenticate()
      Kliknij link w wyniku w komórce, aby otworzyć stronę uwierzytelniania w Notebooku na nowej karcie.
  2. Przeglądarka: mechanizm uwierzytelniania w notatniku
    1. Sprawdź, czy wyświetla się właściwe konto użytkownika.
    2. Wybierz projekt Google Cloud, którego chcesz używać do uwierzytelniania. Jeśli chcesz utworzyć nowy projekt, zalecamy użycie konwencji nazewnictwa „ee-xyz”, gdzie xyz to Twoja zwykła nazwa użytkownika w Earth Engine. (jeśli nie możesz wybrać ani utworzyć projektu Cloud, zapoznaj się z sekcją rozwiązywania problemów poniżej).
    3. Kliknij Wygeneruj token.
  3. Przeglądarka: wybór konta
    • Pojawi się strona wyboru konta. Kliknij konto użytkownika, któremu chcesz przyznać dostęp z notatnika.
  4. Przeglądarka: strona z ostrzeżeniem
    • Wyświetla się strona z ostrzeżeniem, że Google nie jest autorem aplikacji (czyli kodu w notatniku). Aby potwierdzić, kliknij Dalej.
  5. Przeglądarka: ekran zgody
    • Potwierdź, że chcesz przyznać żądane uprawnienia, i kliknij Dalej.
  6. Przeglądarka: ekran kodu autoryzacji
    • Kopiowanie kodu weryfikacji autoryzacji
  7. Przeglądarka: Notatnik
    • Wróć do karty notebooka i wklej kod weryfikacyjny w wyjściu komórki notebooka.
    • Wyjście komórki powinno wskazywać: "Udało się zapisać token autoryzacji".
  8. Przejdź do inicjalizacji.

Tryb notebooka ma rzadko używany parametr quiet: jeśli jest ustawiony, działa „nieinteraktywnie” i nie wyświetla promptu ani nie czeka na podanie kodu autoryzacyjnego. Zamiast tego zawiera polecenie, które należy wykonać, aby zapisać kod.

Projekty uwierzytelniania

Musisz mieć uprawnienia właściciela, edytującego lub edytującego konfigurację OAuth w projekcie uwierzytelniania używanym w trybie notebooka. W wielu przypadkach, zwłaszcza w mniejszych zespołach, projekt uwierzytelniania używany na stronie Notebook Authenticator może być taki sam jak projekt główny używany do innych zadań.

Ze względu na zastrzeżenia dotyczące bezpieczeństwa „konfiguracja klienta OAuth” w projekcie uwierzytelniania jest konfiguracją jednorazową. Jeśli Ty lub inni użytkownicy skonfigurowaliście klienta OAuth w projekcie z innych powodów, nie można go usunąć. W tym przypadku pojawi się komunikat o błędzie „Niezgodna konfiguracja klienta OAuth2”. Do uwierzytelniania musisz użyć innego projektu lub użyć trybów colab, localhost lub gcloud.

Rozwiązywanie problemów

Co zrobić, jeśli nie mogę utworzyć projektu Cloud?

Niektóre organizacje kontrolują, kto może tworzyć projekty Cloud. Jeśli podczas próby utworzenia projektu na stronie usługi Notebook Authenticator pojawi się błąd, możesz spróbować wykonać kilka czynności:

  1. Spróbuj utworzyć projekt bezpośrednio, aby sprawdzić, czy masz niezbędne uprawnienia.
  2. Aby dowiedzieć się, jakie procesy są dostępne do tworzenia projektów, skontaktuj się z administratorem organizacji.
  3. Utwórz projekt z konta nienależącego do organizacji i dodaj do niego konto, którego używasz w celach służbowych, jako właściciela projektu. Uwaga: niektóre organizacje mają zasady zabezpieczeń, które uniemożliwiają dostęp do klientów OAuth z projektów zewnętrznych.

Błąd: „Interfejs Earth Engine API nie był wcześniej używany w projekcie XXX lub jest wyłączony”

Najpierw upewnij się, że masz skonfigurowany projekt w ee.Initialize() lub na linii poleceń (domyślne projekty udostępniane przez Cloud i Colab nie mają włączonego Earth Engine). Po drugie, upewnij się, że interfejs Earth Engine API jest włączony w projekcie.

Błąd: „Projekt ma niezgodną konfigurację klienta OAuth2”

Projekty w Cloud mogą mieć tylko jedną konfigurację klienta OAuth2. Aby sprawdzić, czy projekt w usłudze Cloud ma skonfigurowaną konfigurację klienta OAuth 2, sprawdź identyfikatory klienta OAuth 2 na stronie Dane logowania. Musisz wybrać inny projekt Cloud, który ma już skonfigurowaną zgodną konfigurację przez Notebook Authenticator, lub wybrać lub utworzyć projekt Cloud bez klientów OAuth2. Autentyfikatora skonfiguruje ten projekt automatycznie. Niestety system OAuth nie pozwala użytkownikom na usuwanie konfiguracji, więc trzeba użyć innego projektu. Nie musi to być ten sam projekt, który jest używany do innych zadań w Earth Engine. Pamiętaj, że ten błąd nie występuje w trybie Colab.

Błąd: „Nie udało się połączyć z gcloud. Sprawdź, czy nie występują błędy opisane powyżej, i w razie potrzeby zainstaluj gcloud”.

Ten błąd może wystąpić, jeśli gcloud nie jest zainstalowany lub nie znajduje się na ścieżce PATH. Może się to też zdarzyć, jeśli wywołasz funkcję ee.Authenticate(auth_mode='gcloud') w komórce kodu w notatniku. Zamiast tego użyj opcji ee.Authenticate(), która domyślnie używa uwierzytelniania w trybie notebooka. Jeśli nie możesz utworzyć projektu, zapoznaj się z powyższym rozwiązaniem.

Co zrobić, jeśli nie mam dostępu do komputera lokalnego, na którym można zainstalować gcloud?

Jeśli pracujesz w środowisku tylko z dostępem do internetu bez dostępu do terminala lokalnego, a nadal musisz używać terminala zdalnego, możesz zainicjować narzędzie wiersza poleceń, uruchamiając tryb notebooka, wykonując polecenie earthengine authenticate --auth_mode=notebook.

Błąd 400: redirect_uri_mismatch

Ten błąd może wystąpić, jeśli uwierzytelniasz się na komputerze zdalnym bez dostępu do przeglądarki. Spróbuj dodać --quiet, jeśli używasz polecenia earthengine authenticate w wierszu poleceń, lub ee.Authenticate(quiet=True), jeśli używasz klienta Python. W tym celu musisz się zalogować za pomocą gcloud na komputerze, na którym masz dostęp do przeglądarki internetowej.

Błąd: „Twoja aplikacja uwierzytelnia się przy użyciu lokalnych domyślnych danych logowania aplikacji. Interfejs API earthengine.googleapis.com wymaga projektu z limitem, który nie jest ustawiony domyślnie.

Ten błąd może wystąpić, gdy Earth Engine nie może określić identyfikatora projektu. Jeśli opcje rozwiązywania problemów Google Cloud nie działają, uruchom earthengine set_project YOUR_PROJECT_ID lub gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Uwagi techniczne

Dla osób zainteresowanych kwestiami technicznymi: potrzeba stosowania różnych mechanizmów tworzenia danych logowania wynika z konieczności przekazania danych logowania do znanego i zaufanego środowiska. Poniżej krótko omawiamy różne przypadki.

  • Wcześniej istniał tryb paste, który umożliwiał wklejanie tokena w dowolnym miejscu. Uznaliśmy, że jest to zbyt ryzykowne, i wyłączyliśmy tę funkcję.
  • colab: auth.authenticate_user() wyświetli prośbę o udostępnienie danych logowania klientowi uwierzytelniającemu „Colab”, czyli samemu środowisku notebooka. Są one dostępne w ramach usługi google.auth.default() i są używane przez ee.Initialize().
  • localhost: poświadczenia są przekazywane z przeglądarki do portu na Twoim komputerze lokalnym. W takim przypadku bezpieczeństwo end-to-end zależy od tego, czy Twój lokalny komputer nie został naruszony. Klientem autoryzacji, który zobaczysz, jest „Earth Engine Authenticator”.
  • gcloud: ta opcja korzysta z procesu --launch-browser opisanego w dokumentacji gcloud, a w przypadku maszyny zdalnej z procesu --no-launch-browser. Używany klient uwierzytelniania to „Google Auth Library”.
  • notebook: utworzymy nowego klienta uwierzytelniania specjalnie dla Twojej firmy – zobaczysz swój adres e-mail na stronie zgody. Ten klient jest ustawiony w trybie „development”, który jest trybem specjalnym umożliwiającym używanie starszych tokenów wklejania. Musimy użyć Twojego projektu, ponieważ takich klientów nie można udostępniać dużej liczbie użytkowników.