Azure Maps 맵 컨트롤 사용
Azure Maps 웹 SDK는 웹 또는 모바일 애플리케이션에 표시할 자체 콘텐츠와 이미지로 대화형 맵을 사용자 지정할 수 있는 맵 컨트롤을 제공합니다. 이 모듈은 JavaScript 또는 TypeScript를 사용하여 웹 또는 Node.js 애플리케이션에서 Azure Maps REST 서비스를 쉽게 사용할 수 있도록 지원하는 도우미 라이브러리입니다.
이 문서에서는 Azure Maps Web SDK를 사용하지만 Azure Maps 서비스는 모든 맵 컨트롤에서 사용할 수 있습니다. 타사 맵 제어 플러그 인 목록은 Azure Maps 커뮤니티 - 오픈 소스 프로젝트를 참조하세요.
참고 항목
Azure Maps 웹 SDK 맵 컨트롤 v1 종료
웹 SDK 맵 컨트롤 버전 1은 이제 더 이상 사용되지 않으며 2026년 9월 19일에 사용 중지됩니다. 서비스 중단을 방지하려면 2026년 9월 19일까지 Web SDK 맵 컨트롤 버전 3으로 마이그레이션합니다. 버전 3은 이전 버전과 호환되며 WebGL 2 호환성, 향상된 성능, 3D 지형 타일 지원 등 여러 가지 이점을 제공합니다. 자세한 내용은 Azure Maps 웹 SDK v1 마이그레이션 가이드를 참조하세요.
필수 조건
웹 페이지에서 맵 컨트롤을 사용하려면 다음 필수 조건 중 하나가 있어야 합니다.
- Azure Maps 계정
- 구독 키 또는 Microsoft Entra 자격 증명 자세한 내용은 인증 옵션을 참조하세요.
웹 페이지에 새 맵 만들기
맵 컨트롤 클라이언트 쪽 JavaScript 라이브러리를 사용하여 웹 페이지에 맵을 포함할 수 있습니다.
새 HTML 파일 만들기
Azure Maps 웹 SDK에서 로드합니다. 다음 두 가지 옵션 중 하나를 선택하세요.
HTML 파일의
<head>요소에 JavaScript 및stylesheet에 대한 참조를 추가하여 전역적으로 호스트되는 Azure Maps 웹 SDK의 CDN 버전을 사용합니다.<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 웹 SDK 소스 코드를 로드하여 앱으로 호스트합니다. 이 패키지에는 TypeScript 정의도 포함됩니다.
npm install azure-maps-control
그런 다음 Azure Maps
stylesheet에 대한 참조를 파일의<head>요소에 추가합니다.<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />참고 항목
다음 코드를 추가하여 TypeScript 정의를 애플리케이션으로 가져올 수 있습니다.
import * as atlas from 'azure-maps-control';맵이 페이지 본문 전체를 채우도록 렌더링하려면
<head>요소에 다음<style>요소를 추가합니다.<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에서 전달했습니다. 이 작업을 수행하는 또 다른 방법은document.getElementById('myMap')를 첫 번째 매개 변수로 전달하여HTMLElement개체에서 전달하는 것입니다.필요에 따라 페이지의
head요소에 다음meta요소를 추가하는 것이 유용할 수 있습니다.<!-- 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">이제 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>웹 브라우저에서 파일을 열고 렌더링된 맵을 봅니다. 이 테이블은 다음 이미지와 같습니다.
맵 지역화
Azure Maps는 렌더링된 맵의 언어 및 지역 보기를 설정하는 두 가지 방법을 제공합니다. 첫 번째 옵션은 이 정보를 글로벌 atlas 네임스페이스에 추가하는 것입니다. 그러면 앱의 모든 맵 컨트롤 인스턴스가 기본적으로 이 설정으로 지정됩니다. 다음은 언어를 프랑스어("fr-FR")로 설정하고 지역 보기를 "Auto"로 설정합니다.
atlas.setLanguage('fr-FR');
atlas.setView('Auto');
두 번째 옵션은 다음과 같이 맵을 로드할 때 맵 옵션에 이 정보를 전달하는 것입니다.
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>'
}
});
참고 항목
다른 언어 및 지역 설정을 사용하여 동일한 페이지에 여러 개의 맵 인스턴스를 로드할 수 있습니다. 또한 맵의 setStyle 함수를 사용하여 맵이 로드된 후 해당 설정을 업데이트할 수 있습니다.
다음은 언어가 “fr-FR”로 설정되고 지역 보기가 Auto로 설정된 Azure Maps의 예시입니다.
지원되는 언어 및 지역별 보기의 목록은 Azure Maps 지역화 지원을 참조하세요.
WebGL 2 호환성
Azure Maps Web SDK 3.0부터 Web SDK에는 최신 웹 브라우저에서 하드웨어 가속 렌더링을 가능하게 하는 강력한 그래픽 기술인 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@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 웹 SDK는 Azure Government 클라우드를 지원합니다. Azure Maps 웹 SDK에 액세스하는 데 사용되는 모든 JavaScript 및 CSS URL은 동일하게 유지됩니다. Azure Maps 플랫폼의 Azure Government 클라우드 버전에 연결하려면 다음 작업을 수행해야 합니다.
대화형 맵 컨트롤을 사용하는 경우 Map 클래스의 인스턴스를 만들기 전에 다음 코드 줄을 추가합니다.
atlas.setDomain('atlas.azure.us');
맵 및 서비스 인증 시 Azure Government 클라우드 플랫폼에서 Azure Maps 인증 세부 정보를 사용해야 합니다.
JavaScript 프레임워크
JavaScript 프레임워크를 사용하여 개발하는 경우 다음 오픈 소스 프로젝트 중 하나가 유용할 수 있습니다.
- ng-azure-maps - Azure 맵 주변의 Angular 10 래퍼.
- AzureMapsControl.Components - Azure Maps Blazor 구성 요소.
- Azure Maps React 구성 요소 - Azure Maps 컨트롤의 반응 래퍼.
- Vue Azure Maps - Vue 애플리케이션용 Azure Maps 구성 요소.
다음 단계
맵을 만들고 상호 작용하는 방법을 알아봅니다.
맵 스타일을 지정하는 방법을 알아봅니다.
모범 사례를 알아보고 샘플을 참조하세요.
Microsoft Entra ID를 Azure Maps와 통합하는 방법을 보여 주는 샘플 목록은 다음을 참조하세요.