Earth Engine a introduit des niveaux de quota non commerciaux pour protéger les ressources de calcul partagées et garantir des performances fiables pour tous. Les projets non commerciaux utilisent le niveau "Communauté" par défaut, mais vous pouvez modifier le niveau d'un projet à tout moment.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Authentification et initialisation

Avant de pouvoir envoyer des requêtes à Earth Engine via une bibliothèque cliente, vous devez vous authentifier et utiliser les identifiants obtenus pour initialiser le client Earth Engine.

Éditeur de code Earth Engine et JavaScript

L'authentification et l'initialisation sont gérées automatiquement dans l'éditeur de code. Vous pouvez choisir de router les requêtes via un projet cloud à partir de votre identifiant de connexion en haut à droite de l'éditeur de code.

Si vous utilisez l'API JavaScript (en dehors de l'éditeur de code), utilisez l'un des assistants d'authentification dans ee.data (par exemple, ee.data.authenticateViaPopup()), suivi de ee.initialize(), comme indiqué dans cet exemple.

Python et ligne de commande

Avant d'utiliser la bibliothèque cliente Python Earth Engine, vous devez vous authentifier (valider votre identité) et utiliser les identifiants obtenus pour initialiser le client Python. Les flux d'authentification utilisent les projets Cloud pour l'authentification. Ils sont utilisés pour un usage non payant (sans frais, non commercial) ainsi que pour un usage payant. Pour vous authentifier et initialiser, exécutez

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

Cette opération sélectionne d'abord le meilleur mode d'authentification pour votre environnement, puis vous invite à confirmer l'accès pour vos scripts. Si des identifiants existent déjà, ils sont automatiquement réutilisés. Exécutez ee.Authenticate(force=True) pour créer de nouveaux identifiants.

L'étape d'initialisation vérifie que des identifiants valides existent, qu'ils aient été créés à partir de ee.Authenticate() ou qu'ils soient préexistants en tant qu'identifiants Google par défaut. Il initialise ensuite la bibliothèque cliente Python avec les méthodes compatibles avec le serveur backend. Vous devrez fournir un projet dont vous êtes propriétaire ou pour lequel vous disposez des autorisations nécessaires. Consultez la section Configurer un projet Cloud pour enregistrer le projet et activer l'API Earth Engine. Ce projet sera utilisé pour exécuter toutes les opérations Earth Engine.

Sur la ligne de commande, l'appel équivalent est earthengine authenticate. Si les identifiants ont expiré ou ne sont pas valides, vous devrez peut-être exécuter earthengine authenticate --force. Les appels de ligne de commande s'initialisent à chaque appel. Vous pouvez utiliser l'argument --project pour définir le projet.

Vous pouvez également configurer un projet pour tous les futurs appels en exécutant earthengine set_project {my-project}. La ligne de commande et ee.Initialize() l'utiliseront chaque fois qu'un projet n'est pas spécifié directement. Si vous utilisez l'authentification via gcloud (voir ci-dessous), le projet défini par gcloud auth application-default set-quota-project {my-project} sera utilisé comme cas final.

Informations d'authentification

L'objectif des flux d'authentification Earth Engine est d'obtenir un "jeton" de sécurité à partir de votre compte connecté, qui peut être stocké pour autoriser vos scripts à accéder à vos données. Pour des raisons de sécurité, le système d'authentification de Google ne transmettra ces jetons qu'aux systèmes pouvant être sécurisés. Consultez les notes techniques ci-dessous.

En raison de la sensibilité des systèmes concernés, il existe différentes manières de procéder selon votre situation particulière. La plupart des options sont contrôlées par le paramètre auth_mode, soit sous la forme ee.Authenticate(auth_mode=...), soit sous la forme earthengine authenticate --auth_mode=... sur la ligne de commande.

Notez que si des identifiants Google existent déjà dans votre environnement, vous n'aurez peut-être pas besoin d'appeler ee.Authenticate() du tout. Les VM Google Cloud, App Engine et d'autres environnements fournissent des "identifiants ambiants" utilisables, et gcloud auth application-default login les créera également.

Toutefois, nous vous recommandons d'utiliser ee.Authenticate() au début de tous les scripts pour maximiser la compatibilité. Sans paramètre auth_mode, il est conçu pour fonctionner dans la plupart des situations, mais suivez les détails ci-dessous si le mode par défaut ne fonctionne pas. Le mode par défaut est sélectionné comme suit :

colab si vous exécutez le notebook dans Google Colab
notebook si vous exécutez le code dans d'autres notebooks Jupyter que Colab
localhost si un navigateur Web est détecté et qu'aucun binaire gcloud n'est installé
gcloud, sinon. Pour ce mode, vous devez installer gcloud.

Guide et tableau de référence rapide

Ce guide de décision décrit les options possibles si le mode par défaut sélectionné par ee.Authenticate() ne fonctionne pas. Par exemple, si vous exécutez d'autres environnements de notebook, vous devrez peut-être spécifier explicitement notebook.

Environnement local :
- Local signifie que vous exécutez du code dans un shell Python ou un notebook Python sur la machine devant vous, ou plus précisément, sur la même machine que celle sur laquelle votre navigateur Web est exécuté. Cela inclut les situations de bureau à distance où Python et le navigateur se trouvent sur la même machine (à distance).
- L'utilisation de auth_mode=localhost est la plus simple et sera sélectionnée par défaut si gcloud n'est pas installé, mais votre script ne fonctionnera que dans les environnements locaux.
- auth_mode=gcloud et auth_mode=notebook sont également disponibles.
Environnement distant
- À distance signifie que votre navigateur se trouve sur une machine (locale), mais que votre code s'exécute ailleurs, par exemple sur un poste de travail distant ou un notebook Web.
- Si vous êtes dans Colab, utilisez auth_mode=colab. Si vous devez définir scopes pour appeler d'autres API, utilisez gcloud.
- Si vous pouvez installer gcloud sur la machine distante et sur votre machine locale, utilisez auth_mode=gcloud.
- Si vous pouvez utiliser un projet d'authentification (voir ci-dessous), utilisez auth_mode=notebook.
- Sinon, si vous ne pouvez pas utiliser de projet, installer gcloud, utiliser Colab ou utiliser un navigateur sur la même machine :
- Demandez (à nouveau) à un administrateur de créer des projets. Exemple :
  - Demandez à l'administrateur de configurer un projet pour vous (en tant que propriétaire, éditeur ou éditeur de configuration OAuth).
  - Vous pouvez également demander à l'administrateur de vous accorder les autorisations nécessaires pour créer un projet.

Ce tableau indique les combinaisons de fonctionnalités compatibles avec chaque mode.

	Pour un accès local ou à distance ?	Projet requis	Champs d'application définissables	CLI locale requise	Propriétaire du projet
`localhost`	local	O	O	N	N
`colab`	télécommande	O	N	N	N
`gcloud`	les deux	O	O	N	N
`notebook`	les deux	O	O	N	O

Identifiants pour les comptes de service et Compute Engine

ee.Initialize() utilisera les identifiants Earth Engine (que ee.Authenticate() stocke dans ~/.config/earthengine/credentials) ou récupérera les identifiants à partir de google.auth.default(), mais si nécessaire, vous pouvez transmettre un argument credentials= pour utiliser les identifiants d'un autre emplacement, en ignorant ces valeurs par défaut.

Si vous authentifiez du code Python qui s'exécutera sans surveillance, vous pouvez vous authentifier avec un compte de service plutôt qu'avec un compte utilisateur. Consultez cette documentation pour savoir comment utiliser les comptes de service avec Earth Engine. Les autres méthodes incluent authenticate_service_account dans le module d'authentification Colab et les méthodes décrites dans le guide Cloud sur l'authentification en tant que compte de service.

Si votre code s'exécute sur une VM Compute Engine, un compte de service par défaut est créé pour l'environnement, que ee.Initialize() utilisera par défaut. Vous devrez peut-être enregistrer le compte de service pour utiliser Earth Engine si le projet Cloud à partir duquel la VM a été démarrée n'est pas enregistré pour être utilisé avec Earth Engine (commercial ou non commercial).

Détails sur les modes

auth_mode=colab. ee.Authenticate() crée ou obtient les identifiants par défaut compatibles avec Colab en exécutant colab.auth.authenticate_user() si nécessaire. Les identifiants utilisent toujours le champ d'application cloud-platform et peuvent également être utilisés pour appeler d'autres API Cloud.

auth_mode=gcloud. Cela délègue l'authentification à l'outil gcloud et équivaut à exécuter gcloud auth application-default login avec les portées Earth Engine par défaut (earthengine, cloud-platform et drive) ou les portées de l'argument scopes. Le mode gcloud fonctionne dans les cas locaux et distants.

Instructions détaillées pour le mode gcloud (cas locaux et distants)

Vérifiez que gcloud est installé sur la machine locale.
- Dans un terminal, exécutez gcloud help. Si gcloud n'est pas installé, suivez ces instructions pour l'installer.
Terminal de la machine locale
- Dans un terminal, exécutez earthengine authenticate.
- Le résultat de la commande indique que gcloud est utilisé pour récupérer les identifiants.
- Une fenêtre de navigateur s'ouvre sur une page de sélection de compte. Si le navigateur ne s'ouvre pas automatiquement, cliquez sur l'URL.
Navigateur : sélection du compte
- Sélectionnez le compte à utiliser pour l'authentification.
Navigateur : écran de consentement
- Indiquez si vous êtes prêt à accorder les niveaux d'accès demandés, puis cliquez sur "Autoriser".
Navigateur : écran de confirmation
- Le navigateur affichera une page confirmant votre authentification, et la commande earthengine authenticate dans la fenêtre de votre terminal indiquera "Successfully saved authorization token" (Jeton d'autorisation enregistré).
- Dans les cas à distance, la page Web vous fournira un code à coller dans l'environnement Python.
Procédez à l'initialisation.

auth_mode=localhost. Il s'agit d'un flux semblable à gcloud pour les cas où gcloud n'est pas installé. Il effectue les mêmes étapes que gcloud, mais ne fonctionne que pour le cas local. Vous pouvez fournir un numéro de port Internet facultatif, par exemple localhost:8086, ou utiliser localhost:0 pour sélectionner automatiquement un port. Le port par défaut est 8085.

auth_mode=notebook. Il s'agit d'un mode à usage général conçu pour fonctionner dans des situations à distance où les lignes de commande locales ne sont pas disponibles. Vous êtes redirigé vers la page Notebook Authenticator, où vous devez choisir ou créer un "projet d'authentification". Pour en savoir plus, consultez les détails et le guide de dépannage ci-dessous. Le projet transmis à ee.Initialize() ne doit pas nécessairement correspondre à celui-ci. Vous pouvez conserver le même projet pour l'authentification tout en travaillant dans différents projets dans différents notebooks. Nous vous recommandons de transmettre un projet de manière explicite à ee.Initialize(), mais le projet d'authentification sera utilisé par défaut.

Instructions détaillées pour le mode Notebook

Navigateur : Notebook
1. Dans une cellule de code de notebook, exécutez le code suivant pour démarrer un flux d'authentification à l'aide du mode "notebook".
```
import ee
ee.Authenticate()
```
  Cliquez sur le lien dans la sortie de la cellule pour ouvrir une page Notebook Authenticator dans un nouvel onglet.
Navigateur : Notebook Authenticator
1. Vérifiez que le bon compte utilisateur est indiqué.
2. Sélectionnez un projet Google Cloud à utiliser pour l'authentification. Si vous devez créer un projet, nous vous recommandons d'utiliser la convention d'attribution de noms "ee-xyz", où xyz correspond à votre nom d'utilisateur Earth Engine habituel. (Si vous ne parvenez pas à sélectionner ni à créer un projet Cloud, consultez la section de dépannage ci-dessous.)
3. Cliquez sur "Générer le jeton".
Navigateur : sélection du compte
- Une page de sélection de compte s'affiche. Cliquez sur le compte utilisateur auquel vous souhaitez accorder l'accès depuis le notebook.
Navigateur : page d'avertissement
- Une page d'avertissement s'affiche, indiquant que Google n'a pas créé l'application (c'est-à-dire le code du notebook). Cliquez sur "Continuer" pour confirmer.
Navigateur : écran de consentement
- Indiquez si vous êtes prêt à accorder les niveaux d'accès demandés, puis cliquez sur Continuer.
Navigateur : écran du code d'autorisation
- Copier le code de validation de l'autorisation
Navigateur : Notebook
- Revenez à l'onglet du notebook et collez le code de validation dans la sortie de la cellule du notebook.
- Le résultat de la cellule doit indiquer "Successfully saved authorization token." (Jeton d'autorisation enregistré).
Procédez à l'initialisation.

Le mode Notebook comporte un paramètre quiet rarement utilisé : s'il est défini, il s'exécute de manière "non interactive" et ne vous invite pas à saisir le code d'authentification. Au lieu de cela, il donne une commande à exécuter pour enregistrer le code.

Projets d'authentification

Vous devez être propriétaire, éditeur ou éditeur de configuration OAuth du projet d'authentification utilisé en mode notebook. Dans de nombreux cas, en particulier dans les petites équipes, le projet d'authentification que vous utilisez sur la page Notebook Authenticator peut être le même que le projet principal que vous utilisez pour d'autres tâches.

En raison de problèmes de sécurité, la "configuration du client OAuth" dans le projet d'authentification est une configuration unique. Si vous ou d'autres utilisateurs avez configuré un client OAuth dans le projet pour d'autres raisons, il ne peut pas être supprimé et vous verrez un message d'erreur indiquant "Configuration du client OAuth2 incompatible". Vous devrez utiliser un autre projet pour l'authentification ou utiliser les modes colab, localhost ou gcloud ci-dessus.

Détails sur les portées

Les paramètres d'authentification par défaut d'Earth Engine incluent tous les niveaux d'accès disponibles. Vous pouvez donc ignorer cette section si les paramètres par défaut répondent à vos besoins.

Champs d'application Earth Engine : un champ d'application OAuth 2.0 définit et limite l'ensemble des ressources et des opérations auxquelles une application est autorisée à accéder au nom d'un utilisateur. Lorsque vous utilisez OAuth pour vous authentifier auprès d'Earth Engine, vous devez demander un ou plusieurs des champs d'application suivants :

https://www.googleapis.com/auth/earthengine : accès en lecture et en écriture aux ressources et aux composants Earth Engine. Nécessaire pour créer, modifier ou supprimer des composants, gérer les autorisations associées et exécuter des tâches d'exportation.
https://www.googleapis.com/auth/earthengine.readonly : accès en lecture seule aux composants Earth Engine.

Les deux niveaux d'accès permettent d'exécuter des scripts et d'effectuer des calculs (par exemple, évaluer des expressions ou afficher des visualisations de cartes).

Champs d'application Google Cloud et Drive : si vos requêtes ou scripts Earth Engine font référence à des données ou des composants externes, vos identifiants doivent également inclure les champs d'application appropriés pour ces services :

Cloud Storage (GCS) (lors de la lecture ou de l'écriture dans des buckets Cloud Storage, comme le chargement de fichiers GeoTIFF optimisés pour le cloud ou l'exportation des résultats des tâches) :
- 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) (lors de la lecture de tables ou de l'écriture d'exportations dans BigQuery) :
- https://www.googleapis.com/auth/bigquery
Google Drive (lors de l'accès aux données ou de leur exportation vers Google Drive) :
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/drive.readonly

Google Cloud propose également des niveaux d'accès étendus qui englobent tous les services Google Cloud :

Cloud Platform (accès étendu aux services Google Cloud, y compris Earth Engine, Cloud Storage et BigQuery ; notez que Google Drive est un service Workspace distinct et n'est pas couvert par ces niveaux d'accès) :
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud-platform.read-only

Champs d'application par défaut : les champs d'application par défaut configurés par l'éditeur de code Earth Engine et les bibliothèques clientes (telles que ee.Authenticate()) incluent tous les champs d'application suivants : earthengine, cloud-platform et drive (voir ci-dessus pour plus d'informations). Par conséquent, la personnalisation du champ d'application (par exemple, à l'aide du paramètre scopes dans ee.Authenticate(scopes=[...])) n'est nécessaire que si vous avez des contraintes de sécurité ou des règles organisationnelles spécifiques qui nécessitent de limiter les autorisations.

Dépannage

Que faire si je ne peux pas créer de projet Cloud ?

Certaines organisations contrôlent qui peut créer des projets Cloud. Si vous recevez une erreur sur la page Notebook Authenticator lorsque vous essayez de créer un projet, voici quelques solutions à essayer :

Essayez de créer un projet directement pour vérifier si vous disposez des autorisations nécessaires.
Contactez l'administrateur de votre organisation pour savoir quels processus sont disponibles pour créer un projet.
Créez un projet à partir d'un compte non professionnel, puis ajoutez le compte que vous utilisez au travail en tant que propriétaire du projet. Remarque : Certaines organisations ont des règles de sécurité qui empêchent l'accès aux clients OAuth à partir de projets externes.

Erreur : "L'API Earth Engine n'a jamais été utilisée dans le projet XXX ou a été désactivée"

Tout d'abord, assurez-vous d'avoir configuré un projet dans ee.Initialize() ou sur la ligne de commande (Earth Engine ne sera pas activé dans les projets par défaut fournis par Cloud et Colab). Ensuite, assurez-vous que l'API Earth Engine est activée dans votre projet.

Erreur : "Le projet présente une configuration de client OAuth2 incompatible"

Les projets Cloud ne peuvent comporter qu'une seule configuration de client OAuth2. Pour vérifier si un projet Cloud dispose d'une configuration de client OAuth2, consultez les ID client OAuth 2.0 sur la page "Identifiants". Vous devez sélectionner un autre projet Cloud dont la configuration compatible a déjà été définie par Notebook Authenticator, ou sélectionner ou créer un projet Cloud sans clients OAuth2. L'authentificateur configurera automatiquement ce projet. Malheureusement, le système OAuth ne permet pas aux utilisateurs de supprimer des configurations. Vous devez donc utiliser un autre projet. Il ne doit pas nécessairement être identique à celui utilisé pour d'autres tâches Earth Engine. Notez que cette erreur ne se produit pas en mode Colab.

Erreur : "gcloud failed. Veuillez vérifier si des erreurs sont présentes ci-dessus et installer gcloud si nécessaire."

Cette erreur peut se produire si gcloud n'est pas installé ou ne figure pas dans votre variable PATH. Cela peut également se produire si vous appelez ee.Authenticate(auth_mode='gcloud') depuis une cellule de code de notebook. Utilisez plutôt ee.Authenticate(), qui utilisera par défaut l'authentification en mode notebook. Si vous ne parvenez pas à créer un projet, consultez la solution ci-dessus.

Que faire si je n'ai pas accès à une machine locale pour installer gcloud ?

Si vous travaillez dans un environnement Web uniquement sans accès à un terminal local et que vous devez toujours utiliser un terminal à distance, vous pouvez toujours initialiser l'outil de ligne de commande en déclenchant le mode notebook en exécutant la commande earthengine authenticate --auth_mode=notebook.

Erreur 400 : redirect_uri_mismatch

Cette erreur peut se produire si vous vous authentifiez sur une machine distante sans accès à un navigateur Web. Essayez d'ajouter --quiet si vous exécutez earthengine authenticate à partir de la ligne de commande ou ee.Authenticate(quiet=True) si vous utilisez le client Python. Pour cela, vous devrez vous authentifier auprès de gcloud depuis une machine ayant accès à un navigateur Web.

Erreur : "Votre application s'authentifie à l'aide des identifiants par défaut de l'application locale. L'API earthengine.googleapis.com nécessite un projet de quota, qui n'est pas défini par défaut."

Cette erreur peut se produire lorsque Earth Engine ne parvient pas à déterminer votre ID de projet. Si les options de dépannage de Google Cloud ne fonctionnent pas, essayez d'exécuter earthengine set_project YOUR_PROJECT_ID ou gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Erreur : "Il manque des autorisations requises pour [Cloud Storage / BigQuery]"

Cette erreur se produit lorsqu'une requête Earth Engine accède à des ressources Cloud Storage ou BigQuery, mais que les identifiants utilisés pour initialiser Earth Engine n'incluent pas les niveaux d'accès requis pour ce service (ou le niveau d'accès cloud-platform, qui englobe tous les services Google Cloud). Cela se produit généralement si vous avez personnalisé le paramètre scopes lors de l'authentification (par exemple, en fournissant uniquement des autorisations Earth Engine à ee.Authenticate(scopes=[...])) ou si des identifiants existants ont été créés sans ces autorisations.

Vous pouvez résoudre ce problème de deux manières :

Se réauthentifier avec les niveaux d'accès par défaut : les identifiants par défaut pour Earth Engine incluent le niveau d'accès cloud-platform, qui englobe Cloud Storage et BigQuery. Réauthentifiez-vous en utilisant les paramètres par défaut :
- En Python : ee.Authenticate(force=True)
- Sur la ligne de commande : earthengine authenticate --force
Incluez les niveaux d'accès requis : si votre environnement nécessite de personnaliser les niveaux d'accès, assurez-vous que votre liste scopes inclut https://www.googleapis.com/auth/cloud-platform ou le niveau d'accès spécifique au service (par exemple, https://www.googleapis.com/auth/devstorage.full_control ou https://www.googleapis.com/auth/devstorage.read_only pour Cloud Storage, ou https://www.googleapis.com/auth/bigquery pour BigQuery).

Pour en savoir plus sur les niveaux d'accès disponibles, consultez Détails sur les niveaux d'accès.

Remarques techniques

Pour les plus techniques : la nécessité de ces différents mécanismes de création d'identifiants provient du besoin de transmettre des identifiants à un environnement connu et fiable. Voici une brève présentation des différents cas ci-dessus.

Il existait un mode paste qui vous permettait d'obtenir un jeton à coller n'importe où. Ce mode a été jugé trop risqué et n'est plus disponible.
colab : auth.authenticate_user() vous invite à partager des identifiants avec le client d'authentification "Colab", l'environnement du notebook lui-même. Ils sont ensuite disponibles via google.auth.default() et utilisés par ee.Initialize().
localhost : les identifiants sont transmis du navigateur à un port de votre ordinateur local. Dans ce cas, la sécurité de bout en bout dépend du fait que votre machine locale n'a pas été compromise. Le client d'authentification que vous verrez est "Earth Engine Authenticator".
gcloud : utilise le flux --launch-browser décrit dans la documentation de référence gcloud et --no-launch-browser si vous êtes sur une machine distante. Le client d'authentification utilisé est la bibliothèque Google Auth.
notebook : Nous créons un client d'authentification spécifiquement pour votre travail. Vous verrez votre adresse e-mail sur la page de consentement. Ce client est défini en mode "développement", qui est un cas particulier permettant d'utiliser les anciens jetons du mode Coller. Nous devons utiliser votre propre projet pour cela, car ces clients ne peuvent pas être partagés avec un grand nombre d'utilisateurs.