API Earth Engine dans les applications Web côté client

Ce guide explique comment créer une page Web avec une carte interactive affichant les résultats calculés à la volée dans Earth Engine. Il est destiné aux personnes ayant un niveau de connaissance débutant ou intermédiaire en HTML, CSS et JavaScript.

Vous trouverez ci-dessous une démonstration de la carte interactive que vous allez créer dans ce guide. Elle montre la pente du terrain du Grand Canyon calculée dans Earth Engine, représentée par différentes nuances de gris. Vous pouvez faire un panoramique et un zoom sur la carte pour calculer et afficher les résultats d'autres zones. Notez que vous devez vous connecter à la démonstration.

L'approche décrite ici est généralement utilisée lors de la création d'applications monopages (SPA). Dans une SPA, l'application entière est utilisable dans un navigateur Web sans que la page ne soit rechargée à partir du serveur. Par conséquent, ces applications ne nécessitent pas le développement ni l'hébergement d'un composant personnalisé côté serveur.

Étant donné que le code de l'application sera exécuté dans le navigateur Web de l'utilisateur (également appelé exécution côté client), les développeurs ne doivent pas intégrer d'identifiants sensibles tels que les clés privées de compte de service directement dans l'application. Les utilisateurs de l'application doivent plutôt s'authentifier à l'aide de leurs propres comptes enregistrés pour accéder à Earth Engine.

Ce guide va vous permettre d'aborder plusieurs thèmes.

  1. Afficher un bouton permettant aux utilisateurs de se connecter à l'aide de leur compte Earth Engine.
  2. Définir une analyse de base dans Earth Engine.
  3. Intégrer une carte interactive pour afficher les résultats à l'aide de l'API Maps JavaScript.

Prérequis

Configurer votre projet Cloud

  1. Avant de commencer, suivez les instructions de la section Configurer votre projet Cloud compatible avec Earth Engine. Notez l'ID client obtenu dans la section "Configurer OAuth 2.0". Étant donné que votre application permettra aux utilisateurs de se connecter avec leur propre compte Google, vous pouvez ignorer la section "Créer et enregistrer un compte de service".
  2. Activez l'API Maps JavaScript pour votre projet.

Obtenir une clé API Google Maps

Consultez la section Obtenir la clé API de la documentation de l'API Maps JavaScript pour découvrir comment obtenir une clé API vous permettant d' utiliser l'API Maps JavaScript dans votre application Web.

Nous vous recommandons vivement de suivre les instructions de la section Restreindre la clé API pour vous assurer que seules les requêtes autorisées sont effectuées avec votre clé API.

Créer votre application

Étape 1 : Créer une page HTML

Pour commencer, définissez une page Web HTML de base comme suit :

<!DOCTYPE html>
<html>
  <head>
    <style>
      /* Set the size of the div element that contains the map. */
      #map-container {
        height: 400px;
        width: 100%;
        background-color: #eee;
      }
    </style>
  </head>
  <body>
    <!-- The "Sign in with Google" button, initially hidden. -->
    <input
      id="g-sign-in"
      type="image"
      src="https://developers.google.com/identity/images/btn_google_signin_light_normal_web.png"
      onclick="onSignInButtonClick()"
      alt="Sign in with Google"
      hidden
    />

    <!-- Element where map will be added. -->
    <div id="map-container"></div>
    <script>
      // JavaScript code goes here.
    </script>
  </body>
</html>

Ce code HTML de base effectue plusieurs opérations :

  • Utilise des styles CSS pour définir la taille et la couleur d'arrière-plan de la carte affichée lors de l'initialisation.
  • Définit un bouton "Se connecter avec Google" qui appelle une fonction onSignInButtonClick() lorsque l'utilisateur clique dessus. Cette fonction sera définie en JavaScript dans les sections suivantes.
  • Définit un élément vide qui contiendra la carte une fois qu'elle sera initialisée.
  • Ajoute un bloc <script> vide pour contenir le code JavaScript défini ci-dessous.

Étape 2 : Définir des comportements en JavaScript

Dans les étapes suivantes, le code JavaScript peut être placé directement à l'intérieur de la balise <script>.

Définir un rappel pour configurer les API et la carte

Définissez une fonction à exécuter une fois l'utilisateur connecté. L'API Earth Engine ne peut être initialisée et appelée qu'une fois l'utilisateur authentifié. Nous y reviendrons bientôt.

Cet exemple initialise les API Earth Engine et Maps, crée une source de tuiles qui calcule la pente du terrain à la demande et ajoute la source de tuiles à la carte en tant que superposition affichée par l'API Maps JavaScript :

// Initializes Maps JavaScript API and Earth Engine API, instructing the map
// to pull tiles from Earth Engine and to overlay them on the map.
function setUpMap() {
  // Hide the sign-in button.
  document.getElementById("g-sign-in").setAttribute("hidden", "true");

  // Initialize the Earth Engine API. Must be called once before using the API.
  ee.initialize(null, null, null, null, null, 'my-project');

  // Get a reference to the placeholder DOM element to contain the map.
  const mapContainerEl = document.getElementById("map-container");

  // Create an interactive map inside the placeholder DOM element.
  const embeddedMap = new google.maps.Map(mapContainerEl, {
    // Pan and zoom initial map viewport to Grand Canyon.
    center: {lng: -112.8598, lat: 36.2841},
    zoom: 9,
  });

  // Obtain reference to digital elevation model and apply algorithm to
  // calculate slope.
  const srtm = ee.Image("CGIAR/SRTM90_V4");
  const slope = ee.Terrain.slope(srtm);

  // Create a new tile source to fetch visible tiles on demand and display them
  // on the map.
  const mapId = slope.getMap({min: 0, max: 60});
  const tileSource = new ee.layers.EarthEngineTileSource(mapId);
  const overlay = new ee.layers.ImageOverlay(tileSource);
  embeddedMap.overlayMapTypes.push(overlay);
}

Définir un gestionnaire pour les clics sur le bouton de connexion

Ensuite, ajoutez une fonction pour afficher la fenêtre pop-up de connexion lorsque l'utilisateur clique sur le bouton de connexion. Si l'opération réussit, la méthode setUp() est appelée.

// Handles clicks on the sign-in button.
function onSignInButtonClick() {
  // Display popup allowing the user to sign in with their Google account and to
  // grant appropriate permissions to the app.
  ee.data.authenticateViaPopup(setUpMap);
}

Ce rappel est associé au bouton dans le code HTML ci-dessus via son attribut onclick. Notez que dans cet exemple, le bouton de connexion est initialement masqué lorsque la page est chargée. Dans la section suivante, nous vérifierons si l'utilisateur est connecté avant d'afficher le bouton.

Définir le point d'entrée principal

Nous allons maintenant définir le code de niveau supérieur à exécuter en premier lorsque la page est chargée. Il utilise la fonction d'assistance d'authentification intégrée d'Earth Engine ee.data.authenticateViaPopup() pour vérifier si l'utilisateur est déjà connecté. Si l'utilisateur est connecté, la fonction demande les autorisations appropriées et appelle setUp() pour initialiser les API Earth Engine et Maps si l'opération réussit.

Si l'utilisateur n'est pas connecté, le bouton de connexion s'affiche. L'utilisateur peut ensuite cliquer sur le bouton pour déclencher onSignInButtonClick(), qui affiche à son tour la fenêtre pop-up et appelle setUp() pour lancer le processus.

// If the user is signed in, display a popup requesting permissions needed to
// run the app, otherwise show the sign-in button.
ee.data.authenticateViaOauth(
  // The OAuth Client ID defined above.
  CLIENT_ID,
  // Callback invoked immediately when user is already signed in.
  setUpMap,
  // Show authentication errors in a popup.
  alert,
  // Request permission to only read and compute Earth Engine data on behalf of
  // user.
  /* extraScopes = */ ['https://www.googleapis.com/auth/earthengine.readonly'],
  // Show sign-in button if reusing existing credentials fails.
  () => document.getElementById("g-sign-in").removeAttribute("hidden"),
  // Don't require ability to write and access Cloud Platform on behalf of the
  // user.
  /* opt_suppressDefaultScopes = */ true
);

Essayez par vous-même

Vous trouverez ci-dessous la solution complète présentée dans ce guide. En haut à droite de l'exemple de code se trouvent trois boutons. Cliquez sur le bouton le plus à gauche pour ouvrir l'exemple dans JSFiddle.

Remplacez YOUR_API_KEY et YOUR_CLIENT_ID par la clé API Google Maps et l'ID client OAuth obtenus dans Prérequis (vous pouvez cliquer sur ces espaces réservés dans le code ci-dessous pour les insérer automatiquement). Remplacez également 'my-project' par l'ID de votre projet Google Cloud.

<!-- Load Maps JavaScript API. For production apps, append you own ?key=YOUR_API_KEY. -->

<script src="https://maps.googleapis.com/maps/api/js?key="></script>
<script src="https://ajax.googleapis.com/ajax/libs/earthengine/0.1.365/earthengine-api.min.js"></script>

<!-- The "Sign in with Google" button, initially hidden. -->
<input
  id="g-sign-in"
  type="image"
  src="https://developers.google.com/identity/images/btn_google_signin_light_normal_web.png"
  onclick="onSignInButtonClick()"
  alt="Sign in with Google"
  hidden
/>

<!-- Element where map will be added. -->
<div id="map-container"></div>
 
/* Set the size of the div element that contains the map. */
  #map-container {
    height: 400px;
    width: 100%;
    background-color: #eee;
  }
 
// The OAuth Client ID from the Google Developers Console.
// REMINDER: Be sure to add a valid ID here!
const CLIENT_ID = "";

// Initializes Maps JavaScript API and Earth Engine API, instructing the map
// to pull tiles from Earth Engine and to overlay them on the map.
function setUpMap() {
  // Hide the sign-in button.
  document.getElementById("g-sign-in").setAttribute("hidden", "true");

  // Initialize the Earth Engine API. Must be called once before using the API.
  ee.initialize(null, null, null, null, null, 'my-project');

  // Get a reference to the placeholder DOM element to contain the map.
  const mapContainerEl = document.getElementById("map-container");

  // Create an interactive map inside the placeholder DOM element.
  const embeddedMap = new google.maps.Map(mapContainerEl, {
    // Pan and zoom initial map viewport to Grand Canyon.
    center: {lng: -112.8598, lat: 36.2841},
    zoom: 9,
  });

  // Obtain reference to digital elevation model and apply algorithm to
  // calculate slope.
  const srtm = ee.Image("CGIAR/SRTM90_V4");
  const slope = ee.Terrain.slope(srtm);

  // Create a new tile source to fetch visible tiles on demand and display them
  // on the map.
  const mapId = slope.getMap({min: 0, max: 60});
  const tileSource = new ee.layers.EarthEngineTileSource(mapId);
  const overlay = new ee.layers.ImageOverlay(tileSource);
  embeddedMap.overlayMapTypes.push(overlay);
}

// Handles clicks on the sign-in button.
function onSignInButtonClick() {
  // Display popup allowing the user to sign in with their Google account and to
  // grant appropriate permissions to the app.
  ee.data.authenticateViaPopup(setUpMap);
}

// If the user is signed in, display a popup requesting permissions needed to
// run the app, otherwise show the sign-in button.
ee.data.authenticateViaOauth(
  // The OAuth Client ID defined above.
  CLIENT_ID,
  // Callback invoked immediately when user is already signed in.
  setUpMap,
  // Show authentication errors in a popup.
  alert,
  // Request permission to only read and compute Earth Engine data on behalf of
  // user.
  /* extraScopes = */ ['https://www.googleapis.com/auth/earthengine.readonly'],
  // Show sign-in button if reusing existing credentials fails.
  () => document.getElementById("g-sign-in").removeAttribute("hidden"),
  // Don't require ability to write and access Cloud Platform on behalf of the
  // user.
  /* opt_suppressDefaultScopes = */ true
);
 
<!DOCTYPE html>
<html>
  <head>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/earthengine/0.1.365/earthengine-api.min.js"></script>
    <style>
      /* Set the size of the div element that contains the map. */
      #map-container {
        height: 400px;
        width: 100%;
        background-color: #eee;
      }
    </style>
  </head>
  <body>
    <!-- The "Sign in with Google" button, initially hidden. -->
    <input
      id="g-sign-in"
      type="image"
      src="https://developers.google.com/identity/images/btn_google_signin_light_normal_web.png"
      onclick="onSignInButtonClick()"
      alt="Sign in with Google"
      hidden
    />

    <!-- Element where map will be added. -->
    <div id="map-container"></div>
    <script>
      // The OAuth Client ID from the Google Developers Console.
      const CLIENT_ID = "YOUR_CLIENT_ID";
      
      // Initializes Maps JavaScript API and Earth Engine API, instructing the map
      // to pull tiles from Earth Engine and to overlay them on the map.
      function setUpMap() {
        // Hide the sign-in button.
        document.getElementById("g-sign-in").setAttribute("hidden", "true");
      
        // Initialize the Earth Engine API. Must be called once before using the API.
        ee.initialize(null, null, null, null, null, 'my-project');
      
        // Get a reference to the placeholder DOM element to contain the map.
        const mapContainerEl = document.getElementById("map-container");
      
        // Create an interactive map inside the placeholder DOM element.
        const embeddedMap = new google.maps.Map(mapContainerEl, {
          // Pan and zoom initial map viewport to Grand Canyon.
          center: {lng: -112.8598, lat: 36.2841},
          zoom: 9,
        });
      
        // Obtain reference to digital elevation model and apply algorithm to
        // calculate slope.
        const srtm = ee.Image("CGIAR/SRTM90_V4");
        const slope = ee.Terrain.slope(srtm);
      
        // Create a new tile source to fetch visible tiles on demand and display them
        // on the map.
        const mapId = slope.getMap({min: 0, max: 60});
        const tileSource = new ee.layers.EarthEngineTileSource(mapId);
        const overlay = new ee.layers.ImageOverlay(tileSource);
        embeddedMap.overlayMapTypes.push(overlay);
      }
      
      // Handles clicks on the sign-in button.
      function onSignInButtonClick() {
        // Display popup allowing the user to sign in with their Google account and to
        // grant appropriate permissions to the app.
        ee.data.authenticateViaPopup(setUpMap);
      }
      
      // If the user is signed in, display a popup requesting permissions needed to
      // run the app, otherwise show the sign-in button.
      ee.data.authenticateViaOauth(
        // The OAuth Client ID defined above.
        CLIENT_ID,
        // Callback invoked immediately when user is already signed in.
        setUpMap,
        // Show authentication errors in a popup.
        alert,
        // Request permission to only read and compute Earth Engine data on behalf of
        // user.
        /* extraScopes = */ ['https://www.googleapis.com/auth/earthengine.readonly'],
        // Show sign-in button if reusing existing credentials fails.
        () => document.getElementById("g-sign-in").removeAttribute("hidden"),
        // Don't require ability to write and access Cloud Platform on behalf of the
        // user.
        /* opt_suppressDefaultScopes = */ true
      );
    </script>
  </body>
</html>