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 d'acheminer les requêtes via un projet Cloud à partir de votre 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 des projets Cloud pour l'authentification. Ils sont utilisés pour une utilisation non payante (sans frais, non commerciale) ainsi que pour une utilisation payante. Pour vous authentifier et initialiser, exécutez la commande suivante :

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

Le meilleur mode d'authentification pour votre environnement sera d'abord sélectionné, et vous serez invité à 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 des identifiants.

L'étape d'initialisation vérifie qu'il existe des identifiants valides, créés à partir de ee.Authenticate() ou 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 devez fournir un projet dont vous êtes propriétaire ou que vous êtes autorisé à utiliser. Consultez Configuration d'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, et vous pouvez utiliser l'argument --project pour définir le projet.

Vous pouvez également configurer un projet pour tous les appels futurs 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é en dernier recours.

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 transmet ces jetons qu'aux systèmes pouvant être sécurisés (voir les notes techniques ci-dessous).

En raison de la sensibilité au type de systèmes impliqués, il existe différentes manières de procéder en fonction de votre situation particulière. La plupart des options sont contrôlées par le paramètre auth_mode : soit en tant que ee.Authenticate(auth_mode=...), soit en tant que 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(). 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. Toutefois, suivez les instructions 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 code dans un notebook Google Colab
• notebook si vous l'exécutez dans d'autres notebooks Jupyter non-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 de référence rapide et tableau

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 le code dans d'autres environnements de notebook, vous devrez peut-être spécifier notebook explicitement.

• 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 (distante).
  • 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 une station de travail distante ou un notebook Web.
  • Si vous utilisez Colab, utilisez auth_mode=colab ou gcloud si vous devez définir scopes pour appeler d'autres API.
  • 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 :
  • Contactez (à nouveau) un administrateur pour 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 déploiement local ou à distance ?	Projet requis	Champs d'application configurables	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 de google.auth.default(). Toutefois, si nécessaire, vous pouvez transmettre un argument credentials= pour utiliser des identifiants provenant d'un autre emplacement, en contournant 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 ces documents pour savoir comment utiliser des comptes de service avec Earth Engine. D'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 via lequel la VM a été démarrée n'est pas enregistré pour être utilisé avec Earth Engine (commercial ou à usage 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 champs d'application Earth Engine par défaut (earthengine, cloud-platform et drive) ou les champs d'application de l'argument scopes. Le mode gcloud fonctionne dans les cas locaux et distants.

Instructions détaillées pour le mode gcloud (cas local et distant)

Les étapes suivantes décrivent comment s'authentifier à partir d'une ligne de commande sur une machine locale.

1. 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 installer gcloud.
2. Terminal de l'ordinateur local
   • 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.
3. Navigateur : sélection du compte
   • Sélectionnez le compte que vous souhaitez utiliser pour l'authentification.
4. Navigateur : écran de consentement
   • Indiquez si vous acceptez d'accorder les champs d'application demandés, puis cliquez sur "Autoriser".
5. Navigateur : écran de confirmation
   • Le navigateur affiche une page confirmant que vous êtes authentifié, et la commande earthengine authenticate dans la fenêtre de votre terminal indique "Jeton d'autorisation enregistré".
   • Dans de rares cas, la page Web vous fournira un code à coller dans l'environnement Python.
6. Procédez à l'initialisation.

auth_mode=localhost. Il s'agit d'un flux de type 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 distantes où les lignes de commande locales ne sont pas disponibles. Vous êtes redirigé vers la page de l'outil d'authentification Notebook, où vous devez choisir ou créer un "projet d'authentification". Pour en savoir plus, consultez 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. Il est recommandé de transmettre explicitement un projet à ee.Initialize(), mais le projet d'authentification sera utilisé par défaut.

Instructions détaillées pour le mode notebook

Les étapes suivantes décrivent comment s'authentifier à partir d'un notebook.

1. Navigateur : Notebook
   1. Dans une cellule de code du notebook, exécutez le code suivant pour lancer un flux d'authentification en mode "notebook".

      import ee
      ee.Authenticate()

      Cliquez sur le lien dans la sortie de la cellule pour ouvrir une page d'authentification du notebook dans un nouvel onglet.
2. Navigateur : Authentificateur de notebook
   1. Vérifiez que le bon compte utilisateur est listé.
   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 est votre nom d'utilisateur Earth Engine habituel. (Si vous ne parvenez pas à sélectionner ou à créer un projet Cloud, consultez la section de dépannage ci-dessous.)
   Vous devez disposer d'autorisations IAM suffisantes pour l'authentification, par exemple Propriétaire ou Éditeur sur le projet, ou d'un rôle prédéfini "Éditeur de configuration OAuth" en plus des autres rôles IAM attribués. Si un autre membre de votre équipe a déjà créé une configuration d'authentification sur ce projet, un avertissement supplémentaire s'affiche. Ne continuez que si le créateur est un collaborateur de confiance.
   3. Cliquez sur "Générer un jeton".
3. Browser: Account Selection
   • Une page de sélection de compte s'affiche. Cliquez sur le compte utilisateur auquel vous souhaitez accorder l'accès à partir du notebook.
4. 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.
5. Navigateur : écran de consentement
   • Indiquez si vous souhaitez accorder les champs d'application demandés, puis cliquez sur Continuer.
6. Navigateur : écran du code d'autorisation
   • Copiez le code de validation de l'autorisation.
7. 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é).
8. 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, ni n'attend que vous le fassiez. Au lieu de cela, il fournit une commande à exécuter pour enregistrer le code.

Projets d'authentification

Vous devez être propriétaire, éditeur ou éditeur de configuration OAuth sur le 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 de l'authentificateur de notebook peut être le même que le projet principal que vous utilisez pour d'autres tâches.

Pour des raisons de sécurité, la "configuration du client OAuth" sur le projet d'authentification est une configuration unique. Si vous ou d'autres utilisateurs avez configuré un client OAuth sur le projet pour d'autres raisons, il ne peut pas être supprimé et un message d'erreur s'affiche : "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 champs d'application

Les paramètres d'authentification par défaut d'Earth Engine incluent tous les champs d'application 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 éléments et ressources Earth Engine. Requis pour créer, modifier ou supprimer des éléments, gérer les autorisations d'accès aux éléments et exécuter des tâches d'exportation.
• https://www.googleapis.com/auth/earthengine.readonly : accès en lecture seule aux éléments Earth Engine.

Les deux champs d'application 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 éléments 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, par exemple pour charger des GeoTIFF optimisés pour le cloud (COG) ou exporter des résultats de 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 à des 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 champs d'application é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 champs d'application) :
  • 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 (comme ee.Authenticate()) incluent tous ces champs d'application : earthengine, cloud-platform et drive (voir plus haut pour plus de détails). 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é spécifiques ou des règles d'administration qui nécessitent de limiter les autorisations.

Dépannage

Que faire si je ne parviens pas à créer un projet Cloud ?

Certaines organisations contrôlent qui peut créer des projets Cloud. Si vous recevez une erreur sur la page de l'outil d'authentification du notebook lorsque vous essayez de créer un projet, voici quelques solutions à essayer :

1. Essayez de créer un projet directement pour vérifier si vous disposez des autorisations nécessaires.
2. Contactez l'administrateur de votre organisation pour connaître les procédures de création d'un projet.
3. Créez un projet à partir d'un compte non organisationnel, puis ajoutez le compte que vous utilisez pour le 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 (les projets par défaut fournis par Cloud et Colab n'auront pas Earth Engine activé). 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 avoir qu'une seule configuration de client OAuth2. Vous pouvez vérifier si un projet Cloud dispose d'une configuration de client OAuth2 en consultant 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é configurée par l'authentificateur de notebook, ou sélectionner ou créer un projet Cloud sans client 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 : "Échec de gcloud. Veuillez vérifier les erreurs 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 PATH. Cela peut également se produire si vous appelez ee.Authenticate(auth_mode='gcloud') à partir d'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 distant, 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 devez vous authentifier auprès de gcloud à partir d'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 lorsqu'Earth Engine ne parvient pas à déterminer l'ID de votre 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 : "Champs d'application requis manquants 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 champs d'application requis pour ce service (ou le champ d'application 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 ne fournissant que des champs d'application Earth Engine à ee.Authenticate(scopes=[...])) ou si des identifiants existants ont été créés sans ces champs d'application.

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

• Réauthentifier avec les champs d'application par défaut : les identifiants par défaut pour Earth Engine incluent le champ d'application cloud-platform, qui englobe à la fois Cloud Storage et BigQuery. Réauthentifiez-vous à l'aide des paramètres par défaut :
  • En Python : ee.Authenticate(force=True)
  • Sur la ligne de commande : earthengine authenticate --force
• Incluez les champs d'application requis : si votre environnement nécessite de personnaliser les champs d'application, assurez-vous que votre liste scopes inclut https://www.googleapis.com/auth/cloud-platform ou le champ d'application du service spécifique (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 champs d'application disponibles, consultez Détails sur les champs d'application.

Notes techniques

Pour les curieux : la nécessité de ces différents mécanismes de création d'identifiants découle de la nécessité de transmettre des identifiants à un environnement connu et de confiance. Voici une brève discussion sur les différents cas ci-dessus.

• Il existait auparavant un mode paste qui vous fournissait 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 vos identifiants avec le client d'authentification "Colab", l'environnement de notebook lui-même. Elles sont ensuite disponibles via google.auth.default() et utilisées 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 ordinateur local n'a pas été compromis. 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 de gcloud et --no-launch-browser si vous êtes sur une machine distante. Le client d'authentification utilisé est "Google Auth Library".
• notebook : nous créons un client d'authentification spécifiquement pour votre travail. Votre adresse e-mail s'affichera sur la page de consentement. Ce client est défini en mode "développement", un cas particulier qui autorise les anciens jetons du mode collage. Nous devons utiliser votre propre projet, car ces clients ne peuvent pas être partagés avec un grand nombre d'utilisateurs.