API موتور زمین در برنامه‌های وب سمت کلاینت

این راهنما به شما نشان می‌دهد که چگونه یک صفحه وب با نقشه تعاملی بسازید که نتایج محاسبه شده در لحظه را در Earth Engine نمایش دهد. این راهنما برای افرادی که دانش مبتدی یا متوسطی از HTML، CSS و جاوا اسکریپت دارند، مناسب است.

در زیر نسخه آزمایشی نقشه تعاملی که در این راهنما ایجاد خواهید کرد، آمده است. این نقشه، شیب زمین گرند کنیون محاسبه شده در Earth Engine را نشان می‌دهد که با سایه‌های مختلف خاکستری نمایش داده شده است. می‌توانید نقشه را برای محاسبه و نمایش نتایج مناطق اضافی، بزرگ‌نمایی و حرکت دهید. توجه داشته باشید که باید به نسخه آزمایشی وارد شوید.

رویکردی که در اینجا توضیح داده شده است معمولاً هنگام ایجاد برنامه‌های تک صفحه‌ای (SPA) استفاده می‌شود. در یک SPA، کل برنامه در یک مرورگر وب قابل استفاده است بدون اینکه صفحه از سرور مجدداً بارگذاری شود. به همین دلیل، این برنامه‌ها نیازی به توسعه و میزبانی یک جزء سفارشی سمت سرور ندارند.

از آنجایی که کد برنامه در مرورگر وب کاربر اجرا می‌شود (که به عنوان اجرای سمت کلاینت نیز شناخته می‌شود)، توسعه‌دهندگان نباید اطلاعات حساس مانند کلیدهای خصوصی حساب سرویس را مستقیماً در برنامه جاسازی کنند. در عوض، کاربران برنامه باید با استفاده از حساب‌های خود که برای دسترسی به Earth Engine ثبت شده‌اند، احراز هویت کنند.

در این راهنما، شما یاد خواهید گرفت که چگونه:

  1. دکمه‌ای را نمایش دهید که به کاربران اجازه می‌دهد با استفاده از حساب Earth Engine خود وارد سیستم شوند.
  2. یک تحلیل پایه در Earth Engine تعریف کنید.
  3. با استفاده از API جاوا اسکریپت Maps، یک نقشه تعاملی برای نمایش نتایج جاسازی کنید.

پیش‌نیازها

پروژه ابری خود را راه‌اندازی کنید

  1. قبل از شروع، دستورالعمل‌های موجود در بخش «راه‌اندازی پروژه ابری با قابلیت فعال‌سازی Earth Engine» را دنبال کنید. شناسه کلاینت (Client ID) دریافت شده در بخش «راه‌اندازی OAuth 2.0» را یادداشت کنید. از آنجایی که برنامه شما به کاربران اجازه می‌دهد با حساب گوگل خود وارد سیستم شوند، می‌توانید از بخش «ایجاد و ثبت حساب کاربری سرویس» صرف نظر کنید.
  2. API جاوا اسکریپت Maps را برای پروژه خود فعال کنید .

دریافت کلید API نقشه‌ها

برای یادگیری نحوه‌ی دریافت کلید API که به شما امکان استفاده از API جاوا اسکریپت Maps را در برنامه‌ی وب شما می‌دهد، به بخش دریافت کلید API در مستندات Maps JavaScript API مراجعه کنید.

اکیداً توصیه می‌شود که دستورالعمل‌های بخش محدود کردن کلید API را نیز دنبال کنید تا مطمئن شوید که فقط درخواست‌های مجاز با کلید API شما ارسال می‌شوند.

برنامه خود را ایجاد کنید

مرحله ۱. ایجاد یک صفحه 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 برای تعریف اندازه و رنگ پس‌زمینه نقشه نشان داده شده هنگام مقداردهی اولیه استفاده می‌کند.
  • یک دکمه‌ی "ورود با گوگل" تعریف می‌کند که هنگام کلیک، تابع onSignInButtonClick() را فراخوانی می‌کند. این تابع در بخش‌های بعدی در جاوا اسکریپت تعریف خواهد شد.
  • یک عنصر خالی تعریف می‌کند که پس از مقداردهی اولیه، نقشه را در خود جای خواهد داد.
  • یک بلوک خالی <script> برای نگهداری کد جاوا اسکریپت تعریف شده در زیر اضافه می‌کند.

مرحله ۲. تعریف رفتارها در جاوا اسکریپت

در مراحل بعدی، کد جاوا اسکریپت می‌تواند مستقیماً درون تگ <script> قرار گیرد.

تعریف فراخوانی برای تنظیم APIها و نقشه

تابعی را تعریف کنید که پس از ورود کاربر، کار خود را انجام دهد. API موتور زمین فقط پس از احراز هویت کاربر می‌تواند مقداردهی اولیه و فراخوانی شود. به زودی در این مورد بیشتر صحبت خواهیم کرد.

این مثال موتور زمین و APIهای نقشه‌ها را مقداردهی اولیه می‌کند، یک منبع کاشی ایجاد می‌کند که شیب زمین را بر اساس تقاضا محاسبه می‌کند و منبع کاشی را به عنوان یک پوشش نمایش داده شده توسط 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);
}

این فراخوانی از طریق ویژگی onclick با دکمه در کد HTML بالا مرتبط است. توجه داشته باشید که در این مثال، دکمه ورود در ابتدا هنگام بارگذاری صفحه پنهان است. در بخش بعدی، قبل از نمایش دکمه، بررسی خواهیم کرد که آیا کاربر وارد سیستم شده است یا خیر.

تعریف نقطه ورود اصلی

حالا برای تعریف کد سطح بالایی که باید هنگام بارگذاری صفحه ابتدا اجرا شود. این کد از تابع کمکی احراز هویت داخلی Earth Engine به نام ee.data.authenticateViaPopup() استفاده می‌کند تا بررسی کند که آیا کاربر قبلاً وارد سیستم شده است یا خیر. اگر کاربر وارد سیستم شده باشد، تابع مجوزهای مناسب را درخواست می‌کند و در صورت موفقیت، تابع setUp() را برای مقداردهی اولیه Earth Engine و APIهای 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 که در بخش Prerequisites دریافت کرده‌اید را قرار دهید (می‌توانید روی این متغیرهای محلی در کد زیر کلیک کنید تا به صورت خودکار درج شوند). همچنین به جای '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>