Menggunakan kontrol peta Azure Maps

Pustaka JavaScript sisi klien Kontrol Peta memungkinkan Anda untuk merender peta dan menyematkan fungsionalitas Azure Maps ke dalam aplikasi web atau seluler Anda.

Dokumentasi ini menggunakan Azure Maps Web SDK, tetapi layanan Azure Maps dapat digunakan dengan kontrol peta apa pun. Berikut adalah beberapa kontrol peta sumber terbuka populer yang telah dibuatkan plugin oleh tim Azure Maps.

Prasyarat

Untuk menggunakan Kontrol Peta di halaman web, Anda harus memiliki salah satu prasyarat berikut ini:

Membuat peta baru di halaman web

Anda bisa menyematkan peta di halaman web menggunakan pustaka JavaScript sisi klien Kontrol Peta.

  1. Buat file HTML baru.

  2. Muat di Azure Maps Web SDK. Anda dapat memilih salah satu dari dua opsi:

    • Gunakan versi CDN Azure Maps Web SDK yang dihosting secara global dengan menambahkan referensi ke JavaScript dan stylesheet dalam elemen <head> file HTML:

      <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css">
      <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.js"></script>
      
    • Muat kode sumber Azure Maps Web SDK secara lokal menggunakan paket NPM azure-maps-control dan host dengan aplikasi Anda. Paket ini juga menyertakan definisi TypeScript.

      npm install azure-maps-control

    Lalu tambahkan referensi ke stylesheet Azure Maps ke elemen <head> file:

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

    Catatan

    Definisi Typescript dapat diimpor ke dalam aplikasi Anda dengan menambahkan kode berikut:

    import * as atlas from 'azure-maps-control';
    
  3. Untuk merender peta sehingga memenuhi seluruh isi halaman, tambahkan elemen <style> berikut ke elemen <head>.

     <style>
         html, body {
             margin: 0;
         }
    
         #myMap {
             height: 100vh;
             width: 100vw;
         }
     </style>
    
  4. Di isi halaman, tambahkan elemen <div> dan berikan id dari myMap.

     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
    
  5. Sekarang, kita akan menginisialisasi kontrol peta. Untuk mengautentikasi kontrol, Anda harus memiliki kunci langganan Azure Maps atau menggunakan info masuk Azure Active Directory (AAD) dengan opsi autentikasi.

    Jika Anda menggunakan kunci langganan untuk autentikasi, salin dan tempel elemen skrip berikut di dalam elemen <head>, dan di bawah elemen <script> pertama. Ganti <Your Azure Maps Key> dengan kunci langganan utama Azure Maps Anda.

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

    Jika Anda menggunakan Azure Active Directory (AAD) untuk autentikasi, salin dan tempel elemen skrip berikut di dalam elemen <head>, dan di bawah elemen <script> pertama.

    <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 AAD Client Id>',
                  aadAppId: '<Your AAD App Id>',
                  aadTenant: '<Your AAD Tenant Id>'
              }
          });
      }
    </script>
    

    Untuk informasi selengkapnya tentang autentikasi dengan Azure Maps, lihat dokumen Outentikasi dengan Azure Maps. Selain itu, daftar sampel yang menunjukkan cara mengintegrasikan Azure Active Directory (AAD) dengan Azure Maps dapat ditemukan di sini.

    Tip

    Dalam contoh ini, kita telah meneruskan id dari <div> peta. Cara lain untuk melakukan ini adalah dengan meneruskan objek HTMLElement dengan meneruskan document.getElementById('myMap') sebagai parameter pertama.

  6. Secara opsional, mungkin akan berguna jika Anda menambahkan elemen meta berikut ke elemen head halaman:

     <!-- 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. Dengan menggabungkan semuanya, file HTML Anda akan terlihat seperti markup berikut:

     <!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/2/atlas.min.css" type="text/css">
         <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/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. Buka file di browser web Anda dan lihat peta yang dirender. Peta ini seharusnya terlihat seperti gambar di bawah ini:

    Gambar peta yang memperlihatkan hasil yang dirender

Melokalkan peta

Azure Maps menyediakan dua cara berbeda untuk mengatur tampilan bahasa dan wilayah untuk peta yang dirender. Opsi pertama adalah menambahkan informasi ini ke namespace atlas global, yang akan menyebabkan semua instans kontrol peta di aplikasi Anda menjadi default ke pengaturan ini. Berikut ini mengatur bahasa ke Bahasa Perancis (“fr-FR”) dan tampilan wilayah menjadi “Auto”:

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

Opsi kedua adalah untuk meneruskan informasi ini ke dalam opsi peta saat memuat peta seperti ini:

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

Catatan

Dimungkinkan untuk memuat beberapa instans peta pada halaman yang sama dengan pengaturan bahasa dan wilayah yang berbeda. Selain itu, pengaturan ini dapat diperbarui setelah peta dimuat menggunakan fungsi setStyle peta.

Berikut adalah contoh Azure Maps dengan bahasa yang diatur ke "fr-FR" dan tampilan wilayah diatur ke "Otomatis".

Gambar peta memperlihatkan label dalam bahasa Prancis

Daftar lengkap bahasa dan tampilan wilayah yang didukung didokumentasikan di sini.

Dukungan cloud Azure Government

Azure Maps Web SDK mendukung cloud Azure Government. Semua URL JavaScript dan CSS yang digunakan untuk mengakses Azure Maps Web SDK tetap sama. Tugas berikut ini harus dilakukan untuk menyambungkan ke versi cloud Azure Government dari platform Azure Maps.

Saat menggunakan kontrol peta interaktif, tambah baris kode berikut sebelum membuat instans kelas Map.

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

Pastikan untuk menggunakan detail autentikasi Azure Maps dari platform cloud Azure Government saat mengautentikasi peta dan layanan.

Saat menggunakan modul layanan, domain untuk layanan perlu diatur saat membuat instans titik akhir URL API. Misalnya, kode berikut membuat instans kelas SearchURL dan mengarahkan domain ke cloud Azure Government.

var searchURL = new atlas.service.SearchURL(pipeline, 'atlas.azure.us');

Jika langsung mengakses layanan Azure Maps REST, ubah domain URL menjadi atlas.azure.us. Misalnya, jika menggunakan layanan API pencarian, ubah domain URL dari https://atlas.microsoft.com/search/ menjadi https://atlas.azure.us/search/.

Kerangka kerja JavaScript

Jika mengembangkan menggunakan kerangka kerja JavaScript, salah satu proyek sumber terbuka berikut akan berguna:

Langkah berikutnya

Pelajari cara membuat dan berinteraksi dengan peta:

Pelajari cara membuat gaya peta:

Pelajari praktik terbaik dan lihat sampel:

Untuk daftar sampel yang memperlihatkan cara mengintegrasikan Azure Active Directory (AAD) dengan Azure Maps, lihat: