O Earth Engine introduziu níveis de cota não comercial para proteger recursos de computação compartilhados e garantir um desempenho confiável para todo mundo. Os projetos não comerciais usam o nível da comunidade por padrão, mas é possível mudar o nível de um projeto a qualquer momento.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 optar por rotear solicitações por um projeto na nuvem no 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 auxiliares 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 autenticar (verificar sua identidade) e usar as credenciais resultantes para inicializar o cliente Python. Os fluxos de autenticação usam projetos do Cloud para autenticar 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 pelo ee.Authenticate() ou preexistentes como credenciais padrão do Google. Em seguida, ela inicializa a biblioteca de cliente 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 na nuvem 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 forem 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 esse ID sempre que um projeto não for especificado diretamente. Se você usar a autenticação por meio de gcloud (veja abaixo), o projeto definido por gcloud auth application-default set-quota-project {my-project} será usado como um caso final.

Detalhes de autenticação

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

Devido à sensibilidade ao tipo de sistemas envolvidos, 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 de ambiente" utilizáveis, e o gcloud auth application-default login também as criará.

No entanto, recomendamos usar ee.Authenticate() 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 executando em um notebook do Google Colab
notebook se estiver em execução em outros notebooks Jupyter que não sejam do Colab
localhost se um navegador da Web for detectado e nenhum binário da gcloud estiver instalado
gcloud, caso contrário. Para esse modo, é necessário instalar a gcloud.

Guia e tabela de referência rápida

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 do Python na máquina à sua frente ou, mais precisamente, na mesma máquina em que o navegador da Web está sendo executado. Isso inclui situações de área de trabalho remota em que o Python e o navegador estão na mesma máquina (remota).
- Usar auth_mode=localhost é mais fácil e será selecionado por padrão se o gcloud não estiver instalado, mas o script só 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á em execução 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 scopes para chamar outras APIs, use gcloud.
- Se você puder instalar a gcloud na máquina remota e na máquina local, use auth_mode=gcloud.
- Se você puder usar um projeto de autenticação (veja abaixo), use auth_mode=notebook.
- Caso contrário, se não for possível usar um projeto, instalar a gcloud, usar o Colab ou usar 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, editor ou editor de configuração do OAuth)
  - Ou peça ao administrador para conceder a você 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 (que o ee.Authenticate() armazena em ~/.config/earthengine/credentials) ou recuperar as credenciais do google.auth.default(). No entanto, se necessário, é possível transmitir um argumento credentials= para usar credenciais de outro lugar, ignorando esses padrões.

Se você estiver autenticando um código Python que será executado sem supervisão, autentique-se com uma conta de serviço em vez de uma conta de usuário. Consulte estes documentos para 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() usará por padrão. Talvez seja necessário registrar a conta de serviço para usar o Earth Engine se o projeto na nuvem 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. ee.Authenticate() vai criar ou receber as credenciais padrão compatíveis com o 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 a gcloud está instalada na máquina local.
- Em um terminal, execute gcloud help. Se a gcloud não estiver instalada, siga estas instruções para instalar a gcloud.
Terminal da máquina local
- Em um terminal, execute earthengine authenticate.
- A resposta ao comando vai indicar que a gcloud está sendo usada para buscar credenciais.
- Uma janela do navegador será aberta em uma 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 autenticação.
Navegador: tela de permissão
- 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 você colar de volta no ambiente do Python.
Prossiga com a inicialização.

auth_mode=localhost. Esse é um fluxo semelhante ao gcloud para casos em que o gcloud não está instalado. Ele executa as mesmas etapas que a gcloud, mas só funciona para o caso local. É possível fornecer um número de porta de Internet opcional, como localhost:8086, ou usar localhost:0 para selecionar uma porta automaticamente. 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 direciona você para a página do Notebook Authenticator, onde é preciso 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 isso. É possível manter o mesmo projeto para autenticação enquanto trabalha em projetos diferentes em notebooks diferentes. É recomendável transmitir um projeto explicitamente para ee.Initialize(), mas o projeto de autenticação será usado por padrão.

Instruções detalhadas para o modo notebook

Navegador: Notebook
1. Em uma célula de código do notebook, execute o código a seguir 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 Notebook Authenticator 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 habitual do Earth Engine. Se não for possível selecionar ou criar um projeto na nuvem, 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 conta vai aparecer. Clique na conta de usuário a que você quer conceder acesso no 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 permissão
- Indique se você quer conceder os escopos solicitados e clique em Continuar.
Navegador: tela do código de autorização
- Copie 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 deve indicar "Successfully saved authorization token."
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 nem espera 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 autenticador de notebooks pode ser o mesmo que o projeto principal usado para outros trabalhos.

Devido a preocupações com 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 você verá um erro dizendo "configuração incompatível do cliente OAuth2". Será necessário usar um projeto diferente para autenticação ou os modos colab, localhost ou gcloud acima.

Detalhes sobre escopos

As configurações de autenticação padrão do Earth Engine incluem todos os escopos disponíveis. Portanto, você pode pular esta seção se os padrões atenderem aos seus requisitos.

Escopos do Earth Engine: um escopo do OAuth 2.0 define e restringe o conjunto de recursos e operações que um aplicativo pode acessar em nome de um usuário. Ao usar o OAuth para autenticar com o Earth Engine, é necessário solicitar um ou mais dos seguintes escopos:

https://www.googleapis.com/auth/earthengine: acesso de leitura e gravação aos recursos do Earth Engine. Necessário para criar, modificar ou excluir recursos, gerenciar permissões de recursos e executar tarefas de exportação.
https://www.googleapis.com/auth/earthengine.readonly: acesso somente leitura aos recursos do Earth Engine.

Ambos os escopos permitem executar scripts e cálculos (como avaliar expressões ou renderizar visualizações de mapas).

Escopos do Google Cloud e do Drive: se as consultas ou os scripts do Earth Engine fizerem referência a dados ou recursos externos, suas credenciais também precisarão incluir os escopos apropriados para esses serviços:

Cloud Storage (GCS) (ao ler ou gravar em buckets do Cloud Storage, como carregar GeoTIFFs otimizados para nuvem (COGs) ou exportar saídas de tarefas):
- 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) (ao ler tabelas ou gravar exportações no BigQuery):
- https://www.googleapis.com/auth/bigquery
Google Drive (ao acessar ou exportar dados para o Google Drive):
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/drive.readonly

O Google Cloud também oferece escopos amplos que abrangem todos os serviços do Google Cloud:

Cloud Platform (acesso amplo aos serviços do Google Cloud, incluindo o Earth Engine, o Cloud Storage e o BigQuery. O Google Drive é um serviço separado do Workspace e não é coberto por esses escopos):
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud-platform.read-only

Escopos padrão: os escopos padrão configurados pelo Editor de Código do Earth Engine e pelas bibliotecas de cliente (como ee.Authenticate()) incluem todos estes escopos: earthengine, cloud-platform e drive (veja os detalhes acima). Consequentemente, a personalização do escopo (por exemplo, usando o parâmetro scopes em ee.Authenticate(scopes=[...])) só é necessária se você tiver restrições de segurança específicas ou políticas da organização que exijam a limitação de permissões.

Solução de problemas

E se eu não conseguir criar um projeto na nuvem?

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

Tente criar um projeto diretamente para confirmar se você tem as permissões necessárias.
Fale com o administrador da sua organização para saber quais processos estão disponíveis para criar um projeto.
Crie um projeto usando uma conta não organizacional e adicione a conta que você usa para trabalhar 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 ou está desativada"

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

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

Os projetos na nuvem só podem ter uma configuração de cliente OAuth2. Para verificar se um projeto na nuvem tem uma configuração de cliente OAuth2 definida, verifique os IDs do cliente OAuth 2.0 na página "Credenciais". Selecione outro projeto na nuvem que tenha uma configuração compatível já definida pelo Notebook Authenticator ou selecione ou crie um projeto na nuvem 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á erros acima e instale a gcloud, se necessário."

Esse erro pode ocorrer se a gcloud não estiver instalada ou não estiver no PATH. Isso também pode ocorrer se você chamar ee.Authenticate(auth_mode='gcloud') de dentro de uma célula de código do notebook. Use ee.Authenticate(), que usará como padrão a autenticação do modo notebook. 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, inicialize a ferramenta de linha de comando acionando o modo de notebook com o comando earthengine authenticate --auth_mode=notebook.

Erro 400: redirect_uri_mismatch

Esse erro pode ocorrer se você 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. Isso exige que você faça a autenticação com gcloud em uma máquina que tenha acesso a um navegador da Web.

Erro: "Seu aplicativo está se autenticando usando o Application Default Credentials local. A API earthengine.googleapis.com requer 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 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.

Erro: "Escopos obrigatórios ausentes para [Cloud Storage / BigQuery]"

Esse erro ocorre quando uma solicitação do Earth Engine acessa recursos do Cloud Storage ou do BigQuery, mas as credenciais usadas para inicializar o Earth Engine não incluem os escopos necessários para esse serviço (ou o escopo cloud-platform, que abrange todos os serviços do Google Cloud). Isso geralmente acontece se você personalizou o parâmetro scopes durante a autenticação (por exemplo, fornecendo apenas escopos do Earth Engine para ee.Authenticate(scopes=[...])) ou se as credenciais existentes foram criadas sem esses escopos.

Há duas maneiras de resolver esse problema:

Autenticar novamente com escopos padrão: as credenciais padrão do Earth Engine incluem o escopo cloud-platform, que abrange o Cloud Storage e o BigQuery. Faça a reautenticação usando as configurações padrão:
- Em Python: ee.Authenticate(force=True)
- Na linha de comando: earthengine authenticate --force
Inclua os escopos necessários: se o ambiente exigir a personalização de escopos, verifique se a lista scopes inclui https://www.googleapis.com/auth/cloud-platform ou o escopo de serviço específico (como https://www.googleapis.com/auth/devstorage.full_control ou https://www.googleapis.com/auth/devstorage.read_only para o Cloud Storage ou https://www.googleapis.com/auth/bigquery para o BigQuery).

Para mais detalhes sobre os escopos disponíveis, consulte Detalhes sobre escopos.

Notas técnicas

Para os curiosos: a necessidade desses 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.

Costumava haver um modo paste que fornecia um token para colar em qualquer lugar, mas 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 do Colab, o próprio ambiente do notebook. Eles ficam disponíveis em google.auth.default() e são usados 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 sua máquina local não foi comprometida. O cliente de autenticação que você vai ver é o "Earth Engine Authenticator".
gcloud: usa o fluxo --launch-browser descrito na referência da 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. Você verá seu endereço de e-mail na página de consentimento. Esse cliente está definido no modo de desenvolvimento, que é um caso especial que permite os tokens do 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.