Azure Haritalar harita denetimini kullanma

  • Makale

Azure Haritalar Web SDK'sı, web veya mobil uygulamalarınızda görüntülenmek üzere kendi içeriğinizle ve görüntülerinizle etkileşimli haritaların özelleştirilmesini sağlayan bir Harita Denetimi sağlar. Bu modül, JavaScript veya TypeScript kullanarak web veya Node.js uygulamalarında Azure Haritalar REST hizmetlerini kullanmayı kolaylaştıran bir yardımcı kitaplıktır.

Bu makalede Azure Haritalar Web SDK'sı kullanılmaktadır ancak Azure Haritalar hizmetleri herhangi bir harita denetimiyle çalışır. Üçüncü taraf harita denetimi eklentilerinin listesi için bkz. topluluk Azure Haritalar - Açık kaynak projeler.

Dekont

Azure Haritalar Web SDK'sı Harita Denetimi v1 kullanımdan kaldır

Web SDK Eşleme Denetiminin sürüm 1'i artık kullanım dışıdır ve 19/9/26 tarihinde kullanımdan kaldırılacaktır. Hizmet kesintilerini önlemek için 19.09.26'ya kadar Web SDK Eşleme Denetiminin 3. sürümüne geçin. Sürüm 3 geriye dönük olarak uyumludur ve WebGL 2 Uyumluluğu, daha yüksek performans ve 3B arazi kutucukları için destek gibi çeşitli avantajları vardır. Daha fazla bilgi için bkz. Azure Haritalar Web SDK v1 geçiş kılavuzu.

Önkoşullar

Web sayfasında Harita Denetimi'ni kullanmak için aşağıdaki önkoşullardan birine sahip olmanız gerekir:

Web sayfasında yeni harita oluşturma

Harita Denetimi istemci tarafı JavaScript kitaplığını kullanarak bir web sayfasına harita ekleyebilirsiniz.

  1. Yeni bir HTML dosyası oluşturun.

  2. Azure Haritalar Web SDK'sını yükleyin. İki seçenek arasından birini belirleyebilirsiniz:

    • JavaScript'e ve stylesheet HTML dosyasının öğesine başvuru ekleyerek Azure Haritalar Web SDK'sının genel olarak barındırılan <head> CDN sürümünü kullanın:

      <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">
<script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

    • azure-maps-control npm paketini kullanarak Azure Haritalar Web SDK'sı kaynak kodunu yerel olarak yükleyin ve uygulamanızla barındırın. Bu paket, TypeScript tanımlarını da içerir.

      npm install azure-maps-control

    Ardından dosyanın öğesine Azure Haritalar stylesheet<head> başvuruları ekleyin:

    <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

    Dekont

    TypeScript tanımları aşağıdaki kod eklenerek uygulamanıza aktarılabilir:

    import * as atlas from 'azure-maps-control';

  3. Eşlemeyi sayfanın tüm gövdesini dolduracak şekilde işlemek için aşağıdaki öğeyi <head> öğesine ekleyin<style>.

     <style>
     html, body {
         margin: 0;
     }

     #myMap {
         height: 100vh;
         width: 100vw;
     }
 </style>

  4. Sayfanın gövdesine bir <div> öğe ekleyin ve myMap'i idverin.

     <body onload="InitMap()">
     <div id="myMap"></div>
 </body>

  5. Ardından harita denetimini başlatın. Denetimin kimliğini doğrulamak için bir Azure Haritalar abonelik anahtarı veya kimlik doğrulama seçenekleriyle Microsoft Entra kimlik bilgilerini kullanın.

    Kimlik doğrulaması için abonelik anahtarı kullanıyorsanız aşağıdaki betik öğesini öğesinin içine <head> ve ilk <script> öğenin altına kopyalayıp yapıştırın. değerini Azure Haritalar abonelik anahtarınız ile değiştirin<Your Azure Maps Key>.

    <script type="text/javascript">
    function InitMap()
    {
        var map = new atlas.Map('myMap', {
            center: [-122.33, 47.6],
            zoom: 12,
            language: 'en-US',
            authOptions: {
                authType: 'subscriptionKey',
                subscriptionKey: '<Your Azure Maps Key>'
            }
        });
   }
</script>

    Kimlik doğrulaması için Microsoft Entra Id kullanıyorsanız, aşağıdaki betik öğesini öğesinin içine <head> ve ilk <script> öğenin altına kopyalayıp yapıştırın.

    <script type="text/javascript">
  function InitMap()
  {
      var map = new atlas.Map('myMap', {
          center: [-122.33, 47.6],
          zoom: 12,
          language: 'en-US',
          authOptions: {
              authType: 'aad',
              clientId: '<Your Microsoft Entra Client Id>',
              aadAppId: '<Your Microsoft Entra App Id>',
              aadTenant: '<Your Microsoft Entra tenant Id>'
          }
      });
  }
</script>

    Azure Haritalar ile kimlik doğrulaması hakkında daha fazla bilgi için Azure Haritalar ile kimlik doğrulaması belgesine bakın. Azure AD'yi Azure Haritalar ile tümleştirmeyi gösteren örneklerin listesi için bkz. GitHub'da Azure Haritalar ve Azure Active Directory Örnekleri.

    Bahşiş

    Bu örnekte, öğesinin eşlemesini id<div>geçtik. Bunu HTMLElement yapmak için başka bir yol, ilk parametre olarak geçirerekdocument.getElementById('myMap') nesnesini geçirmektir.

  6. İsteğe bağlı olarak, sayfanın öğesine aşağıdaki meta öğeleri head eklemeyi yararlı bulabilirsiniz:

     <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
 <meta http-equiv="x-ua-compatible" content="IE=Edge">

 <!-- Ensures the web page looks good on all screen sizes. -->
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

  7. HTML dosyanız artık aşağıdaki kod parçacığına benzer olmalıdır:

     <!DOCTYPE html>
 <html>
 <head>
     <title></title>

     <meta charset="utf-8">

     <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
     <meta http-equiv="x-ua-compatible" content="IE=Edge">

     <!-- Ensures the web page looks good on all screen sizes. -->
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

     <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
     <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">
     <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>


     <script type="text/javascript">
         //Create an instance of the map control and set some options.
         function InitMap()
         {
             var map = new atlas.Map('myMap', {
                 center: [-122.33, 47.6],
                 zoom: 12,
                 language: 'en-US',
                 authOptions: {
                     authType: 'subscriptionKey',
                     subscriptionKey: '<Your Azure Maps Key>'
                 }
             });
         }
     </script>

     <style>
         html, body {
             margin: 0;
         }

         #myMap {
             height: 100vh;
             width: 100vw;
         }
     </style>
 </head>
 <body onload="InitMap()">
     <div id="myMap"></div>
 </body>
 </html>

  8. Dosyayı web tarayıcınızda açın ve işlenen haritayı görüntüleyin. Aşağıdaki görüntü gibi görünmelidir:

    Screenshot of a map image showing rendered result.

Haritayı yerelleştirme

Azure Haritalar, işlenen harita için dil ve bölgesel görünümü ayarlamanın iki farklı yolunu sağlar. İlk seçenek, bu bilgileri genel atlas ad alanına eklemektir ve bu da uygulamanızdaki tüm harita denetimi örneklerinin varsayılan olarak bu ayarlara sahip olmasını sağlar. Aşağıdakiler dili Fransızca ("fr-FR") ve bölgesel görünümü "Auto" olarak ayarlar:

atlas.setLanguage('fr-FR');
atlas.setView('Auto');

İkinci seçenek, haritayı şu şekilde yüklerken bu bilgileri harita seçeneklerine geçirmektir:

map = new atlas.Map('myMap', {
    language: 'fr-FR',
    view: 'Auto',

    authOptions: {
        authType: 'aad',
        clientId: '<Your AAD Client Id>',
        aadAppId: '<Your AAD App Id>',
        aadTenant: '<Your AAD Tenant Id>'
    }
});

Dekont

Farklı dil ve bölge ayarlarıyla aynı sayfaya birden çok harita örneği yüklemek mümkündür. Buna ek olarak, bu ayarlar haritanın işlevi kullanılarak harita yüklendikten setStyle sonra güncelleştirilebilir.

Dil "fr-FR" ve bölgesel görünüm olarak ayarlanmış bir Azure Haritalar örneği aşağıda verilmiştirAuto.

Screenshot showing a map image with its labels in French.

Desteklenen dillerin ve bölgesel görünümlerin listesi için bkz. Azure Haritalar yerelleştirme desteği.

WebGL 2 Uyumluluğu

Azure Haritalar Web SDK 3.0'dan başlayarak, Web SDK'sı modern web tarayıcılarında donanım hızlandırmalı işlemeyi sağlayan güçlü bir grafik teknolojisi olan WebGL 2 ile tam uyumluluk içerir. WebGL 2'yi kullanan geliştiriciler, karmaşık haritaları ve görselleştirmeleri daha verimli bir şekilde işlemek için modern GPU'ların özelliklerinden yararlanarak gelişmiş performans ve görsel kalite elde edebilir.

Map image showing WebGL 2 Compatibility.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, user-scalable=no" />
        <title>WebGL2 - Azure Maps Web SDK Samples</title>
        <link href=https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css rel="stylesheet"/>
        <script src=https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js></script>
        <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
        <style>
            html,
            body {
                width: 100%;
                height: 100%;
                padding: 0;
                margin: 0;
            }
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>
        <script>
            var map = new atlas.Map("map", {
                center: [-122.44, 37.75],
                bearing: 36,
                pitch: 45,
                zoom: 12,
                style: "grayscale_light",
                // Get an Azure Maps key at https://azuremaps.com/.
                authOptions: {
                    authType: "subscriptionKey",
                    subscriptionKey: " <Your Azure Maps Key> "
                }
            });

            // Wait until the map resources are ready.
            map.events.add("ready", (event) => {
                // Create a custom layer to render data points using deck.gl
                map.layers.add(
                    new DeckGLLayer({
                        id: "grid-layer",
                        data: "https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-bike-parking.json",
                        cellSize: 200,
                        extruded: true,
                        elevationScale: 4,
                        getPosition: (d) => d.COORDINATES,
                        // GPUGridLayer leverages WebGL2 to perform aggregation on the GPU.
                        // For more details, see https://deck.gl/docs/api-reference/aggregation-layers/gpu-grid-layer
                        type: deck.GPUGridLayer
                    })
                );
            });

            // A custom implementation of WebGLLayer
            class DeckGLLayer extends atlas.layer.WebGLLayer {
                constructor(options) {
                    super(options.id);
                    // Create an instance of deck.gl MapboxLayer which is compatible with Azure Maps
                    // https://deck.gl/docs/api-reference/mapbox/mapbox-layer
                    this._mbLayer = new deck.MapboxLayer(options);

                    // Create a renderer
                    const renderer = {
                        renderingMode: "3d",
                        onAdd: (map, gl) => {
                            this._mbLayer.onAdd?.(map["map"], gl);
                        },
                        onRemove: (map, gl) => {
                            this._mbLayer.onRemove?.(map["map"], gl);
                        },
                        prerender: (gl, matrix) => {
                            this._mbLayer.prerender?.(gl, matrix);
                        },
                        render: (gl, matrix) => {
                            this._mbLayer.render(gl, matrix);
                        }
                    };
                    this.setOptions({ renderer });
                }
            }
        </script>
    </body>    
</html>

3B arazi kutucukları

Geliştiriciler, Azure Haritalar Web SDK 3.0 sürümünden başlayarak 3B arazi görselleştirmelerinden yararlanabilir. Bu özellik, yükseltme verilerini haritalarınıza eklemenizi ve kullanıcılarınız için daha çevreleyici bir deneyim oluşturmanızı sağlar. İster dağ sıralarını, vadileri ister diğer coğrafi özellikleri görselleştirin, 3B arazi desteği harita uygulamalarınıza yeni bir gerçekçilik düzeyi getirir.

Aşağıdaki kod örneği, 3B arazi kutucuklarının nasıl uygulanduğunu gösterir.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, user-scalable=no" />
        <title>Elevation - Azure Maps Web SDK Samples</title>
        <link href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css rel="stylesheet" />
        <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js></script>
        <style>
            html,
            body {
                width: 100%;
                height: 100%;
                padding: 0;
                margin: 0;
            }
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="map"></div>
        <script>
            var map = new atlas.Map("map", {
                center: [-121.7269, 46.8799],
                maxPitch: 85,
                pitch: 60,
                zoom: 12,
                style: "road_shaded_relief",
                // Get an Azure Maps key at https://azuremaps.com/.
                authOptions: {
                    authType: "subscriptionKey",
                    subscriptionKey: "<Your Azure Maps Key>"
                }
            });

            // Create a tile source for elevation data. For more information on creating
            // elevation data & services using open data, see https://aka.ms/elevation
            var elevationSource = new atlas.source.ElevationTileSource("elevation", {
                url: "<tileSourceUrl>"
            });

            // Wait until the map resources are ready.
            map.events.add("ready", (event) => {

                // Add the elevation source to the map.
                map.sources.add(elevationSource);

                // Enable elevation on the map.
                map.enableElevation(elevationSource);
            });
        </script>
    </body>
</html>

Azure Kamu bulut desteği

Azure Haritalar Web SDK'sı Azure Kamu bulutunu destekler. Azure Haritalar Web SDK'sına erişmek için kullanılan tüm JavaScript ve CSS URL'leri aynı kalır. Azure Haritalar platformunun Azure Kamu bulut sürümüne bağlanmak için aşağıdaki görevlerin yapılması gerekir.

Etkileşimli harita denetimini kullanırken, sınıfın bir örneğini Map oluşturmadan önce aşağıdaki kod satırını ekleyin.

atlas.setDomain('atlas.azure.us');

Haritanın ve hizmetlerin kimliğini doğrularken Azure Kamu bulut platformundan Azure Haritalar kimlik doğrulama ayrıntılarını kullandığınızdan emin olun.

JavaScript çerçeveleri

JavaScript çerçevesi kullanarak geliştirme yapılırken aşağıdaki açık kaynak projelerden biri yararlı olabilir:

Sonraki adımlar

Harita oluşturmayı ve bunlarla etkileşim kurmayı öğrenin:

Harita oluşturma

Harita stili oluşturmayı öğrenin:

Harita stili seçme

En iyi yöntemleri öğrenin ve örneklere bakın:

En iyi uygulamalar

Kod örnekleri

Microsoft Entra ID'yi Azure Haritalar ile tümleştirmeyi gösteren örneklerin listesi için bkz:

Microsoft Entra kimlik doğrulama örnekleri