Azure Maps のマップ コントロールを使用する

  • [アーティクル]

Azure Maps Web SDK には、Web またはモバイル アプリケーションに表示するための独自のコンテンツと画像を使用して対話型マップをカスタマイズできるマップ コントロールが用意されています。 このモジュールは、Web または Node.js アプリケーションから JavaScript または TypeScript を使用して簡単に Azure Maps REST サービスを使用できるようにするヘルパー ライブラリです。

この記事では Azure Maps Web SDK を使用しますが、Azure Maps サービスは任意のマップ コントロールと連携します。 サードパーティのマップ コントロール プラグインの一覧については、「Azure Maps コミュニティ - オープンソース プロジェクト」を参照してください。

Note

Azure Maps Web SDK Map Control v1 の廃止

Web SDK マップ コントロールのバージョン 1 は非推奨となり、2026 年 9 月 19 日に廃止されます。 サービスの中断を回避するには、2026 年 9 月 19 日までに Web SDK マップ コントロールのバージョン 3 に移行してください。 バージョン 3 には下位互換性があり、WebGL 2 との互換性、パフォーマンスの向上、3D 地形タイルのサポートなど、いくつかの利点があります。 詳細については、「Azure Maps Web SDK v1 移行ガイド」を参照してください。

前提条件

Web ページでマップ コントロールを使用するには、次のいずれかの前提条件が必要です。

Web ページに新しいマップを作成する

マップ コントロール クライアント側 JavaScript ライブラリを使って、Web ページにマップを埋め込むことができます。

  1. 新しい HTML ファイルを作成します。

  2. Azure Maps Web SDK に読み込みます。 次の 2 つのオプションのいずれかを選ぶことができます。

    • HTML ファイルの <head> 要素内の JavaScript と stylesheet に参照を追加して、グローバルにホストされる CDN バージョンの Azure Maps Web SDK を使用します。

      <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 パッケージを使用して、Azure Maps Web SDK のソース コードをローカルに読み込み、アプリを使用してホストします。 このパッケージには TypeScript 定義も含まれています。

      npm install azure-maps-control

    その後、ファイルの stylesheet 要素に Azure Maps の <head> への参照を追加します。

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

    Note

    TypeScript の定義は、次のコードを追加することによってアプリケーションにインポートできます。

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

  3. ページの本文全体を埋めるようにマップをレンダリングするには、次の <style> 要素を <head> 要素に追加します。

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

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

  4. ページの本文で、<div> 要素を追加して myMap の id を指定します。

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

  5. 次に、マップ コントロールを初期化します。 コントロールを認証するには、認証オプションで、Azure Maps サブスクリプション キーまたは Microsoft Entra 資格情報を使います。

    認証にサブスクリプション キーを使用している場合は、<head> 要素内の最初の <script> 要素の下に、次のスクリプト要素をコピーして貼り付けます。 <Your Azure Maps Key> を実際の Azure Maps サブスクリプション キーに置き換えます。

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

    認証に Microsoft Entra ID を使っている場合は、<head> 要素内の次のスクリプト要素と以下の最初の <script> 要素をコピーして貼り付けます。

    <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 Maps での認証の詳細については、Azure Maps での認証に関するドキュメントを参照してください。 Azure AD と Azure マップを統合する方法を示すサンプルの一覧については、GitHub の Azure マップ と Azure Active Directory のサンプルを参照してください。

    ヒント

    この例では、マップ <div> の id を渡しています。 これを行うもう 1 つの方法は、document.getElementById('myMap') を最初のパラメーターとして渡して、HTMLElement オブジェクトを渡すことです。

  6. 必要に応じて、次の meta 要素をページの head 要素に追加すると便利な場合があります。

     <!-- 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 ファイルは、次のコード スニペットのようになります。

     <!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. Web ブラウザーでファイルを開き、レンダリングされたマップを表示します。 それは次の図のようになるはずです。

    Screenshot of a map image showing rendered result.

マップのローカライズ

Azure Maps には、レンダリングされたマップの言語と地域ビューを設定するための 2 つの異なる方法が用意されています。 最初のオプションでは、この情報をグローバルな atlas 名前空間に追加します。これにより、アプリ内のすべてのマップ コントロール インスタンスにこれらの設定が既定で使用されます。 以下では、言語をフランス語 ("fr-FR") に、地域ビューを "auto" に設定します。

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

2 つ目のオプションでは、次のようにマップを読み込むときに、この情報をマップ オプションに渡します。

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

Note

言語と地域の設定が異なる複数のマップ インスタンスを同じページに読み込むことができます。 また、これらの設定は、マップの setStyle 関数を使用してマップを読み込んだ後に更新できます。

言語が "fr-FR" に設定され、地域ビューが Auto に設定されている Azure Maps の例を次に示します。

Screenshot showing a map image with its labels in French.

サポートされている言語と地域ビューの一覧については、「Azure Maps でのローカライズのサポート」を参照してください。

WebGL 2 との互換性

Azure Maps Web SDK 3.0 以降、Web SDK には、最新の Web ブラウザーでハードウェア アクセラレータによるレンダリングを可能にする強力なグラフィックス テクノロジである WebGL 2 との完全な互換性が含まれています。 WebGL 2 を使用すると、開発者は最新の GPU の機能を利用して複雑な地図や視覚化をより効率的にレンダリングでき、その結果、パフォーマンスとビジュアル品質が向上します。

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>

3D 地形タイル

Azure Maps Web SDK 3.0 以降、開発者は 3D 地形の視覚化を利用できます。 この機能を使用すると、標高データを地図に組み込んで、ユーザーにとってよりイマーシブなエクスペリエンスを作成できます。 山脈、渓谷、その他の地理的特徴のいずれを視覚化する場合でも、3D 地形のサポートにより、マッピング アプリケーションに新しいレベルのリアリズムがもたらされます。

次のコード例は、3D 地形タイルを実装する方法を示しています。

<!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 Government クラウドのサポート

Azure Maps Web SDK では、Azure Government クラウドがサポートされています。 Azure Maps Web SDK にアクセスする目的で使用される JavaScript と CSS URL はすべて変わりません。 Azure Maps プラットフォームの Azure Government クラウド バージョンに接続するには、次のタスクを実行する必要があります。

対話型マップ コントロールを使用する場合は、Map クラスのインスタンスを作成する前に、次のコード行を追加します。

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

マップとサービスを認証するときは、Azure Government クラウド プラットフォームからの Azure Maps 認証の詳細を必ず使用してください。

JavaScript フレームワーク

JavaScript フレームワークを開発に使用している場合は、次のいずれかのオープンソース プロジェクトが役に立つでしょう。

次のステップ

マップを作成して操作する方法について説明します。

マップを作成する

マップにスタイルを設定する方法については、以下を参照してください。

マップ スタイルを選択する

ベスト プラクティスとサンプルを参照してください。

ベスト プラクティス

コード サンプル

Microsoft Entra ID と Azure Maps を統合する方法を示すサンプルの一覧については、次を参照してください。

Microsoft Entra 認証サンプル