Аутентификация и инициализация

Прежде чем вы сможете отправлять запросы к Earth Engine через клиентскую библиотеку , вы должны пройти аутентификацию и использовать полученные учетные данные для инициализации клиента Earth Engine.

Редактор кода Earth Engine и JavaScript

Аутентификация и инициализация выполняются автоматически в редакторе кода. Вы можете выбрать маршрутизацию запросов через облачный проект, войдя в систему в правом верхнем углу редактора кода .

Если вы используете API JavaScript (вне редактора кода), используйте один из помощников аутентификации в ee.data (например, ee.data.authenticateViaPopup() ), а затем ee.initialize() как показано в этом примере .

Python и командная строка

Прежде чем использовать клиентскую библиотеку Python Earth Engine, вам необходимо пройти аутентификацию (подтвердить свою личность) и использовать полученные учетные данные для инициализации клиента Python. Потоки аутентификации используют облачные проекты для аутентификации и используются как для бесплатного (бесплатного, некоммерческого), так и для платного использования. Для аутентификации и инициализации запустите

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

Сначала будет выбран лучший режим аутентификации для вашей среды, и вам будет предложено подтвердить доступ для ваших сценариев. Если учетные данные уже существуют, они автоматически используются повторно — запустите ee.Authenticate(force=True) чтобы создать новые учетные данные.

На этапе инициализации проверяется наличие действительных учетных данных, либо созданных с помощью ee.Authenticate() либо ранее существовавших в качестве учетных данных Google по умолчанию. Затем он инициализирует клиентскую библиотеку Python методами, которые поддерживает внутренний сервер. Вам нужно будет предоставить проект , которым вы владеете или имеете разрешения на его использование. См . раздел «Настройка облачного проекта» , чтобы зарегистрировать проект и включить API Earth Engine. Этот проект будет использоваться для выполнения всех операций Earth Engine.

В командной строке эквивалентным вызовом является earthengine authenticate . Если срок действия учетных данных истек или они недействительны, вам может потребоваться запустить earthengine authenticate --force . Вызовы командной строки будут инициализироваться при каждом вызове, и вы можете использовать аргумент --project для установки проекта.

Вы также можете настроить проект для всех будущих вызовов, запустив earthengine set_project {my-project} . Командная строка и ee.Initialize() будут использовать это всякий раз, когда проект не указан напрямую. При использовании аутентификации через gcloud (см. ниже) в качестве последнего случая будет использоваться проект, заданный gcloud auth application-default set-quota-project {my-project} .

Детали аутентификации

Целью потоков аутентификации Earth Engine является получение «токена» безопасности из вашей вошедшей в систему учетной записи, который можно сохранить, чтобы дать вашим сценариям разрешение на доступ к вашим данным. По соображениям безопасности система аутентификации Google будет передавать такие токены только тем системам, которые можно обеспечить безопасность — см. технические примечания ниже.

Из-за чувствительности к типу задействованных систем существуют разные способы действий в зависимости от вашей конкретной ситуации. Большинство опций управляются параметром auth_mode : либо как ee.Authenticate(auth_mode=...) , либо earthengine authenticate --auth_mode=... в командной строке.

Обратите внимание: если учетные данные Google уже существуют в вашей среде, возможно, вам вообще не понадобится вызывать ee.Authenticate() . Виртуальные машины Google Cloud, App Engine и другие среды предоставляют полезные «окружающие учетные данные», и gcloud auth application-default login также создает их.

Однако для максимальной совместимости рекомендуется использовать ee.Authenticate() в начале всех скриптов. Без параметра auth_mode он предназначен для работы в большинстве ситуаций, но следуйте инструкциям ниже, если режим по умолчанию не работает. Режим по умолчанию выбирается следующим образом:

  • colab , если работает в блокноте Google Colab
  • notebook если он работает на других блокнотах Jupyter, отличных от Colab
  • localhost , если обнаружен веб-браузер и не установлен двоичный файл gcloud
  • gcloud , иначе. Для этого режима вам потребуется установить gcloud .

Краткое справочное руководство и таблица

В этом руководстве по принятию решений описаны возможные варианты действий, если режим по умолчанию, выбранный с помощью ee.Authenticate() не работает. Например, если вы работаете в других средах ноутбуков, возможно, вам придется явно указать notebook .

  • Местная среда .
    • «Локальный» означает, что вы запускаете код в оболочке Python или в блокноте Python на компьютере перед вами — или, точнее, на том же компьютере, на котором работает ваш веб-браузер. Сюда входят ситуации с удаленным рабочим столом, когда Python и браузер находятся на одном (удаленном) компьютере.
    • Использование auth_mode=localhost проще всего и будет выбрано по умолчанию, если gcloud не установлен, но ваш скрипт будет работать только в локальных средах.
    • Также доступны как auth_mode=gcloud , так и auth_mode=notebook .
  • Удаленная среда .
    • «Удаленный» означает, что ваш браузер находится на одном (локальном) компьютере, но ваш код выполняется в другом месте, например, на удаленной рабочей станции или ноутбуке с доступом в Интернет.
    • Если вы используете Colab, используйте auth_mode=colab ; или используйте gcloud , если вам нужно установить scopes для вызова других API.
    • Если вы можете установить gcloud как на удаленном, так и на локальном компьютере, используйте auth_mode=gcloud .
    • Если вы можете использовать проект аутентификации (см. ниже), используйте auth_mode=notebook .
    • В противном случае, если вы не можете использовать проект, установить gcloud, использовать Colab или браузер на одном компьютере:
    • Поговорите с администратором (еще раз) о создании проектов. Например:
      • Попросите администратора настроить проект для вас (в качестве владельца, редактора или редактора конфигурации OAuth).
      • Или попросите администратора предоставить вам разрешения на создание проекта.

В этой таблице показано, какие комбинации функций поддерживаются каждым режимом.

Для локального или удаленного? Нужен проект Настраиваемые области Требуется локальный интерфейс командной строки Владелец проекта
localhost местный Да Да Н Н
colab удаленный Да Н Н Н
gcloud оба Да Да Н Н
notebook оба Да Да Н Да

Учетные данные для сервисных учетных записей и Compute Engine

ee.Initialize() будет использовать учетные данные Earth Engine (которые ee.Authenticate() хранит в ~/.config/earthengine/credentials ) или получать учетные данные из google.auth.default() , но при необходимости вы можете передать аргумент credentials= , чтобы использовать учетные данные из другого места, минуя эти значения по умолчанию.

Если вы проверяете подлинность кода Python, который будет выполняться автоматически, вам может потребоваться выполнить аутентификацию с использованием учетной записи службы, а не учетной записи пользователя. Ознакомьтесь с этой документацией, чтобы узнать об использовании сервисных учетных записей с Earth Engine. Другие методы включают в себя authenticate_service_account в модуле аутентификации Colab и методы, описанные в руководстве Cloud по аутентификации в качестве учетной записи службы .

Если ваш код выполняется на виртуальной машине Compute Engine , для среды создается учетная запись службы по умолчанию , которую ee.Initialize() будет использовать по умолчанию. Вам может потребоваться зарегистрировать учетную запись службы для использования Earth Engine, если облачный проект, с помощью которого была запущена виртуальная машина, не зарегистрирован для использования с Earth Engine (коммерческим или некоммерческим).

Подробности о режимах

auth_mode=colab . ee.Authenticate() создаст или получит учетные данные по умолчанию, поддерживаемые Colab, запустив colab.auth.authenticate_user() при необходимости. Учетные данные всегда используют область cloud-platform , а также могут использоваться для вызова других облачных API.

auth_mode=gcloud . Это делегирует аутентификацию инструменту gcloud и аналогично запуску gcloud auth application-default login с областями действия Earth Engine по умолчанию (earthengine, облачная платформа и диск) или областями в аргументе scopes . Режим gcloud работает как в локальном, так и в удаленном случае.

Пошаговые инструкции для режима gcloud (локальный и удаленный случаи)

  1. Убедитесь, что gcloud установлен на локальном компьютере.
    • В терминале запустите gcloud help . Если gcloud не установлен, следуйте этим инструкциям , чтобы установить gcloud .
  2. Локальный машинный терминал
    • В терминале запустите earthengine authenticate .
    • Вывод команды будет указывать, что gcloud используется для получения учетных данных.
    • В окне браузера откроется страница выбора учетной записи. Если браузер не открывается автоматически, щелкните URL-адрес.
  3. Браузер: выбор учетной записи
    • Выберите учетную запись, которую вы хотите использовать для аутентификации.
  4. Браузер: экран согласия
    • Укажите, готовы ли вы предоставить запрошенные области, и нажмите «Разрешить».
  5. Браузер: экран подтверждения
    • Браузер отобразит страницу, подтверждающую вашу аутентификацию, а команда earthengine authenticate в окне вашего терминала сообщит «Токен авторизации успешно сохранен».
    • В удаленных случаях веб-страница предоставит вам код для вставки обратно в среду Python.
  6. Продолжите инициализацию.

auth_mode=localhost . Это процедура, похожая на gcloud, для случаев, когда gcloud не установлен. Он выполняет те же действия, что и gcloud, но работает только в локальном случае. Вы можете указать дополнительный номер интернет-порта, например localhost:8086 , или использовать localhost:0 для автоматического выбора порта. Порт по умолчанию — 8085.

auth_mode=ноутбук . Это режим общего назначения, предназначенный для работы в удаленных ситуациях, когда локальные командные строки недоступны. Вы перейдете на страницу Notebook Authenticator, где вам нужно будет выбрать или создать «проект аутентификации» — подробности и руководство по устранению неполадок см. ниже. Проект, переданный в ee.Initialize() не обязательно должен соответствовать этому — вы можете сохранить один и тот же проект для аутентификации, работая в разных проектах в разных записных книжках. Рекомендуется явно передать проект в ee.Initialize() , но по умолчанию будет использоваться проект аутентификации.

Пошаговые инструкции для режима блокнота

  1. Браузер: Ноутбук
    1. В ячейке кода записной книжки выполните следующий код, чтобы запустить поток проверки подлинности в режиме «записной книжки».
      import ee
ee.Authenticate()
       Щелкните ссылку в выходных данных ячейки, чтобы открыть страницу Notebook Authenticator на новой вкладке.
  2. Браузер: Аутентификатор ноутбука
    1. Убедитесь, что указана правильная учетная запись пользователя.
    2. Выберите проект Google Cloud, который будет использоваться для аутентификации. Если вам нужно создать новый проект, мы рекомендуем соглашение об именовании «ee-xyz», где xyz — ваше обычное имя пользователя Earth Engine. (Если вы не можете выбрать или создать облачный проект, см. раздел «Устранение неполадок» ниже.)
    3. Нажмите «Создать токен».
  3. Браузер: выбор учетной записи
    • Вам будет показана страница выбора аккаунта. Щелкните учетную запись пользователя, которой вы хотите предоставить доступ из записной книжки.
  4. Браузер: страница предупреждения
    • Появится страница с предупреждением, указывающая, что Google не создавал приложение (т. е. код в блокноте). Нажмите «Продолжить», чтобы подтвердить.
  5. Браузер: экран согласия
    • Укажите, готовы ли вы предоставить запрошенные области, и нажмите «Продолжить» .
  6. Браузер: экран кода авторизации
    • Скопируйте код подтверждения авторизации
  7. Браузер: Ноутбук
    • Вернитесь на вкладку блокнота и вставьте код подтверждения в выходные данные ячейки блокнота.
    • В выводе ячейки должно быть указано «Токен авторизации успешно сохранен».
  8. Продолжите инициализацию.

Режим ноутбука имеет редко используемый quiet параметр: если он установлен, он работает «неинтерактивно», не запрашивая и не ожидая ввода кода авторизации. Вместо этого он дает команду для сохранения кода.

Проекты аутентификации

Вам нужно будет быть владельцем, редактором или редактором конфигурации OAuth в проекте аутентификации, используемом в режиме блокнота. Во многих случаях, особенно в небольших группах, проект аутентификации, который вы используете на странице Notebook Authenticator, может быть таким же, как основной проект, который вы используете для другой работы.

Из соображений безопасности «Конфигурация клиента OAuth» в проекте аутентификации является однократной настройкой. Если вы или другие пользователи настроили клиент OAuth в проекте по другим причинам, его невозможно удалить, и вы увидите сообщение об ошибке «несовместимая конфигурация клиента OAuth2». Вам нужно будет использовать другой проект для аутентификации или использовать режимы colab, localhost или gcloud, описанные выше.

Поиск неисправностей

Что делать, если я не могу создать облачный проект?

Некоторые организации контролируют, кто может создавать облачные проекты. Если вы получаете сообщение об ошибке на странице Notebook Authenticator при попытке создать проект, попробуйте выполнить несколько действий:

  1. Попробуйте создать проект напрямую, чтобы убедиться, есть ли у вас необходимые разрешения.
  2. Обратитесь к администратору вашей организации, чтобы узнать, какие процессы доступны для создания проекта.
  3. Создайте проект из учетной записи, не принадлежащей организации, и добавьте учетную запись, которую вы используете для работы в качестве владельца проекта. Примечание. В некоторых организациях действуют политики безопасности, которые запрещают доступ к клиентам OAuth из внешних проектов.

Ошибка: «API Earth Engine ранее не использовался в проекте XXX или отключен»

Во-первых, убедитесь, что вы настроили проект в ee.Initialize() или в командной строке (в проектах по умолчанию, предоставляемых Cloud и Colab, Earth Engine не будет включен). Во-вторых, убедитесь, что API Earth Engine включен в вашем проекте.

Ошибка: «Проект имеет несовместимую конфигурацию клиента OAuth2»

Облачные проекты могут иметь только одну конфигурацию клиента OAuth2. Вы можете проверить, установлена ​​ли в облачном проекте конфигурация клиента OAuth2, проверив идентификаторы клиентов OAuth 2.0 на странице «Учетные данные». Вам необходимо либо выбрать другой облачный проект, совместимая конфигурация которого уже настроена в Notebook Authenticator, либо выбрать или создать облачный проект без клиентов OAuth2. Аутентификатор автоматически настроит этот проект. К сожалению, система OAuth не позволяет пользователям удалять конфигурации, поэтому необходимо использовать другой проект. Этот проект не обязательно должен быть тем же проектом, который используется для других работ Earth Engine. Обратите внимание, что эта ошибка не возникает в режиме Colab.

Ошибка: «Ошибка gcloud. Проверьте наличие указанных выше ошибок и при необходимости установите gcloud».

Эта ошибка может возникнуть, если gcloud не установлен или не находится в вашей PATH. Это также может произойти, если вы вызываете ee.Authenticate(auth_mode='gcloud') из ячейки кода записной книжки. Вместо этого используйте ee.Authenticate() , который по умолчанию использует аутентификацию в режиме ноутбука. Если вы не можете создать проект, см. решение выше.

Что делать, если у меня нет доступа к локальному компьютеру для установки gcloud?

Если вы работаете только в веб-среде без доступа к локальному терминалу и вам по-прежнему необходимо использовать удаленный терминал, вы все равно можете инициализировать инструмент командной строки, включив режим ноутбука, выполнив команду earthengine authenticate --auth_mode=notebook .

Ошибка 400: redirect_uri_mismatch

Вы можете получить эту ошибку при аутентификации на удаленном компьютере без доступа к веб-браузеру. Попробуйте добавить --quiet , если вы запускаете earthengine authenticate из командной строки, или ee.Authenticate(quiet=True) если используете клиент Python. Для этого вам потребуется пройти аутентификацию в gcloud на компьютере, имеющем доступ к веб-браузеру.

Ошибка: «Ваше приложение проходит аутентификацию с использованием локальных учетных данных приложения по умолчанию. Для API Earthengine.googleapis.com требуется проект квоты, который не установлен по умолчанию».

Эта ошибка может возникнуть, если Earth Engine не может определить идентификатор вашего проекта. Если варианты устранения неполадок Google Cloud не работают, попробуйте запустить earthengine set_project YOUR_PROJECT_ID или gcloud auth application-default set-quota-project YOUR_PROJECT_ID .

Технические примечания

Для тех, кто интересуется техническими вопросами: необходимость в этих различных механизмах создания учетных данных обусловлена ​​необходимостью передавать учетные данные в известную и надежную среду. Вот краткое обсуждение различных случаев, описанных выше.

  • Раньше существовал режим paste , который давал вам токен для вставки куда угодно, но это было сочтено слишком рискованным и больше недоступно.
  • colab : auth.authenticate_user() предложит вам поделиться учетными данными с клиентом аутентификации «Colab», самой средой ноутбука. Затем они доступны через google.auth.default() и используются ee.Initialize() .
  • localhost : учетные данные передаются из браузера в порт на вашем локальном компьютере. В этой ситуации сквозная безопасность зависит от того, что ваша локальная машина не была скомпрометирована. Клиент аутентификации, который вы увидите, — это «Earth Engine Authenticator».
  • gcloud : используется поток --launch-browser описанный в справочнике по gcloud , и --no-launch-browser если на удаленном компьютере. Используемый клиент аутентификации — «Библиотека аутентификации Google».
  • notebook : мы создаем новый клиент авторизации специально для вашей работы — вы увидите свой адрес электронной почты на странице согласия. Этот клиент установлен в режиме «разработки», что является особым случаем, позволяющим использовать старые токены режима вставки. Для этого нам необходимо использовать собственный проект, поскольку такие клиенты не могут быть доступны большому количеству пользователей.