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 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 illustré 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 Cloud Projects pour s'authentifier. Ils sont utilisés pour une utilisation non rémunérée (sans frais, non commerciale) et payante. Pour authentifier et initialiser, exécutez

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

Le meilleur mode d'authentification pour votre environnement est alors sélectionné, et vous êtes 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 que des identifiants valides existent, créés à partir de ee.Authenticate() ou préexistants en tant qu'identifiants par défaut Google. 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 le propriétaire ou dont vous disposez des autorisations d'utilisation. Consultez la section Configuration du 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 invocations de ligne de commande seront initialisées à 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é 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 transmet ces jetons qu'à des systèmes pouvant être sécurisés. Pour en savoir plus, consultez les notes techniques ci-dessous.

En raison de la sensibilité du type de systèmes concerné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: en tant que ee.Authenticate(auth_mode=...) ou 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ée également.

Toutefois, ee.Authenticate() est recommandé 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 l'exécution se fait dans un notebook Google Colab
• notebook si vous exécutez le notebook dans d'autres notebooks Jupyter autres 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 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 s'exécute. 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é. Toutefois, 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 à distance ou un notebook Web.
  • Si vous utilisez Colab, utilisez auth_mode=colab. Si vous devez définir scopes pour appeler d'autres API, utilisez gcloud.
  • Si vous pouvez installer gcloud à la fois 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 un projet, installer gcloud, utiliser Colab ou utiliser un navigateur sur la même machine:
  • Contactez à nouveau un administrateur pour créer des projets. Exemple :
    • Demander à l'administrateur de configurer un projet pour vous (en tant que propriétaire, éditeur ou éditeur de la 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.

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(). Toutefois, si nécessaire, vous pouvez transmettre un argument credentials= pour utiliser des identifiants provenant d'ailleurs, en contournant ces valeurs par défaut.

Si vous authentifiez du code Python qui s'exécute sans surveillance, vous pouvez vous authentifier avec un compte de service plutôt qu'avec un compte utilisateur. Pour savoir comment utiliser des comptes de service avec Earth Engine, consultez ces documents. Parmi les autres méthodes, citons 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 par lequel la VM a été démarrée n'est pas enregistré pour être utilisé avec Earth Engine (commercial ou non commercial).

Informations 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. Cette opération 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 à la fois en local et à distance.

auth_mode=localhost. Il s'agit d'un flux semblable à gcloud lorsque 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 polyvalent conçu pour fonctionner dans des situations à distance où les lignes de commande locales ne sont pas disponibles. Vous êtes alors redirigé vers la page de l'Authentificateur Notebook, 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 lorsque vous travaillez sur 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.

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 n'invite pas l'utilisateur à saisir le code d'authentification ni ne l'attend. À la place, il fournit une commande à exécuter pour enregistrer le code.

Projets d'authentification

Vous devez être propriétaire, éditeur ou éditeur de la 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 de l'Authentificateur 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" du projet d'authentification est une configuration ponctuelle. 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 le message d'erreur "Configuration du client OAuth2 incompatible" s'affiche. Vous devrez utiliser un autre projet pour l'authentification ou les modes colab, localhost ou gcloud ci-dessus.

Dépannage

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

Certaines organisations contrôlent les personnes autorisées à créer des projets Cloud. Si vous recevez une erreur sur la page de l'authentificateur Notebook lorsque vous essayez de créer un projet, essayez les solutions suivantes:

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 processus disponibles pour créer un projet.
3. Créez un projet à partir d'un compte non professionnel, puis ajoutez le compte que vous utilisez pour le travail en tant que propriétaire du projet. Remarque: Certaines organisations disposent de 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 est 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 ne seront pas compatibles avec Earth Engine). 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. Pour vérifier si un projet Cloud dispose d'une configuration client OAuth2, vérifiez les ID client OAuth 2.0 sur la page "Identifiants". Vous devez sélectionner un autre projet Cloud dont la configuration compatible est déjà configurée par l'Authentificateur Notebook, 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 rechercher les erreurs ci-dessus et installer gcloud si nécessaire."

Cette erreur peut se produire si gcloud n'est pas installé ou n'est pas défini 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 utilise 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 s'afficher 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 ce faire, vous devez vous authentifier avec gcloud à partir d'un ordinateur ayant accès à un navigateur Web.

Erreur: "Votre application s'authentifie à l'aide des identifiants par défaut de l'application locaux. 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 l'ID de votre projet. Si les options de dépannage 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.

Remarques techniques

Pour les curieux d'ordre technique: la nécessité de ces différents mécanismes de création d'identifiants vient de la nécessité de transmettre des identifiants à un environnement connu et fiable. Voici un bref récapitulatif des différents cas ci-dessus.

• Il existait un mode paste qui vous donnait 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 de 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 "Authentificateur Earth Engine".
• gcloud: utilise le flux --launch-browser décrit dans la documentation de référence gcloud et --no-launch-browser si vous vous trouvez 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. Votre adresse e-mail s'affiche sur la page de consentement. Ce client est défini en mode "développement", ce qui est un cas particulier qui permet les anciens jetons de mode de collage. Nous devons utiliser votre propre projet pour cela, car ces clients ne peuvent pas être partagés avec un grand nombre d'utilisateurs.