자습서: Azure Maps를 사용하여 주변 관심 지점 검색

아티클
05/02/2024

이 자습서에서는 Azure Maps를 사용하여 계정을 설정한 다음, Maps API를 사용하여 관심 지점을 검색하는 방법을 보여 줍니다. 이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

Azure Maps 계정 만들기
Maps 계정에 대한 구독 키 검색
지도 컨트롤 API를 사용하여 새 웹 페이지 만들기
Maps 검색 서비스를 사용하여 주변 관심 지점 찾기

필수 조건

Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.

참고 항목

Azure Maps의 인증에 대한 자세한 내용은 Azure Maps의 인증 관리를 참조하세요.

새 지도 만들기

맵 컨트롤 API는 편리한 클라이언트 라이브러리입니다. 이 API를 사용하면 맵을 웹 애플리케이션에 쉽게 통합할 수 있습니다. 기본 REST 서비스 호출의 복잡성을 숨기고 사용자 지정 가능한 구성 요소를 사용하여 생산성을 향상합니다. 다음 단계에서는 지도 컨트롤 API가 포함된 정적 HTML 페이지를 만드는 방법을 보여줍니다.

로컬 컴퓨터에서 새 파일을 만들고 이름을 MapSearch.html로 지정합니다.

다음 HTML 구성 요소를 파일에 추가합니다.

 <!DOCTYPE html>
 <html>
 <head>
     <title>Map Search</title>
     <meta charset="utf-8" />

     <!-- 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>
     function GetMap(){
         //Add Map Control JavaScript code here.
     }
     </script>

     <style>
         html,
         body {
             width: 100%;
             height: 100%;
             padding: 0;
             margin: 0;
         }

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

위의 HTML과 관련하여 알아야 할 몇 가지 사항:

HTML 헤더에는 Azure 맵 컨트롤 라이브러리에서 호스팅하는 CSS 및 JavaScript 리소스 파일이 포함됩니다.
페이지 본문의 onload 이벤트는 페이지 본문이 로드될 때 GetMap 함수를 호출합니다.
GetMap 함수에는 Azure Maps API에 액세스하는 데 사용되는 인라인 JavaScript 코드가 포함됩니다. 이는 다음 단계에서 추가됩니다.

다음 JavaScript 코드를 HTML 파일의 GetMap 함수에 추가하세요. 문자열 <Your Azure Maps Subscription Key>를 Azure Maps 계정에서 복사한 구독 키로 바꿉니다.
```
//Instantiate a map object
var map = new atlas.Map("myMap", {
    view: 'Auto',

    // Add your Azure Maps subscription key. https://aka.ms/am-primaryKey
    authOptions: {
        authType: 'subscriptionKey',
        subscriptionKey: '<Your Azure Maps Subscription Key>'
    }
});
```
위의 JavaScript에 대해 알아야 할 몇 가지 사항:
- Azure Maps 계정 키에 대한 맵 컨트롤 API를 초기화하는 GetMap 함수의 핵심입니다.
- atlas는 API 및 관련 시각적 구성 요소가 포함된 네임스페이스입니다.
- atlas.Map은 시각적 및 대화형 웹 지도에 대한 컨트롤을 제공합니다.
변경 내용을 파일에 저장하고 브라우저에서 해당 HTML 페이지를 엽니다. 표시된 맵은 계정 키를 통해 atlas.Map을 호출하여 만들 수 있는 가장 기본적인 지도입니다.
GetMap 함수에서 맵을 초기화한 후 다음 JavaScript 코드를 추가합니다.
```
//Wait until the map resources are ready.
map.events.add('ready', function() {

    //Create a data source and add it to the map.
    datasource = new atlas.source.DataSource();
    map.sources.add(datasource);

    //Add a layer for rendering point data.
    var resultLayer = new atlas.layer.SymbolLayer(datasource, null, {
        iconOptions: {
            image: 'pin-round-darkblue',
            anchor: 'center',
            allowOverlap: true
        },
        textOptions: {
            anchor: "top"
        }
    });

    map.layers.add(resultLayer);
});
```
이 코드 정보:
- 맵 리소스가 로드를 완료하고 맵에 액세스할 준비가 되면 시작되는 ready 이벤트가 맵에 추가됩니다.
- 맵 ready 이벤트 처리기에서, 결과 데이터를 저장하는 데이터 원본이 만들어집니다.
- 기호 레이어가 생성되어 데이터 원본에 연결됩니다. 이 계층은 데이터 원본의 결과 데이터를 렌더링하는 방법을 지정합니다. 이 경우 결과는 다른 아이콘이 겹칠 수 있도록 결과 좌표 위에 중앙에 있는 진한 파란색 둥근 핀 아이콘으로 렌더링됩니다.
- 결과 레이어는 맵 레이어에 추가됩니다.

검색 기능 추가

이 섹션에서는 Maps 검색 API를 사용하여 맵에서 관심 지점을 찾는 방법을 보여줍니다. 이는 개발자가 주소, 관심 지점 및 다른 지리적 위치 정보를 검색할 수 있도록 설계된 RESTful API입니다. 검색 서비스에서 지정된 주소에 위도와 경도 정보를 할당합니다.

팁

Azure Maps는 Azure Maps JavaScript REST SDK용 npm 모듈 집합을 제공합니다. 이러한 모듈에는 Node.js 애플리케이션에서 Azure Maps REST 서비스 사용을 간소화하는 클라이언트 라이브러리가 포함되어 있습니다. 사용 가능한 모듈의 전체 목록은 JavaScript/TypeScript REST SDK 개발자 가이드(미리 보기)를 참조하세요.

Search Service

맵 ready 이벤트 처리기에 다음 스크립트 블록을 추가합니다. 검색 쿼리를 빌드하는 코드입니다. Search Service의 기본 검색 API인 유사 항목 검색 서비스를 사용합니다. 유사 항목 검색 서비스는 주소, 위치 및 POI(관심 지점)와 같은 대부분의 유사 항목 입력을 처리합니다. 이 코드는 제공된 위도와 경도의 지정된 반경 내에서 인접한 주유소를 검색합니다. 그런 다음 GeoJSON 피처 컬렉션이 추출되어 데이터 원본에 추가되며, 그 결과 자동으로 맵 기호 계층에 데이터가 렌더링됩니다. 이 스크립트 블록의 마지막 부분은 맵의 setCamera 속성을 사용하여 결과의 경계 상자를 사용하여 맵 카메라 보기를 설정합니다.

var query = 'gasoline-station';
var radius = 9000;
var lat = 47.64452336193245;
var lon = -122.13687658309935;
var url = `https://atlas.microsoft.com/search/poi/json?api-version=1.0&query=${query}&lat=${lat}&lon=${lon}&radius=${radius}`;

fetch(url, {
    headers: {
        "Subscription-Key": map.authentication.getToken()
    }
})
.then((response) => response.json())
.then((response) => {
    var bounds = [];

    //Extract GeoJSON feature collection from the response and add it to the datasource
    var data = response.results.map((result) => {
        var position = [result.position.lon, result.position.lat];
        bounds.push(position);
        return new atlas.data.Feature(new atlas.data.Point(position), { ...result });
    });
    datasource.add(data);

    //Set camera to bounds to show the results
    map.setCamera({
        bounds: new atlas.data.BoundingBox.fromLatLngs(bounds),
        zoom: 10,
        padding: 15
    });
});

MapSearch.html 파일을 저장하고, 브라우저를 새로 고칩니다. 해당 지역의 주유소 위치에 둥근 파란색 핀이 있는 시애틀 중심으로 맵이 표시됩니다.
브라우저에 다음 HTTPRequest를 입력하여 지도에서 렌더링하는 원시 데이터를 볼 수 있습니다. <Your Azure Maps Subscription Key>를 구독 키로 바꿉니다.
```
https://atlas.microsoft.com/search/poi/json?api-version=1.0&query=gasoline%20station&subscription-key={Your-Azure-Maps-Subscription-key}&lat=47.6292&lon=-122.2337&radius=100000
```

이 시점에서 MapSearch 페이지에는 유사 항목 검색 쿼리에서 반환된 관심 지점의 위치가 표시될 수 있습니다. 몇 가지 대화형 기능과 위치에 대한 자세한 정보를 추가해 보겠습니다.

대화형 데이터 추가

지금까지 만든 맵은 검색 결과의 위도/경도 데이터만 살펴봅니다. 그러나 맵 검색 서비스에서 반환하는 원시 JSON에는 각 주유소에 대한 추가 정보가 포함되어 있습니다. 이름과 주소를 포함합니다. 대화형 팝업 상자를 사용하여 해당 데이터를 맵에 통합할 수 있습니다.

맵 ready 이벤트 처리기에서 유사 항목 검색 서비스를 쿼리하는 코드 뒤에 다음 코드 줄을 추가합니다. 이 코드는 팝업 인스턴스를 만들고 기호 레이어에 mouseover 이벤트를 추가합니다.
```
// Create a popup but leave it closed so we can update it and display it later.
popup = new atlas.Popup();

//Add a mouse over event to the result layer and display a popup when this event fires.
map.events.add('mouseover', resultLayer, showPopup);
```
API atlas.Popup은 맵의 필수 지점에 고정된 정보 창을 제공합니다.

Popup의 인스턴스를 만드는 코드 뒤에 맵 ready 이벤트 처리기에 다음 코드 줄을 추가하고 기호 계층에 mouseover 이벤트를 추가합니다. 이 코드는 관심 지점 위로 마우스를 가져갔을 때 결과가 포함된 팝업 창을 표시합니다.

function showPopup(e) {
    //Get the properties and coordinates of the first shape that the event occurred on.

    var p = e.shapes[0].getProperties();
    var position = e.shapes[0].getCoordinates();

    //Create HTML from properties of the selected result.
    var html = `
      <div style="padding:5px">
        <div><b>${p.poi.name}</b></div>
        <div>${p.address.freeformAddress}</div>
        <div>${position[1]}, ${position[0]}</div>
      </div>`;

    //Update the content and position of the popup.
    popup.setPopupOptions({
        content: html,
        position: position
    });

    //Open the popup.
    popup.open(map);
}

파일을 저장하고 브라우저를 새로 고칩니다. 이제 브라우저의 맵에서 검색 핀 위를 마우스로 가리키면 정보 팝업이 표시됩니다.

이 자습서에 사용된 완성된 코드는 GitHub의 search 자습서를 참조하세요.
이 샘플을 실시간으로 보려면 Azure Maps 코드 샘플 사이트에서 관심 지점 검색을 참조하세요.

다음 단계

다음 자습서에서는 두 위치 사이의 경로를 표시하는 방법을 보여 줍니다.

대상으로 라우팅