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

[アーティクル]
10/24/2023

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 ページでマップコントロールを使用するには、次のいずれかの前提条件が必要です。

Azure Maps アカウント
サブスクリプションキーまたは Microsoft Entra 資格情報。詳細については、認証オプションに関する記事を参照してください。

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

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

新しい HTML ファイルを作成します。
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';
```
ページの本文全体を埋めるようにマップをレンダリングするには、次の <style> 要素を <head> 要素に追加します。
```
 <style>
     html, body {
         margin: 0;
     }

     #myMap {
         height: 100vh;
         width: 100vw;
     }
 </style>
```
ページの本文で、<div> 要素を追加して myMap の id を指定します。
```
 <body onload="InitMap()">
     <div id="myMap"></div>
 </body>
```
次に、マップコントロールを初期化します。コントロールを認証するには、認証オプションで、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 Maps を統合する方法を示すサンプルの一覧については、GitHub の Azure Maps および Azure Active Directory のサンプルを参照してください。

ヒント

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

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

 <!-- Ensures that Internet Explorer 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">

HTML ファイルは、次のコードスニペットのようになります。

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

     <meta charset="utf-8">

     <!-- Ensures that Internet Explorer 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>

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

マップのローカライズ

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 の例を次に示します。

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

WebGL 2 との互換性

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

<!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@^8/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 フレームワークを開発に使用している場合は、次のいずれかのオープンソースプロジェクトが役に立つでしょう。

ng-azure-maps - Azure Maps の Angular 10 ラッパー。
AzureMapsControl.Components - Azure Maps Blazor コンポーネント。
Azure Maps React Component - Azure Maps コントロール用の React ラッパー。
Vue Azure Maps - Vue アプリケーション用の Azure Maps コンポーネント。

次のステップ

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

マップを作成する

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

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

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

ベストプラクティス

コードサンプル

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

Microsoft Entra 認証サンプル

次の方法で共有

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

前提条件

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

マップのローカライズ

WebGL 2 との互換性

3D 地形タイル

Azure Government クラウドのサポート

JavaScript フレームワーク

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

マップのローカライズ

WebGL 2 との互換性

3D 地形タイル

Azure Government クラウドのサポート

JavaScript フレームワーク

次のステップ

フィードバック

その他のリソース

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