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 rotear solicitações por um projeto do Cloud 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 helpers 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 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')

Primeiro, ele vai selecionar o melhor modo de autenticação para seu ambiente e pedir que você confirme o acesso aos seus 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 há credenciais válidas, criadas em ee.Authenticate() ou preexistentes como credenciais padrão do Google. Em seguida, ele inicializa a biblioteca de cliente Python com métodos compatíveis com o servidor de back-end. Você precisa fornecer um projeto de sua propriedade ou ter 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 expirarem 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.

Você também pode 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ê estiver usando a autenticação por gcloud (veja 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 conectada, que pode ser armazenado para dar aos seus scripts permissão de 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 observações técnicas abaixo.

Devido à sensibilidade do 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, seja 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, é recomendável 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 executando em outros notebooks Jupyter que não são 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 o gcloud.

Guia e tabela de referência rápida

Este guia descreve as opções possíveis se o modo padrão selecionado pelo 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 código em um shell ou notebook Python na máquina em frente a você 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 seu 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 seu navegador está em uma máquina (local), mas seu código está sendo executado em outro lugar, como em uma estação de trabalho remota ou um notebook baseado na Web.
- Se estiver no Colab, use auth_mode=colab. Use gcloud se precisar definir scopes para chamar outras APIs.
- Se você puder instalar a gcloud na máquina remota e na 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 um navegador na mesma máquina:
- Fale com um administrador (de novo) 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 permissões de criação de projeto.

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

	Para local ou remoto?	Projeto necessário	Escopos definí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 credenciais de 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, talvez seja melhor fazer a autenticação 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 sendo executado 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 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() 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 o gcloud está instalado na máquina local.
- Em um terminal, execute gcloud help. Se gcloud não estiver instalado, siga estas instruções para instalar gcloud.
Terminal da máquina local
- Em um terminal, execute earthengine authenticate.
- A resposta ao comando vai indicar que o gcloud está sendo usado para buscar credenciais.
- Uma janela do navegador será aberta em uma página de seleção de contas. 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 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.
Continue 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 do gcloud, mas funciona apenas para o caso local. Você pode fornecer um número de porta da Internet opcional, por exemplo, 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. Ela vai direcionar você para a página do Notebook Authenticator, em que será necessário 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. Você pode 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: Notebook Authenticator
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 comum 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 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 consentimento
- 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.
- A saída da célula deve indicar "Successfully saved authorization token."
Continue com a inicialização.

O modo 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 dá 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 notebook. Em muitos casos, principalmente em equipes menores, o projeto de autenticação usado na página "Autenticador de notebook" pode ser o mesmo 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 você vai receber um erro dizendo "configuração de cliente OAuth2 incompatível". Você precisará usar um projeto diferente para autenticação ou usar 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 a recursos e ativos 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.

Os dois escopos permitem executar scripts e computações (como avaliar expressões ou renderizar visualizações de mapas).

Escopos do Google Cloud e do Drive: se suas consultas ou 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 a nuvem 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 Earth Engine, Cloud Storage e BigQuery. O Google Drive é um serviço separado do Workspace e não está incluído nesses 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. Consulte 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 ou políticas organizacionais específicas que exijam a limitação de permissões.

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 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 com uma conta não organizacional e adicione a conta que você usa no trabalho como proprietária 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 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 na nuvem tem uma configuração de cliente OAuth2, confira os IDs do cliente OAuth 2.0 na página "Credenciais". Selecione outro projeto na nuvem que já tenha uma configuração compatível 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 seu PATH. Isso também pode acontecer se você chamar ee.Authenticate(auth_mode='gcloud') de uma célula de código de notebook. Use ee.Authenticate(), que usa a autenticação do 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 da Web sem acesso a um terminal local e ainda precisar usar um terminal remoto, será possível inicializar a ferramenta de linha de comando acionando o modo de notebook ao executar o comando earthengine authenticate --auth_mode=notebook.

Erro 400: redirect_uri_mismatch

Esse erro pode ocorrer ao autenticar 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 fazer a autenticação com gcloud em uma máquina que tenha acesso a um navegador da Web.

Erro: "Seu aplicativo está sendo autenticado usando o Application Default Credentials local. 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.

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 atuais foram criadas sem esses escopos.

Há duas maneiras de resolver esse problema:

Reautenticar com escopos padrão: as credenciais padrão do Earth Engine incluem o escopo cloud-platform, que abrange o Cloud Storage e o BigQuery. Reautentique 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 específico do serviço (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.

Observações técnicas

Para quem tem curiosidade técnica: 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.

Antes, havia um modo paste que dava um token para colar em qualquer lugar. Isso foi considerado muito arriscado e não está mais disponível.
colab: o auth.authenticate_user() vai pedir que você compartilhe as credenciais com o cliente de autenticação "Colab", o próprio ambiente do notebook. Eles ficam disponíveis pelo google.auth.default() e são usados pelo 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 de que sua máquina local não tenha sido comprometida. O cliente de autenticação que você vai ver é o "Earth Engine Authenticator".
gcloud: usa o fluxo --launch-browser descrito na referência 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 do modo de colagem mais antigo. Precisamos usar seu próprio projeto para isso, porque esses clientes não podem ser compartilhados com um grande número de usuários.