В Earth Engine введены некоммерческие квотные уровни для защиты совместно используемых вычислительных ресурсов и обеспечения надежной работы для всех. Некоммерческие проекты по умолчанию используют уровень «Сообщество», хотя вы можете изменить уровень проекта в любое время.

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

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

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

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

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

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

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

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

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

На этапе инициализации проверяется наличие действительных учетных данных, созданных с помощью ee.Authenticate() или существующих в качестве учетных данных Google по умолчанию. Затем он инициализирует клиентскую библиотеку Python с помощью методов, которые поддерживает бэкенд-сервер. Вам нужно будет указать проект, владельцем которого вы являетесь или на использование которого у вас есть разрешение. Чтобы зарегистрировать проект и включить Earth Engine API, ознакомьтесь с инструкциями по настройке облачного проекта. Этот проект будет использоваться для выполнения всех операций 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).
  - или попросите администратора предоставить вам разрешение на создание проекта.

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

	Для локального или удаленного?	Требуется проект	Области действия, которые можно задать	Требуется локальный CLI	Владелец проекта
`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 и методы, описанные в руководстве по аутентификации в качестве сервисного аккаунта.

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

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

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

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

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

Убедитесь, что на локальном компьютере установлен инструмент gcloud.
- В терминале выполните команду gcloud help. Если gcloud не установлен, следуйте этим инструкциям .
Терминал локального компьютера
- В терминале выполните команду earthengine authenticate.
- В результате выполнения команды будет указано, что для получения учетных данных используется gcloud.
- В браузере откроется страница выбора аккаунта. Если браузер не открывается автоматически, нажмите на URL.
Браузер: выбор аккаунта
- Выберите аккаунт, который хотите использовать для аутентификации.
Браузер: окно запроса доступа
- Укажите, готовы ли вы предоставить запрашиваемые области действия, и нажмите "Разрешить".
Браузер: экран подтверждения
- В браузере появится страница с подтверждением аутентификации, а в окне терминала команда earthengine authenticate сообщит, что токен авторизации успешно сохранен.
- В редких случаях на веб-странице будет указан код, который нужно вставить обратно в среду Python.
Выполните инициализацию.

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

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

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

Браузер: Notebook
1. В ячейке кода блокнота выполните следующий код, чтобы запустить процесс аутентификации в режиме notebook.
```
import ee
ee.Authenticate()
```
  Нажмите на ссылку в выходных данных ячейки, чтобы открыть страницу Notebook Authenticator в новой вкладке.
Браузер: Notebook Authenticator
1. Убедитесь, что указан правильный аккаунт пользователя.
2. Выберите проект Google Cloud, который будет использоваться для аутентификации. Если вам нужно создать новый проект, рекомендуем использовать соглашение об именовании "ee-xyz", где xyz – ваше обычное имя пользователя Earth Engine. Если вы не можете выбрать или создать облачный проект, ознакомьтесь с инструкциями по устранению неполадок ниже.
3. Нажмите "Создать токен".
Браузер: выбор аккаунта
- Откроется страница выбора аккаунта. Выберите аккаунт пользователя, которому хотите предоставить доступ к блокноту.
Браузер: страница с предупреждением
- Появится предупреждение о том, что приложение (код в блокноте) создано не Google. Нажмите "Продолжить".
Браузер: окно запроса доступа
- Укажите, готовы ли вы предоставить запрашиваемые области действия, и нажмите Продолжить.
Браузер: экран с кодом авторизации
- Скопируйте код подтверждения авторизации.
Браузер: Notebook
- Вернитесь на вкладку блокнота и вставьте код подтверждения в выходные данные ячейки блокнота.
- В выходных данных ячейки должно быть указано Successfully saved authorization token (Токен авторизации успешно сохранен).
Выполните инициализацию.

В режиме Notebook есть редко используемый параметр quiet. Если он задан, то запуск происходит в неинтерактивном режиме, то есть без запроса кода авторизации. Вместо этого он дает команду, которую нужно выполнить, чтобы сохранить код.

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

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

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

Подробные сведения об областях действия

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

Области действия Earth Engine. Область действия OAuth 2.0 определяет и ограничивает набор ресурсов и операций, к которым приложению разрешено получать доступ от имени пользователя. При использовании OAuth для аутентификации в Earth Engine необходимо запросить одну или несколько из следующих областей действия:

https://www.googleapis.com/auth/earthengine – доступ на чтение и запись к объектам и ресурсам Earth Engine. Требуется для создания, изменения и удаления объектов, управления разрешениями на доступ к объектам и выполнения задач экспорта.
https://www.googleapis.com/auth/earthengine.readonly: доступ только для чтения к объектам Earth Engine.

Обе области позволяют выполнять скрипты и вычисления (например, оценивать выражения или визуализировать карты).

Области действия Google Cloud и Диска. Если ваши запросы или скрипты Earth Engine ссылаются на внешние данные или объекты, ваши учетные данные также должны включать соответствующие области действия для этих сервисов:

Cloud Storage (GCS) (при чтении из сегментов Cloud Storage или записи в них, например при загрузке Cloud Optimized GeoTIFF (COG) или экспорте результатов задач):
- https://www.googleapis.com/auth/devstorage.full_control
- https://www.googleapis.com/auth/devstorage.read_write
- https://www.googleapis.com/auth/devstorage.read_only
BigQuery (BQ) (при чтении таблиц или записи экспортированных данных в BigQuery):
- https://www.googleapis.com/auth/bigquery
Google Диск (при доступе к данным на Google Диске или их экспорте):
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/drive.readonly

Google Cloud также предлагает широкие области действия, которые охватывают все сервисы Google Cloud:

Cloud Platform (широкий доступ к сервисам Google Cloud, включая Earth Engine, Cloud Storage и BigQuery; обратите внимание, что Google Диск – это отдельный сервис Workspace, на который эти области действия не распространяются):
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud-platform.read-only

Области действия по умолчанию. Области действия по умолчанию, настроенные как редактором кода Earth Engine, так и клиентскими библиотеками (например, ee.Authenticate()), включают все следующие области действия: earthengine, cloud-platform и drive (подробности см. выше). Следовательно, настраивать область действия (например, с помощью параметра scopes в ee.Authenticate(scopes=[...])) нужно, только если у вас есть особые ограничения безопасности или организационные правила, требующие ограничения разрешений.

Устранение неполадок

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

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

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

Ошибка "Earth Engine API has not been used in project XXX before or it is disabled" (Earth Engine API не использовался в проекте XXX или отключен)

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

Ошибка "В проекте используется несовместимая конфигурация клиента OAuth2"

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

Ошибка: "gcloud failed. Проверьте, нет ли ошибок выше, и при необходимости установите 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 на компьютере, на котором есть доступ к браузеру.

Ошибка: "Your application is authenticating by using local Application Default Credentials. Для earthengine.googleapis.com API требуется проект квоты, который не задан по умолчанию".

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

Ошибка "Отсутствуют необходимые области действия для [Cloud Storage/BigQuery]"

Эта ошибка возникает, когда запрос Earth Engine обращается к ресурсам Cloud Storage или BigQuery, но учетные данные, используемые для инициализации Earth Engine, не включают необходимые области действия для этого сервиса (или область действия cloud-platform, которая охватывает все сервисы Google Cloud). Обычно это происходит, если вы настроили параметр scopes во время аутентификации (например, предоставили ee.Authenticate(scopes=[...]) только области Earth Engine) или если существующие учетные данные были созданы без этих областей.

Решить эту проблему можно двумя способами:

Повторно пройдите аутентификацию с областями действия по умолчанию. Учетные данные по умолчанию для Earth Engine включают область действия cloud-platform, которая охватывает Cloud Storage и BigQuery. Повторно пройдите аутентификацию, используя настройки по умолчанию:
- В Python: ee.Authenticate(force=True)
- В командной строке: earthengine authenticate --force
Укажите необходимые области действия. Если в вашей среде требуется настроить области действия, убедитесь, что список scopes включает https://www.googleapis.com/auth/cloud-platform или область действия определенного сервиса (например, https://www.googleapis.com/auth/devstorage.full_control или https://www.googleapis.com/auth/devstorage.read_only для Cloud Storage или https://www.googleapis.com/auth/bigquery для BigQuery).

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

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

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

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