Autenticación e inicialización

Antes de realizar solicitudes a Earth Engine a través de una biblioteca cliente, debes autenticar y usar las credenciales resultantes para inicializar el cliente de Earth Engine.

Editor de código de Earth Engine y JavaScript

La autenticación y la inicialización se controlan automáticamente en el editor de código. Puedes enrutar las solicitudes a través de un proyecto de Cloud desde tu acceso en la parte superior derecha del Editor de código.

Si usas la API de JavaScript (fuera del editor de código), usa uno de los ayudas de autenticación en ee.data (por ejemplo, ee.data.authenticateViaPopup()) seguido de ee.initialize(), como se muestra en este ejemplo.

Python y línea de comandos

Antes de usar la biblioteca cliente de Python de Earth Engine, debes autenticarte (verificar tu identidad) y usar las credenciales resultantes para inicializar el cliente de Python. Los flujos de autenticación usan proyectos de Cloud para autenticarse y se usan para uso no remunerado (gratuito y no comercial), así como para uso pagado. Para autenticar e inicializar, ejecuta

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

Primero, se seleccionará el mejor modo de autenticación para tu entorno y se te solicitará que confirmes el acceso de tus secuencias de comandos. Si ya existen credenciales, se vuelven a usar automáticamente. Ejecuta ee.Authenticate(force=True) para crear credenciales nuevas.

El paso de inicialización verifica que existan credenciales válidas, ya sea que se hayan creado desde ee.Authenticate() o que ya existan como credenciales predeterminadas de Google. Luego, inicializa la biblioteca cliente de Python con métodos que admite el servidor de backend. Deberás proporcionar un proyecto que te pertenezca o para el que tengas permisos de uso. Consulta Configuración del proyecto de Cloud para registrar el proyecto y habilitar la API de Earth Engine. Este proyecto se usará para ejecutar todas las operaciones de Earth Engine.

En la línea de comandos, la llamada equivalente es earthengine authenticate. Si las credenciales están vencidas o no son válidas, es posible que debas ejecutar earthengine authenticate --force. Las invocaciones de línea de comandos se inicializarán en cada llamada, y puedes usar el argumento --project para configurar el proyecto.

También puedes configurar un proyecto para todas las llamadas futuras si ejecutas earthengine set_project {my-project}. La línea de comandos y ee.Initialize() usarán esto siempre que no se especifique un proyecto directamente. Si usas la autenticación a través de gcloud (consulta a continuación), el proyecto establecido por gcloud auth application-default set-quota-project {my-project} se usará como caso final.

Detalles de la autenticación

El objetivo de los flujos de autenticación de Earth Engine es obtener un "token" de seguridad de la cuenta en la que accediste, que se puede almacenar para otorgarles permiso a tus secuencias de comandos para acceder a tus datos. Por motivos de seguridad, el sistema de autenticación de Google solo pasará esos tokens a sistemas que puedan ser seguros. Consulta las notas técnicas a continuación.

Debido a la sensibilidad del tipo de sistemas involucrados, existen diferentes formas de proceder según tu situación particular. La mayoría de las opciones se controlan con el parámetro auth_mode: como ee.Authenticate(auth_mode=...) o earthengine authenticate --auth_mode=... en la línea de comandos.

Ten en cuenta que, si ya existen credenciales de Google en tu entorno, es posible que no necesites llamar a ee.Authenticate(). Las VMs de Google Cloud, App Engine y otros ambientes proporcionan "credenciales ambientales" que se pueden usar, y gcloud auth application-default login también las creará.

Sin embargo, se recomienda ee.Authenticate() al comienzo de todas las secuencias de comandos para maximizar la compatibilidad. Sin el parámetro auth_mode, está diseñado para funcionar en la mayoría de las situaciones, pero sigue los detalles que se indican a continuación si el modo predeterminado no funciona. El modo predeterminado se selecciona de la siguiente manera:

• colab si se ejecuta en un notebook de Google Colab
• notebook si se ejecuta en otros notebooks de Jupyter que no son de Colab
• localhost si se detecta un navegador web y no hay un binario de gcloud instalado
• gcloud, de lo contrario. Para este modo, deberás instalar gcloud.

Guía y tabla de referencia rápida

En esta guía de decisión, se describen las opciones posibles si no funciona el modo predeterminado que seleccionó ee.Authenticate(). Por ejemplo, si ejecutas en otros entornos de notebook, es posible que debas especificar notebook de forma explícita.

• Entorno local:
  • "Local" significa que estás ejecutando código en una shell de Python o un notebook de Python en la máquina que tienes frente a ti, o más precisamente, en la misma máquina en la que se ejecuta tu navegador web. Esto incluye situaciones de escritorio remoto en las que tanto Python como el navegador están en la misma máquina (remota).
  • Usar auth_mode=localhost es más fácil y se seleccionará de forma predeterminada si no está instalado gcloud, pero tu secuencia de comandos solo funcionará en entornos locales.
  • auth_mode=gcloud y auth_mode=notebook también están disponibles.
• Entorno remoto:
  • “Remoto” significa que el navegador está en una máquina (local), pero el código se ejecuta en otro lugar, como en una estación de trabajo remota o en un notebook basado en la Web.
  • Si usas Colab, usa auth_mode=colab o gcloud si necesitas configurar scopes para llamar a otras APIs.
  • Si puedes instalar gcloud en la máquina remota y en la local, usa auth_mode=gcloud.
  • Si puedes usar un proyecto de autenticación (consulta a continuación), usa auth_mode=notebook.
  • De lo contrario, si no puedes usar un proyecto, instalar gcloud, usar Colab ni usar un navegador en la misma máquina, haz lo siguiente:
  • Habla (otra vez) con un administrador sobre cómo crear proyectos. Por ejemplo:
    • Pídele al administrador que configure un proyecto para ti (como propietario, editor o editor de configuración de OAuth)
    • También puedes pedirle al administrador que te otorgue permisos para crear un proyecto.

En esta tabla, se muestran las combinaciones de funciones que admite cada modo.

	¿Para local o remoto?	Proyecto necesario	Permisos configurables	Se necesita una CLI local	Propietario del proyecto
localhost	local	Sí	S	N	N
colab	remoto	Sí	N	N	N
gcloud	ambos	Sí	S	N	N
notebook	ambos	Sí	S	No	Sí

Credenciales para cuentas de servicio y Compute Engine

ee.Initialize() usará las credenciales de Earth Engine (que ee.Authenticate() almacena en ~/.config/earthengine/credentials) o recuperará credenciales de google.auth.default(), pero si es necesario, puedes pasar un argumento credentials= para usar credenciales de otro lugar y omitir estos valores predeterminados.

Si autenticas código de Python que se ejecutará sin supervisión, te recomendamos que te autentiques con una cuenta de servicio en lugar de una cuenta de usuario. Consulta estos documentos si deseas usar cuentas de servicio con Earth Engine. Otros métodos incluyen authenticate_service_account en el módulo de autenticación de Colab y los métodos que se describen en la guía de Cloud para autenticarse como una cuenta de servicio.

Si tu código se ejecuta en una VM de Compute Engine, se crea una cuenta de servicio predeterminada para el entorno, que ee.Initialize() usará de forma predeterminada. Es posible que debas registrar la cuenta de servicio para usar Earth Engine si el proyecto de Cloud a través del cual se inició la VM no está registrado para su uso con Earth Engine (comercial o no comercial).

Detalles sobre los modos

auth_mode=colab. ee.Authenticate() creará o obtendrá las credenciales predeterminadas que admite Colab. Para ello, ejecutará colab.auth.authenticate_user() si es necesario. Las credenciales siempre usan el alcance cloud-platform y también se pueden usar para llamar a otras APIs de Cloud.

auth_mode=gcloud. Esto delega la autenticación a la herramienta gcloud y es lo mismo que ejecutar gcloud auth application-default login con los permisos predeterminados de Earth Engine (earthengine, cloud-platform y drive) o los permisos en el argumento scopes. El modo gcloud funciona en casos locales y remotos.

Instrucciones paso a paso para el modo gcloud (casos locales y remotos)

En los siguientes pasos, se describe cómo autenticarse desde una línea de comandos en una máquina local.

1. Verifica que gcloud esté instalado en la máquina local.
   • En una terminal, ejecuta gcloud help. Si gcloud no está instalado, sigue estas instrucciones para instalarlo.
2. Terminal de la máquina local
   • En una terminal, ejecuta earthengine authenticate.
   • El resultado del comando indicará que se está usando gcloud para recuperar credenciales.
   • Se abrirá una ventana del navegador en una página de selección de cuentas. Si el navegador no se abre automáticamente, haz clic en la URL.
3. Navegador: Selección de cuenta
   • Selecciona la cuenta que quieres usar para la autenticación.
4. Navegador: Pantalla de consentimiento
   • Indica si quieres otorgar los permisos solicitados y haz clic en "Permitir".
5. Navegador: Pantalla de confirmación
   • El navegador mostrará una página que confirmará que se autenticó y el comando earthengine authenticate en la ventana de la terminal informará que se guardó correctamente el token de autorización.
   • En casos remotos, la página web te dará un código para que lo pegues en el entorno de Python.
6. Continúa con la inicialización.

auth_mode=localhost. Este es un flujo similar a gcloud para los casos en los que gcloud no está instalado. Realiza los mismos pasos que gcloud, pero solo funciona para el caso local. Puedes proporcionar un número de puerto de Internet opcional, p. ej., localhost:8086, o usar localhost:0 para seleccionar automáticamente un puerto. El puerto predeterminado es 8085.

auth_mode=notebook. Este es un modo de uso general diseñado para funcionar en situaciones remotas en las que no están disponibles las líneas de comandos locales. Se te redireccionará a la página de Notebook Authenticator, donde deberás elegir o crear un "proyecto de autenticación". Consulta los detalles y la guía de solución de problemas a continuación. El proyecto que se pasa a ee.Initialize() no tiene que coincidir con esto. Puedes mantener el mismo proyecto para la autenticación mientras trabajas en diferentes proyectos en diferentes notebooks. Se recomienda pasar un proyecto de forma explícita a ee.Initialize(), pero se usará el proyecto de autenticación de forma predeterminada.

Instrucciones paso a paso para el modo notebook

En los siguientes pasos, se describe cómo autenticarse desde una notebook.

1. Navegador: Notebook
   1. En una celda de código de notebook, ejecuta el siguiente código para iniciar un flujo de autenticación con el modo "notebook".

      import ee
      ee.Authenticate()

      Haz clic en el vínculo del resultado de la celda para abrir una página de Notebook Authenticator en una pestaña nueva.
2. Navegador: Autenticador de notebooks
   1. Verifica que aparezca la cuenta de usuario correcta.
   2. Selecciona un proyecto de Google Cloud para usarlo en la autenticación. Si necesitas crear un proyecto nuevo, te recomendamos la convención de nombres "ee-xyz", en la que xyz es tu nombre de usuario habitual de Earth Engine. (Si no puedes seleccionar o crear un proyecto de Cloud, consulta la sección de solución de problemas a continuación).
   Se te deben asignar permisos de IAM suficientes para la autenticación, como propietario o editor del proyecto, o un rol predefinido adicional de "Editor de configuración de OAuth" además de los otros roles de IAM asignados. Si otra persona de tu equipo ya creó una configuración de autenticación en este proyecto, recibirás una advertencia adicional. Solo debes continuar si el creador es un colaborador confiable.
   3. Haz clic en Generar token.
3. Navegador: Selección de cuenta
   • Aparecerá una página de selección de cuentas. Haz clic en la cuenta de usuario a la que deseas otorgar acceso desde el notebook.
4. Navegador: Página de advertencia
   • Aparece una página de advertencia que indica que Google no creó la app (es decir, el código del notebook). Haz clic en Continuar para confirmar.
5. Navegador: Pantalla de consentimiento
   • Indica si deseas otorgar los permisos solicitados y haz clic en Continuar.
6. Navegador: Pantalla del código de autorización
   • Copia el código de verificación de autorización
7. Navegador: Notebook
   • Regresa a la pestaña del notebook y pega el código de verificación en el resultado de la celda del notebook.
   • El resultado de la celda debe indicar "Se guardó correctamente el token de autorización".
8. Continúa con la inicialización.

El modo de notebook tiene un parámetro quiet que rara vez se usa: si se configura, se ejecuta de forma "no interactiva" y no te solicita que ingreses el código de autenticación ni espera a que lo hagas. En su lugar, proporciona un comando para ejecutar y guardar el código.

Proyectos de autenticación

Deberás ser propietario, editor o editor de configuración de OAuth en el proyecto de autenticación que se usa en el modo de notebook. En muchos casos, en particular en equipos más pequeños, el proyecto de autenticación que usas en la página de Notebook Authenticator puede ser el mismo que el proyecto principal que usas para otro trabajo.

Debido a motivos de seguridad, la "configuración del cliente de OAuth" en el proyecto de autenticación es una configuración única. Si tú o algún otro usuario configuraron un cliente de OAuth en el proyecto por otros motivos, no se puede quitar y verás un error que dirá "Configuración de cliente de OAuth2 incompatible". Deberás usar un proyecto diferente para la autenticación o usar los modos colab, localhost o gcloud que se mencionaron anteriormente.

Solución de problemas

¿Qué sucede si no puedo crear un proyecto de Cloud?

Algunas organizaciones controlan quién puede crear proyectos de Cloud. Si recibes un error en la página de Notebook Authenticator cuando intentas crear un proyecto, puedes probar lo siguiente:

1. Intenta crear un proyecto directamente para confirmar si tienes o no los permisos necesarios.
2. Habla con el administrador de tu organización para averiguar qué procesos están disponibles para crear un proyecto.
3. Crea un proyecto desde una cuenta que no sea de la organización y agrega la cuenta que usas para el trabajo como propietario del proyecto. Nota: Algunas organizaciones tienen políticas de seguridad que impiden el acceso a los clientes de OAuth desde proyectos externos.

Error: "La API de Earth Engine no se usó en el proyecto XXX antes o está inhabilitada"

En primer lugar, asegúrate de haber configurado un proyecto en ee.Initialize() o en la línea de comandos (los proyectos predeterminados que proporcionan Cloud y Colab no tendrán habilitado Earth Engine). En segundo lugar, asegúrate de que la API de Earth Engine esté habilitada en tu proyecto.

Error: “El proyecto tiene una configuración de cliente de OAuth2 incompatible”

Los proyectos de Cloud solo pueden tener una configuración de cliente de OAuth2. Para verificar si un proyecto de Cloud tiene configurada una configuración de cliente de OAuth2, consulta los IDs de cliente de OAuth 2.0 en la página Credenciales. Debes seleccionar otro proyecto de Cloud que tenga una configuración compatible que ya haya configurado Notebook Authenticator, o bien seleccionar o crear un proyecto de Cloud sin clientes de OAuth2. El autenticador configurará este proyecto automáticamente. Lamentablemente, el sistema de OAuth no permite que los usuarios borren configuraciones, por lo que se debe usar un proyecto diferente. No es necesario que este proyecto sea el mismo que se usa para otros trabajos de Earth Engine. Ten en cuenta que este error no ocurre en el modo Colab.

Error: "gcloud falló. Verifica si hay algún error anterior y, si es necesario, instala gcloud".

Este error puede ocurrir si gcloud no está instalado o no está en tu RUTA DE ACCESO. También puede ocurrir si llamas a ee.Authenticate(auth_mode='gcloud') desde una celda de código de notebook. En su lugar, usa ee.Authenticate(), que usará de forma predeterminada la autenticación en modo notebook. Si no puedes crear un proyecto, consulta la solución anterior.

¿Qué sucede si no tengo acceso a una máquina local para instalar gcloud?

Si trabajas en un entorno solo web sin acceso a una terminal local y aún necesitas usar una terminal remota, puedes inicializar la herramienta de línea de comandos activando el modo de notebook ejecutando el comando earthengine authenticate --auth_mode=notebook.

Error 400: redirect_uri_mismatch

Es posible que obtengas este error si te autenticas en una máquina remota sin acceso a un navegador web. Intenta agregar --quiet si ejecutas earthengine authenticate desde la línea de comandos o ee.Authenticate(quiet=True) si usas el cliente de Python. Para ello, deberás autenticarte con gcloud desde una máquina que tenga acceso a un navegador web.

Error: "Tu aplicación se autentica con credenciales predeterminadas de la aplicación locales. La API de earthengine.googleapis.com requiere un proyecto de cuota, que no se establece de forma predeterminada".

Este error puede ocurrir cuando Earth Engine no puede determinar el ID de tu proyecto. Si las opciones de solución de problemas de Google Cloud no funcionan, intenta ejecutar earthengine set_project YOUR_PROJECT_ID o gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Notas técnicas

Para los curiosos en materia técnica: la necesidad de estos diferentes mecanismos de creación de credenciales proviene de la necesidad de pasar credenciales a un entorno conocido y confiable. A continuación, se incluye un breve análisis de los diferentes casos anteriores.

• Antes había un modo paste que te proporcionaba un token para pegar en cualquier lugar, pero se consideró demasiado riesgoso y ya no está disponible.
• colab: auth.authenticate_user() te pedirá que compartas credenciales con el cliente de autenticación de "Colab", el entorno del notebook. Luego, están disponibles a través de google.auth.default() y las usa ee.Initialize().
• localhost: Las credenciales se pasan del navegador a un puerto en tu máquina local. En esta situación, la seguridad de extremo a extremo depende de que tu máquina local no se haya visto comprometida. El cliente de autenticación que verás es el "Autenticador de Earth Engine".
• gcloud: Usa el flujo --launch-browser que se describe en la referencia de gcloud y --no-launch-browser si estás en una máquina remota. El cliente de autenticación que se usa es "Biblioteca de Google Auth".
• notebook: Creamos un nuevo cliente de autenticación específicamente para tu trabajo. Verás tu dirección de correo electrónico en la página de consentimiento. Este cliente se configura en el modo “desarrollo”, que es un caso especial que permite los tokens de modo de pegado anteriores. Para ello, debemos usar tu propio proyecto, ya que estos clientes no se pueden compartir con una gran cantidad de usuarios.