Anúncio: todos os projetos não comerciais registrados para usar o Earth Engine antes de 15 de abril de 2025 precisam verificar a qualificação não comercial para manter o acesso ao Earth Engine.

Esta página foi traduzida pela API Cloud Translation.

Autenticação e inicialização

Antes de fazer solicitações ao Earth Engine usando uma biblioteca de cliente, é necessário autenticar e usar as credenciais resultantes para inicializar o cliente do Earth Engine.

Editor de código do Earth Engine e JavaScript

A autenticação e a inicialização são processadas automaticamente no editor de código. Você pode encaminhar solicitações por um projeto do Cloud a partir do seu login no canto superior direito do Editor de código.

Se você estiver usando a API JavaScript (fora do editor de código), use um dos ajudantes de autenticação em ee.data (por exemplo, ee.data.authenticateViaPopup()) seguido por ee.initialize(), conforme mostrado neste exemplo.

Python e linha de comando

Antes de usar a biblioteca de cliente Python do Earth Engine, é necessário fazer a autenticação (verificar sua identidade) e usar as credenciais resultantes para inicializar o cliente Python. Os fluxos de autenticação usam Projetos do Cloud para fazer a autenticação, e são usados para uso não pago (sem custo financeiro, não comercial) e pago. Para autenticar e inicializar, execute

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

Isso vai selecionar o melhor modo de autenticação para seu ambiente e pedir que você confirme o acesso aos scripts. Se as credenciais já existirem, elas serão reutilizadas automaticamente. Execute ee.Authenticate(force=True) para criar novas credenciais.

A etapa de inicialização verifica se existem credenciais válidas, criadas a partir de ee.Authenticate() ou preexistentes como credenciais padrão do Google. Em seguida, ela inicializa a biblioteca de cliente do Python com métodos compatíveis com o servidor de back-end. Você precisa fornecer um projeto que seja seu ou que você tenha permissões para usar. Consulte Configuração do projeto do Cloud para registrar o projeto e ativar a API Earth Engine. Esse projeto será usado para executar todas as operações do Earth Engine.

Na linha de comando, a chamada equivalente é earthengine authenticate. Se as credenciais estiverem expiradas ou inválidas, talvez seja necessário executar earthengine authenticate --force. As invocações de linha de comando serão inicializadas em cada chamada, e você poderá usar o argumento --project para definir o projeto.

Também é possível configurar um projeto para todas as chamadas futuras executando earthengine set_project {my-project}. A linha de comando e o ee.Initialize() vão usar isso sempre que um projeto não for especificado diretamente. Se você usar a autenticação pelo gcloud (consulte abaixo), o projeto definido por gcloud auth application-default set-quota-project {my-project} será usado como um caso final.

Detalhes da autenticação

O objetivo dos fluxos de autenticação do Earth Engine é receber um "token" de segurança da sua conta com login, que pode ser armazenado para dar permissão aos scripts para acessar seus dados. Por motivos de segurança, o sistema de autenticação do Google somente vai transmitir esses tokens para sistemas que possam ser protegidos. Consulte as notas técnicas abaixo.

Devido à sensibilidade do tipo de sistema envolvido, há diferentes maneiras de proceder, dependendo da sua situação específica. A maioria das opções é controlada pelo parâmetro auth_mode: como ee.Authenticate(auth_mode=...) ou earthengine authenticate --auth_mode=... na linha de comando.

Se as credenciais do Google já existirem no seu ambiente, talvez não seja necessário chamar ee.Authenticate(). As VMs do Google Cloud, o App Engine e outros ambientes fornecem "credenciais ambientais" utilizáveis, e o gcloud auth application-default login também as cria.

No entanto, ee.Authenticate() é recomendado no início de todos os scripts para maximizar a compatibilidade. Sem o parâmetro auth_mode, ele foi projetado para funcionar na maioria das situações, mas siga os detalhes abaixo se o modo padrão não funcionar. O modo padrão é selecionado da seguinte maneira:

colab se estiver sendo executado em um notebook do Google Colab
notebook se estiver sendo executado em outros notebooks do Jupyter que não são do Colab
localhost se um navegador da Web for detectado e nenhum binário do gcloud estiver instalado
gcloud, caso contrário. Para esse modo, você precisa instalar o gcloud.

Guia de referência rápida e tabela

Este guia de decisão descreve as opções possíveis se o modo padrão selecionado por ee.Authenticate() não funcionar. Por exemplo, se você estiver executando em outros ambientes de notebook, talvez seja necessário especificar notebook explicitamente.

Ambiente local.
- "Local" significa que você está executando o código em um shell ou notebook Python na máquina em frente a você, ou seja, na mesma máquina em que seu navegador da Web está em execução. Isso inclui situações de área de trabalho remota em que o Python e o navegador estão na mesma máquina (remota).
- O uso de auth_mode=localhost é mais fácil e será selecionado por padrão se o gcloud não estiver instalado, mas o script só vai funcionar em ambientes locais.
- auth_mode=gcloud e auth_mode=notebook também estão disponíveis.
Ambiente remoto.
- "Remoto" significa que o navegador está em uma máquina (local), mas o código está executando em outro lugar, como em uma estação de trabalho remota ou em um notebook baseado na Web.
- Se estiver no Colab, use auth_mode=colab. Se precisar definir gcloud para chamar outras APIs, use gcloud.scopes
- Se você puder instalar o gcloud na máquina remota e na máquina local, use auth_mode=gcloud.
- Se você puder usar um projeto de autenticação (consulte abaixo), use auth_mode=notebook.
- Caso contrário, se não for possível usar um projeto ou instalar o gcloud ou usar o Colab ou um navegador na mesma máquina:
- Fale com um administrador (novamente) sobre a criação de projetos. Exemplo:
  - Peça ao administrador para configurar um projeto para você (como proprietário ou editor ou editor de configuração do OAuth)
  - Ou peça ao administrador para conceder permissões para criar um projeto.

Esta tabela mostra quais combinações de recursos são compatíveis com cada modo.

	Para local ou remoto?	Projeto necessário	Escopos configuráveis	CLI local necessária	Proprietário do projeto
`localhost`	Local	S	S	N	N
`colab`	controle remoto	S	N	N	N
`gcloud`	ambos	S	S	N	N
`notebook`	ambos	S	S	N	S

Credenciais para contas de serviço e Compute Engine

O ee.Initialize() vai usar as credenciais do Earth Engine (armazenadas pelo ee.Authenticate() em ~/.config/earthengine/credentials) ou recuperar credenciais do google.auth.default(). Se necessário, você pode transmitir um argumento credentials= para usar credenciais de outro lugar, ignorando essas configurações padrão.

Se você estiver autenticando um código Python que será executado sem supervisão, faça a autenticação com uma conta de serviço em vez de uma conta de usuário. Consulte estes documentos para saber como usar contas de serviço com o Earth Engine. Outros métodos incluem authenticate_service_account no módulo de autenticação do Colab e os métodos descritos no guia do Cloud para autenticação como uma conta de serviço.

Se o código estiver em execução em uma VM do Compute Engine, uma conta de serviço padrão será criada para o ambiente, que o ee.Initialize() vai usar por padrão. Talvez seja necessário registrar a conta de serviço para usar o Earth Engine se o projeto do Cloud em que a VM foi iniciada não estiver registrado para uso com o Earth Engine (comercial ou não comercial).

Detalhes sobre os modos

auth_mode=colab. O ee.Authenticate() cria ou extrai as credenciais padrão aceitas pelo Colab, executando colab.auth.authenticate_user(), se necessário. As credenciais sempre usam o escopo cloud-platform e também podem ser usadas para chamar outras APIs do Cloud.

auth_mode=gcloud. Isso delega a autenticação à ferramenta gcloud e é o mesmo que executar gcloud auth application-default login com os escopos padrão do Earth Engine (earthengine, cloud-platform e drive) ou os escopos no argumento scopes. O modo gcloud funciona em casos locais e remotos.

Instruções detalhadas para o modo gcloud (casos locais e remotos)

Verifique se o gcloud está instalado na máquina local.
- Em um terminal, execute gcloud help. Se o gcloud não estiver instalado, siga estas instruções para instalar o gcloud.
Terminal da máquina local
- Em um terminal, execute earthengine authenticate.
- A saída do comando vai indicar que o gcloud está sendo usado para buscar credenciais.
- Uma janela do navegador vai abrir para a página de seleção de conta. Se o navegador não abrir automaticamente, clique no URL.
Navegador: seleção de conta
- Selecione a conta que você quer usar para a autenticação.
Navegador: tela de consentimento
- Indique se você quer conceder os escopos solicitados e clique em "Permitir".
Navegador: tela de confirmação
- O navegador vai mostrar uma página confirmando que você está autenticado, e o comando earthengine authenticate na janela do terminal vai informar "Token de autorização salvo com sucesso".
- Em casos remotos, a página da Web vai fornecer um código para colar de volta no ambiente Python.
Prossiga com a inicialização.

auth_mode=localhost. Este é um fluxo semelhante ao gcloud para casos em que o gcloud não está instalado. Ele executa as mesmas etapas do gcloud, mas só funciona para o caso local. Você pode fornecer um número de porta de Internet opcional, por exemplo, localhost:8086, ou usar localhost:0 para selecionar automaticamente uma porta. A porta padrão é 8085.

auth_mode=notebook. Esse é um modo de uso geral projetado para funcionar em situações remotas em que as linhas de comando locais não estão disponíveis. Ele vai enviar você para a página do autenticador do Notebook, onde você vai precisar escolher ou criar um "projeto de autenticação". Confira os detalhes e o guia de solução de problemas abaixo. O projeto transmitido para ee.Initialize() não precisa corresponder a ele. Você pode manter o mesmo projeto para autenticação enquanto trabalha em projetos diferentes em diferentes notebooks. É recomendável transmitir um projeto explicitamente para ee.Initialize(), mas o projeto de autenticação será usado por padrão.

Instruções detalhadas sobre o modo notebook

Navegador: Notebook
1. Em uma célula de código do notebook, execute o código abaixo para iniciar um fluxo de autenticação usando o modo "notebook".
```
import ee
ee.Authenticate()
```
  Clique no link na saída da célula para abrir uma página do autenticador de notebooks em uma nova guia.
Navegador: Autenticador de notebook
1. Verifique se a conta de usuário correta está listada.
2. Selecione um projeto do Google Cloud para usar na autenticação. Se você precisar criar um novo projeto, recomendamos a convenção de nomenclatura "ee-xyz", em que xyz é seu nome de usuário do Earth Engine. Se você não conseguir selecionar ou criar um projeto do Cloud, consulte a seção de solução de problemas abaixo.
3. Clique em "Gerar token".
Navegador: seleção de conta
- Uma página de seleção de contas vai aparecer. Clique na conta de usuário que você quer conceder acesso ao notebook.
Navegador: página de aviso
- Uma página de aviso é apresentada, indicando que o Google não criou o app (ou seja, o código no notebook). Clique em "Continuar" para confirmar.
Navegador: tela de consentimento
- Indique se você quer conceder os escopos solicitados e clique em Continuar.
Navegador: tela do código de autorização
- Copiar o código de verificação de autorização
Navegador: Notebook
- Volte para a guia do notebook e cole o código de verificação na saída da célula do notebook.
- A saída da célula precisa indicar "Token de autorização salvo com sucesso."
Prossiga com a inicialização.

O modo de notebook tem um parâmetro quiet raramente usado: se definido, ele é executado "de forma não interativa" e não solicita e aguarda que você insira o código de autenticação. Em vez disso, ele fornece um comando para executar e salvar o código.

Projetos de autenticação

Você precisa ser proprietário, editor ou editor de configuração do OAuth no projeto de autenticação usado no modo de notebook. Em muitos casos, principalmente em equipes menores, o projeto de autenticação usado na página do Notebook Authenticator pode ser o mesmo que o projeto principal usado para outros trabalhos.

Devido a problemas de segurança, a "configuração do cliente OAuth" no projeto de autenticação é uma configuração única. Se você ou outros usuários tiverem configurado um cliente OAuth no projeto por outros motivos, ele não poderá ser removido e uma mensagem de erro será exibida informando que a configuração do cliente OAuth2 é incompatível. Você vai precisar usar um projeto diferente para autenticação ou usar os modos colab, localhost ou gcloud acima.

Solução de problemas

E se eu não conseguir criar um projeto do Cloud?

Algumas organizações controlam quem pode criar projetos do Cloud. Se você receber um erro na página do autenticador do notebook ao tentar criar um projeto, tente o seguinte:

Tente criar um projeto diretamente para confirmar se você tem as permissões necessárias.
Converse com o administrador da sua organização para descobrir quais processos estão disponíveis para criar um projeto.
Crie um projeto em uma conta que não seja da organização e adicione a conta que você usa para trabalho como proprietário do projeto. Observação: algumas organizações têm políticas de segurança que impedem o acesso a clientes OAuth de projetos externos.

Erro: "A API Earth Engine não foi usada no projeto XXX antes ou está desativada"

Primeiro, verifique se você configurou um projeto em ee.Initialize() ou na linha de comando. Os projetos padrão fornecidos pelo Cloud e pelo Colab não têm o Earth Engine ativado. Em segundo lugar, verifique se a API Earth Engine está ativada no seu projeto.

Erro: "O projeto tem uma configuração de cliente OAuth2 incompatível"

Os projetos do Cloud só podem ter uma configuração de cliente OAuth2. Para verificar se um projeto do Cloud tem uma configuração de cliente OAuth2 definida, verifique os IDs de cliente OAuth 2 na página "Credenciais". Selecione outro projeto do Cloud que tenha uma configuração compatível já configurada pelo autenticador de notebook ou selecione ou crie um projeto do Cloud sem clientes OAuth2. O autenticador vai configurar esse projeto automaticamente. Infelizmente, o sistema OAuth não permite que os usuários excluam configurações. Portanto, é necessário usar um projeto diferente. Esse projeto não precisa ser o mesmo usado para outros trabalhos do Earth Engine. Esse erro não ocorre no modo Colab.

Erro: "gcloud failed. Verifique se há algum erro acima e instale o gcloud, se necessário."

Esse erro pode ocorrer se o gcloud não estiver instalado ou não estiver no seu PATH. Isso também pode ocorrer se você chamar ee.Authenticate(auth_mode='gcloud') em uma célula de código do notebook. Use ee.Authenticate(), que vai usar a autenticação no modo notebook por padrão. Se não for possível criar um projeto, consulte a solução acima.

E se eu não tiver acesso a uma máquina local para instalar a gcloud?

Se você estiver trabalhando em um ambiente somente para Web sem acesso a um terminal local e ainda precisar usar um terminal remoto, ainda será possível inicializar a ferramenta de linha de comando acionando o modo de notebook executando o comando earthengine authenticate --auth_mode=notebook.

Erro 400: redirect_uri_mismatch

Você pode receber esse erro se fizer a autenticação em uma máquina remota sem acesso a um navegador da Web. Tente adicionar --quiet se estiver executando earthengine authenticate na linha de comando ou ee.Authenticate(quiet=True) se estiver usando o cliente Python. Para isso, você precisa se autenticar com gcloud em uma máquina que tenha acesso a um navegador da Web.

Erro: "Seu aplicativo está autenticando usando as credenciais padrão locais do aplicativo. A API earthengine.googleapis.com exige um projeto de cota, que não é definido por padrão."

Esse erro pode ocorrer quando o Earth Engine não consegue determinar o ID do seu projeto. Se as opções de solução de problemas do Google Cloud não funcionarem, tente executar earthengine set_project YOUR_PROJECT_ID ou gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Observações técnicas

Para os curiosos: a necessidade de diferentes mecanismos de criação de credenciais vem da necessidade de transmitir credenciais para um ambiente conhecido e confiável. Confira uma breve discussão sobre os diferentes casos acima.

Havia um modo paste que dava a você um token para colar em qualquer lugar, e isso foi considerado muito arriscado e não está mais disponível.
colab: o auth.authenticate_user() vai solicitar que você compartilhe as credenciais com o cliente de autenticação "Colab", o próprio ambiente do notebook. Elas ficam disponíveis em google.auth.default() e são usadas por ee.Initialize().
localhost: as credenciais são transmitidas do navegador para uma porta na máquina local. Nessa situação, a segurança de ponta a ponta depende do fato de que a máquina local não foi comprometida. O cliente de autenticação que você vai encontrar é o "Autenticador do Earth Engine".
gcloud: usa o fluxo --launch-browser descrito na referência do gcloud e --no-launch-browser se estiver em uma máquina remota. O cliente de autenticação usado é a "Biblioteca de autenticação do Google".
notebook: criamos um novo cliente de autenticação especificamente para seu trabalho. Seu endereço de e-mail vai aparecer na página de consentimento. Esse cliente está definido no modo "desenvolvimento", que é um caso especial que permite os tokens de modo de colagem mais antigos. Precisamos usar seu próprio projeto para isso, porque esses clientes não podem ser compartilhados com um grande número de usuários.