واجهة برمجة التطبيقات Earth Engine في تطبيقات الويب من جهة العميل

يشرح هذا الدليل كيفية إنشاء صفحة ويب تعرض خريطة تفاعلية تعرض نتائج محسوبة في الوقت الفعلي في Earth Engine. وهو مناسب للمستخدمين الذين لديهم معرفة أساسية أو متوسطة بلغات HTML وCSS وJavaScript.

في ما يلي عرض توضيحي للخريطة التفاعلية التي ستنشئها في هذا الدليل. تعرض الخريطة انحدار التضاريس في "الوادي الكبير" المحسوب في Earth Engine، والذي يظهر بدرجات متفاوتة من اللون الرمادي. يمكنك تحريك الخريطة وتكبيرها وتصغيرها لحساب النتائج وعرضها لمناطق إضافية. يُرجى العِلم أنّه يجب تسجيل الدخول إلى العرض التوضيحي.

تُستخدم الطريقة الموضّحة هنا عادةً عند إنشاء تطبيقات صفحة واحدة (SPAs). في تطبيق صفحة واحدة، يمكن استخدام التطبيق بأكمله في متصفّح ويب بدون إعادة تحميل الصفحة من الخادم. وبالتالي، لا تتطلّب هذه التطبيقات تطوير مكوّن مخصّص من جهة الخادم واستضافته.

بما أنّ رمز التطبيق سيتم تشغيله في متصفّح الويب الخاص بالمستخدم (المعروف أيضًا باسم التنفيذ من جهة العميل)، يجب ألا يضمّن المطوّرون بيانات الاعتماد الحسّاسة، مثل المفاتيح الخاصة لحسابات الخدمة، مباشرةً في التطبيق. بدلاً من ذلك، يجب أن يصادق مستخدمو التطبيق باستخدام حساباتهم الخاصة التي تم تسجيلها للوصول إلى Earth Engine.

في هذا الدليل، ستتعرّف على ما يلي:

  1. عرض زرّ يسمح للمستخدمين بتسجيل الدخول باستخدام حساباتهم على Earth Engine
  2. تحديد تحليل أساسي في Earth Engine
  3. تضمين خريطة تفاعلية لعرض النتائج باستخدام Maps JavaScript API

المتطلبات الأساسية

إعداد مشروعك على Google Cloud

  1. قبل البدء، اتّبِع التعليمات الواردة في مقالة إعداد مشروعك على Google Cloud المفعَّل فيه Earth Engine. دوِّن رقم تعريف العميل الذي تم الحصول عليه في قسم "إعداد OAuth 2.0". بما أنّ تطبيقك سيسمح للمستخدمين بتسجيل الدخول باستخدام حساباتهم على Google، يمكنك تخطّي قسم "إنشاء حساب خدمة وتسجيله".
  2. فعِّل Maps JavaScript API لمشروعك.

الحصول على مفتاح Maps API

راجِع مقالة الحصول على مفتاح واجهة برمجة التطبيقات في مستندات Maps JavaScript API للتعرّف على كيفية الحصول على مفتاح واجهة برمجة تطبيقات يسمح لك بـ استخدام Maps JavaScript API في تطبيق الويب.

ننصحك بشدة أيضًا باتّباع التعليمات الواردة في القسم تقييد مفتاح واجهة برمجة التطبيقات لضمان عدم إجراء سوى الطلبات المفوّضة باستخدام مفتاح واجهة برمجة التطبيقات.

إنشاء تطبيقك

الخطوة 1. إنشاء صفحة HTML

للبدء، حدِّد صفحة ويب أساسية بتنسيق HTML على النحو التالي:

<!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>

ينفّذ هذا الرمز الأساسي بتنسيق HTML عدة إجراءات:

  • يستخدم أنماط CSS لتحديد حجم الخريطة ولونها في الخلفية اللذين يظهران أثناء التهيئة.
  • يحدّد زر "تسجيل الدخول باستخدام حساب Google" يستدعي الدالة onSignInButtonClick() عند النقر عليه. سيتم تحديد هذه الدالة في JavaScript في الأقسام التالية.
  • يحدّد عنصرًا فارغًا سيحتوي على الخريطة بعد تهيئتها.
  • يضيف كتلة <script> فارغة لتضمين رمز JavaScript المحدّد أدناه.

الخطوة 2. تحديد السلوكيات في JavaScript

في الخطوات التالية، يمكن وضع رمز JavaScript مباشرةً داخل علامة الـ <script>.

تحديد معاودة الاتصال لإعداد واجهات برمجة التطبيقات والخريطة

حدِّد دالة لتنفيذ العمل بعد تسجيل دخول المستخدم. لا يمكن تهيئة Earth Engine API واستدعاؤه إلا بعد مصادقة المستخدم. سنقدّم المزيد من المعلومات حول ذلك قريبًا.

يهيئ هذا المثال واجهتَي برمجة التطبيقات Earth Engine وMaps، وينشئ مصدر مربّعات يحسب انحدار التضاريس عند الطلب، ويضيف مصدر المربّعات إلى الخريطة كطبقة تراكب تعرضها Maps JavaScript API:

// 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);
}

تحديد معالج للنقر على زر تسجيل الدخول

بعد ذلك، أضِف دالة لعرض النافذة المنبثقة لتسجيل الدخول عند النقر على زر تسجيل الدخول. إذا نجحت العملية، يتم استدعاء الطريقة setUp().

// 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);
}

ترتبط معاودة الاتصال هذه بالزر في رمز HTML أعلاه من خلال السمة onclick. يُرجى العِلم أنّه في هذا المثال، يتم إخفاء زر تسجيل الدخول في البداية عند تحميل الصفحة. في القسم التالي، سنتحقّق مما إذا كان المستخدم قد سجّل الدخول قبل عرض الزر.

تحديد نقطة الدخول الرئيسية

الآن، لنحدّد الرمز الأعلى مستوى الذي سيتم تنفيذه أولاً عند تحميل الصفحة. يستخدم هذا الرمز دالة مساعِدة مدمجة للمصادقة في Earth Engine، وهي ee.data.authenticateViaPopup() ، للتحقّق مما إذا كان المستخدم قد سجّل الدخول من قبل. إذا كان المستخدم قد سجّل الدخول، تطلب الدالة الأذونات المناسبة، وتستدعي setUp() لتهيئة واجهتَي برمجة التطبيقات Earth Engine وMaps إذا نجحت العملية.

إذا لم يكن المستخدم قد سجّل الدخول، يتم عرض زر تسجيل الدخول. يمكن للمستخدم بعد ذلك النقر على الزر لتشغيل onSignInButtonClick()، ما يؤدي بدوره إلى عرض النافذة المنبثقة واستدعاء setUp() لبدء العملية.

// 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
);

تجربة الميزة بنفسك

في ما يلي الحل الكامل المقدَّم في هذا الدليل. في أعلى يسار نموذج الرمز، تظهر ثلاثة أزرار. انقر على الزر الأقصى يسارًا لفتح النموذج في JSFiddle.

استبدِل YOUR_API_KEY وYOUR_CLIENT_ID بمفتاح Maps API ورقم تعريف عميل OAuth اللذين تم الحصول عليهما في المتطلبات الأساسية (يمكنك النقر على هذين العنصرَين النائبَين في الرمز أدناه لإدراجهما تلقائيًا). استبدِل أيضًا 'my-project' برقم تعريف مشروعك على 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>