Azure Maps 웹 SDK 모범 사례

  • 아티클

이 문서에서는 Azure Maps 웹 SDK에 대한 모범 사례에 중점을 두지만 설명된 많은 모범 사례와 최적화는 다른 모든 Azure Maps SDK에 적용될 수 있습니다.

Azure Maps 웹 SDK는 다양한 방식으로 많은 공간 데이터 세트를 렌더링하기 위한 강력한 캔버스를 제공합니다. 경우에 따라 데이터를 동일한 방식으로 렌더링하는 여러 방법이 있지만 데이터 세트의 크기와 필요한 기능에 따라 한 방법이 다른 방법보다 더 나은 성능을 발휘할 수 있습니다. 이 문서에서는 성능을 극대화하고 원활한 사용자 환경을 만드는 모범 사례와 팁 및 요령을 제공하는 데 중점을 둡니다.

일반적으로 맵의 성능을 향상하려는 경우 레이어 및 원본의 수, 사용되는 데이터 세트, 렌더링 스타일의 복잡성을 줄이는 방법을 찾습니다.

보안 모범 사례

보안 모범 사례에 대한 자세한 내용은 인증 및 권한 부여 모범 사례를 참조하세요.

최신 버전의 Azure Maps 사용

Azure Maps SDK는 SDK에서 사용되는 모든 외부 종속성 라이브러리와 함께 일반 보안 테스트를 진행합니다. 알려진 보안 문제는 적절한 때에 해결되어 프로덕션으로 릴리스됩니다. 애플리케이션이 Azure Maps 웹 SDK의 호스트된 버전인 최신 주 버전을 가리키는 경우 보안 관련 수정을 포함하는 모든 부 버전 업데이트를 자동으로 수신하게 됩니다.

npm 모듈을 통해 Azure Maps 웹 SDK를 자체 호스팅하는 경우 최신 부 버전을 가리키도록 package.json 파일의 Azure Maps npm 패키지 버전 번호와 함께 캐럿(^) 기호를 사용해야 합니다.

"dependencies": {
  "azure-maps-control": "^3.0.0"
}

팁

항상 최신 버전의 npm Azure Maps Control을 사용합니다. 자세한 내용은 npm 설명서에서 azure-maps-control을 참조하세요.

초기 맵 로드 최적화

웹 페이지를 로드하는 경우 가장 먼저 수행해야 할 작업 중 하나는 사용자가 빈 화면에서 시작하지 않도록 최대한 빨리 렌더링을 시작하는 것입니다.

맵 준비 이벤트 보기

마찬가지로 맵을 처음 로드하는 경우에는 사용자가 빈 맵을 보지 않도록 가능한 한 빨리 데이터를 로드하는 것이 좋습니다. 맵은 리소스를 비동기적으로 로드하므로 사용자 고유의 데이터를 렌더링하기 전에 맵에서 상호 작용할 준비가 될 때까지 기다려야 합니다. 기다릴 수 있는 이벤트에는 load 이벤트와 ready 이벤트 두 가지가 있습니다. 로드 이벤트는 맵이 초기 맵 보기를 완전히 로드하고 모든 맵 타일이 로드된 후에 실행됩니다. "스타일 로드가 완료되지 않았습니다." 오류가 표시되면 load 이벤트를 사용하고 스타일이 완전히 로드될 때까지 기다려야 합니다.

준비 이벤트는 맵과의 상호 작용을 시작하는 데 필요한 최소 맵 리소스를 사용하는 경우에 발생합니다. 더 정확하게 말하면 맵이 스타일 데이터를 처음으로 로드할 때 ready 이벤트가 트리거됩니다. 준비 이벤트는 종종 로드 이벤트의 절반 시간 내에 발생할 수 있으므로 데이터를 맵에 더 빨리 로드하기 시작할 수 있습니다. 지금은 맵의 스타일이나 언어를 변경하지 마세요. 이렇게 하면 스타일 다시 로드가 트리거됩니다.

Azure Maps 웹 SDK 지연 로드

맵이 즉시 필요하지 않은 경우 필요할 때까지 Azure Maps 웹 SDK를 지연 로드합니다. 이렇게 하면 필요할 때까지 Azure Maps 웹 SDK에서 사용하는 JavaScript 및 CSS 파일의 로드가 지연됩니다. 이 상황이 발생하는 일반적인 시나리오는 페이지가 로드될 때 표시되지 않는 탭 또는 플라이아웃 패널에서 맵이 로드되는 경우입니다.

맵 지연 로드 코드 샘플에서는 단추를 누를 때까지 Azure Maps 웹 SDK 로딩을 지연하는 방법을 보여 줍니다. 소스 코드는 맵 지연 로드 샘플 코드를 참조하세요.

맵에 자리 표시자 추가

네트워크 제한 또는 애플리케이션 내의 다른 우선 순위로 인해 맵 로드하는 데 시간이 오래 걸리는 경우 맵div에 작은 배경 이미지를 자리 표시자로 추가하는 것이 좋습니다. 로드하는 동안 맵 div의 빈 공간이 채워집니다.

초기화 시 초기 맵 스타일 및 카메라 옵션 설정

앱은 종종 특정 위치 또는 스타일로 맵을 로드하려고 합니다. 경우에 따라 개발자는 맵이 로드될 때까지 기다리거나 ready 이벤트를 기다린 다음 맵의 setCamera 또는 setStyle 함수를 사용합니다. 이 작업은 원하는 맵 보기에 필요한 리소스를 로드하기 전에 기본적으로 로드되기 때문에 원하는 초기 맵 보기를 가져오는 데 더 많은 시간이 걸립니다. 더 나은 방법은 초기화 시 원하는 맵 카메라 및 스타일 옵션을 맵에 전달하는 것입니다.

데이터 원본 최적화

웹 SDK에는 두 개의 데이터 원본이 있습니다.

  • GeoJSON 원본: DataSource 클래스는 GeoJSON 형식의 원시 위치 데이터를 로컬로 관리합니다. 중소 규모의 데이터 세트에 적합합니다(수십만 개 이상의 기능).
  • 벡터 타일 원본: VectorTileSource 클래스는 맵 바둑판식 배열 시스템을 기반으로 현재 맵 보기의 벡터 타일 형식의 데이터를 로드합니다. 대규모 데이터 세트에 이상적입니다(수백만 또는 수십억 개의 기능).

대량 데이터 세트에 대한 타일 기반 솔루션 사용

수백만 개의 기능을 포함하는 큰 데이터 세트를 사용하는 경우 최적의 성능을 얻기 위해 벡터 또는 래스터 이미지 타일 서비스와 같은 서버 쪽 솔루션을 사용하여 데이터를 노출하는 것이 좋습니다.
벡터 타일은 타일의 포커스 영역에 클리핑된 기하 도형과 함께 보기에 있는 데이터를 로드하도록 최적화되며, 타일의 확대/축소 수준에 대한 맵의 해상도와 일치하도록 일반화됩니다.

Azure Maps Creator 플랫폼은 벡터 타일 형식으로 데이터를 검색합니다. 다른 데이터 형식은 Tippecanoe와 같은 도구를 사용할 수 있습니다. 벡터 타일 작업에 대한 자세한 내용은 GitHub의 Mapbox awesome-vector-tiles 추가 정보를 참조하세요.

서버 쪽에서 데이터 세트를 래스터 이미지 타일로 렌더링하는 사용자 지정 서비스를 만들고 맵 SDK의 TileLayer 클래스를 사용하여 데이터를 로드할 수도 있습니다. 맵은 최대 수십 개의 이미지를 로드하고 관리하기만 하면 되므로 뛰어난 성능을 제공합니다. 그러나 원시 데이터를 로컬에서 사용할 수 없기 때문에 래스터 타일 사용에 대한 몇 가지 제한 사항이 있습니다. 보조 서비스는 사용자가 클릭한 셰이프를 확인하는 등 모든 유형의 상호 작용 환경을 지원하는 데 필요한 경우가 많습니다. 또한 래스터 타일의 파일 크기는 일반화 및 확대/축소 수준에 최적화된 기하 도형을 포함하는 압축된 벡터 타일보다 큰 경우가 많습니다.

데이터 원본에 대한 자세한 내용은 데이터 원본 만들기를 참조하세요.

여러 데이터 세트를 단일 벡터 타일 원본으로 결합

맵에서 관리해야 하는 데이터 원본이 적을수록 표시되는 모든 기능을 더 빠르게 처리할 수 있습니다. 특히 타일 원본의 경우 두 개의 벡터 타일 소스를 함께 결합하면 타일을 검색하기 위한 HTTP 요청 수가 절반으로 줄어들며, 파일 헤더가 하나이기 때문에 총 데이터 양은 약간 줄어듭니다.

단일 벡터 타일 원본에서 여러 데이터 세트를 결합하는 것은 Tippecanoe와 같은 도구를 사용하여 구현할 수 있습니다. 데이터 세트를 단일 기능 컬렉션으로 결합하거나 벡터 타일 내에서 원본 레이어라고 하는 별도의 레이어로 분리할 수 있습니다. 벡터 타일 원본을 렌더링 레이어에 연결하는 경우 레이어로 렌더링하려는 데이터가 포함된 원본 레이어를 지정합니다.

데이터 업데이트로 인한 캔버스 새로 고침 수 줄이기

DataSource 클래스의 데이터를 추가하거나 업데이트할 수 있는 몇 가지 방법이 있습니다. 다음 목록에서는 성능 향상을 위한 다양한 방법과 몇 가지 고려 사항을 보여 줍니다.

  • 데이터 원본 add 함수를 사용하여 데이터 원본에 하나 이상의 기능을 추가할 수 있습니다. 이 함수가 호출될 때마다 맵 캔버스 새로 고침이 트리거됩니다. 여러 기능을 추가하는 경우 데이터 세트를 반복하여 각 기능에 대해 이 함수를 호출하는 대신 배열 또는 기능 컬렉션으로 결합하여 해당 함수에 한 번 전달합니다.
  • 데이터 원본 setShapes 함수를 사용하여 데이터 원본의 모든 셰이프를 덮어쓸 수 있습니다. 내부적으로 데이터 원본 clear 및 add 함수를 결합하고, 두 가지 대신 단일 맵 캔버스를 새로 고치는 것이 더 빠릅니다. 데이터 원본의 모든 데이터를 업데이트하려면 이 함수를 사용합니다.
  • 데이터 원본 importDataFromUrl 함수를 사용하여 URL을 통해 데이터 원본에 GeoJSON 파일을 로드할 수 있습니다. 데이터가 다운로드되면 데이터 원본 add 함수에 전달됩니다. GeoJSON 파일이 다른 도메인에서 호스트되는 경우 다른 도메인에서 CORs(cross domain requests)를 지원하는지 확인합니다. 도메인의 로컬 파일에 데이터를 복사하거나 CORs를 사용하도록 설정된 프록시 서비스를 만드는 것을 고려하지 않는 경우. 파일이 클 경우 벡터 타일 원본으로 변환하는 것이 좋습니다.
  • 기능이 Shape 클래스로 래핑되는 경우 셰이프의 addProperty, setCoordinates, setProperties 함수는 모두 데이터 원본에서 업데이트를 트리거하고 맵 캔버스를 새로 고칩니다. 데이터 원본 getShapes 및 getShapeById 함수에서 반환하는 모든 기능은 자동으로 Shape 클래스로 래핑됩니다. 여러 셰이프를 업데이트하려면 데이터 원본 toJson 함수를 사용하여 JSON으로 변환하고 GeoJSON을 편집한 다음, 해당 데이터를 데이터 원본 setShapes 함수에 전달하는 것이 더 빠릅니다.

데이터 원본 Clear 함수를 불필요하게 호출하지 않습니다.

DataSource 클래스의 Clear 함수를 호출하면 맵 캔버스를 새로 고칩니다. clear 함수가 연속적으로 여러 번 호출되는 경우 각 새로 고침이 발생할 때까지 맵이 대기하는 동안 지연이 발생할 수 있습니다.

이는 데이터 원본을 지우고, 새 데이터를 다운로드하고, 데이터 원본을 다시 지운 다음, 새 데이터를 데이터 원본에 추가하는 애플리케이션의 일반적인 시나리오입니다. 원하는 사용자 환경에 따라 다음과 같은 대안이 더 나을 것입니다.

  • 새 데이터를 다운로드하기 전에 데이터를 지운 다음 새 데이터를 데이터 원본 add 또는 setShapes 함수에 전달합니다. 맵의 유일한 데이터 세트인 경우 새 데이터를 다운로드하는 동안 맵은 비어 있게 됩니다.
  • 새 데이터를 다운로드한 다음 데이터 원본 setShapes 함수에 전달합니다. 이렇게 하면 맵의 모든 데이터가 바뀝니다.

사용하지 않는 기능 및 속성 제거

데이터 세트에 앱에서 사용되지 않는 기능이 포함된 경우 이를 제거합니다. 마찬가지로 필요 없는 기능에 대한 모든 속성을 제거합니다. 여기에는 여러 가지 이점이 있습니다.

  • 다운로드해야 하는 데이터의 양을 줄입니다.
  • 데이터를 렌더링할 때 반복해야 하는 기능 수를 줄입니다.
  • 경우에 따라 데이터 기반 식 및 필터를 단순화하거나 제거하여 렌더링 시 필요한 프로세스를 줄일 수 있습니다.

기능에 많은 속성이나 콘텐츠가 포함된 경우 데이터 원본에 추가되는 내용을 렌더링에 필요한 것만으로 제한하고 필요한 경우 다른 속성이나 콘텐츠를 검색하기 위한 별도의 메서드나 서비스를 포함하는 것이 훨씬 더 효율적입니다. 예를 들어, 클릭했을 때 맵에 위치를 표시하는 간단한 맵이 있는 경우 많은 세부 콘텐츠가 표시됩니다. 데이터 기반 스타일을 사용하여 맵에서 위치가 렌더링되는 방식을 사용자 지정하려면 데이터 원본에 필요한 속성만 로드합니다. 세부 콘텐츠를 표시하려는 경우 기능의 ID를 사용하여 다른 콘텐츠를 별도로 검색합니다. 콘텐츠가 서버에 저장된 경우 서비스를 사용하여 비동기적으로 검색함으로써 맵을 처음 로드할 때 다운로드해야 하는 데이터의 양을 줄일 수 있습니다.

또한 기능 좌표의 유효 숫자 수를 줄이면 데이터 크기를 크게 줄일 수 있습니다. 좌표가 소수 자릿수 12자리 이상을 포함하는 경우는 흔하지만 소수 자릿수 6자리의 정확도는 0.1m 정도로 좌표가 나타내는 위치보다 정확도가 높습니다(실내 건물 레이아웃과 같은 작은 위치 데이터로 작업할 경우 소수점 6자리 권장). 소수 자릿수가 여섯 자리를 초과하는 경우 데이터가 렌더링되는 방식에는 차이가 거의 없으며, 사용자는 추가적인 이점 없이 더 많은 데이터를 다운로드해야 합니다.

다음은 GeoJSON 데이터를 사용하는 데 유용한 도구 목록입니다.

데이터를 신속하게 변경하기 위해 별도의 데이터 원본 사용

스트리밍 데이터의 라이브 업데이트를 표시하거나 기능에 애니메이션을 적용하는 등의 작업을 위해 맵에서 데이터를 신속하게 업데이트해야 하는 경우가 있습니다. 데이터 원본이 업데이트되면 렌더링 엔진은 데이터 원본의 모든 기능을 반복하여 렌더링합니다. 빠르게 변경되는 데이터에서 정적 데이터를 다른 데이터 원본으로 분리하면, 각 업데이트에서 다시 렌더링되는 기능의 수가 줄어들기 때문에 전반적인 성능이 향상됩니다.

라이브 데이터와 함께 벡터 타일을 사용하는 경우 업데이트를 지원하는 손쉬운 방법은 expires 응답 헤더를 사용하는 것입니다. 기본적으로 모든 벡터 타일 원본 또는 래스터 타일 레이어는 expires 날짜를 기준으로 타일을 자동으로 다시 로드합니다. 맵의 트래픽 흐름 및 인시던트 타일은 이 기능을 사용하여 새 실시간 트래픽 데이터가 맵에 표시되도록 합니다. Maps refreshExpiredTiles 서비스 옵션을 false로 설정하여 이 기능을 사용하지 않도록 설정할 수 있습니다.

GeoJSON 데이터 원본에서 버퍼 및 허용 오차 옵션 조정

DataSource 클래스는 즉시 렌더링하기 위해 원시 위치 데이터를 벡터 타일 로컬로 변환합니다. 로컬 벡터 타일은 타일 간 원활한 렌더링을 보장하기 위해 약간의 버퍼가 있는 원시 데이터를 타일 영역의 경계에 클리핑합니다. buffer 옵션의 값이 작을수록 로컬 벡터 타일에 저장되는 중첩된 데이터 수가 줄어들고 성능이 향상되지만 발생하는 렌더링 아티팩트의 변화가 커집니다. 렌더링 아티팩트를 최소화하면서 적절한 성능 조합을 얻으려면 이 옵션을 조정하세요.

DataSource 클래스에는 렌더링 용도로 기하 도형 해상도를 낮출 때 Douglas-Peucker 단순화 알고리즘과 함께 사용되는 tolerance 옵션도 있습니다. 이 허용 범위 값을 높이면 기하 도형의 해상도가 낮아지고 성능이 향상됩니다. 이 옵션을 조정하여 데이터 세트에 대한 적절한 기하 도형 해상도 조합 및 성능을 가져옵니다.

GeoJSON 데이터 원본에 대한 최대 확대/축소 옵션 설정

DataSource 클래스는 즉시 렌더링하기 위해 원시 위치 데이터를 벡터 타일 로컬로 변환합니다. 기본적으로 이 작업을 확대/축소 수준 18까지 수행하며, 이 지점에서 더 가까이 확대하면 확대/축소 수준 18로 생성된 타일의 데이터를 샘플링합니다. 해당 수준에서 확대하는 경우 높은 해상도를 필요로 하는 대부분의 데이터 세트에 적합합니다. 그러나 상태 또는 다각형을 볼 때처럼 축소하여 보는 경우가 많은 데이터 세트에서는 데이터 원본의 minZoom 옵션을 12와 같은 더 작은 값으로 설정하면 계산, 로컬 타일 생성, 데이터 원본에서 사용하는 메모리를 줄이고 성능을 향상합니다.

GeoJSON 응답 최소화

서비스를 통하거나 플랫 파일을 로드하여 서버에서 GeoJSON 데이터를 로드하는 경우 다운로드 크기를 필요보다 크게 만드는 불필요한 공간 문자를 제거하도록 데이터를 최소화해야 합니다.

URL을 사용하여 원시 GeoJSON 액세스

GeoJSON 개체를 JavaScript 내에 인라인으로 저장할 수도 있지만 이 경우에는 이 개체에 대해 만든 변수와 별도의 웹 작업자에서 관리하는 데이터 원본 인스턴스에 저장되므로 많은 메모리가 사용됩니다. 대신 URL을 사용하여 앱에 GeoJSON을 노출하면 데이터 원본이 데이터의 단일 복사본을 데이터 원본 웹 작업자에게 직접 로드합니다.

렌더링 레이어 최적화

Azure Maps는 맵에서 데이터를 렌더링하는 다양한 레이어를 제공합니다. 레이어를 시나리오에 맞게 조정하는 여러 가지 최적화 방법이 있으며, 성능 향상과 전체적인 사용자 환경을 조정할 수 있습니다.

레이어를 한 번 만들고 다시 사용

Azure Maps 웹 SDK는 데이터를 기준으로 합니다. 데이터는 데이터 원본으로 이동하여 렌더링 레이어에 연결됩니다. 맵의 데이터를 변경하려면 데이터 원본의 데이터를 업데이트하거나 레이어의 스타일 옵션을 변경합니다. 이 방법은 제거한 다음, 변경할 때마다 레이어를 다시 만드는 것보다 더 빠릅니다.

기호 레이어 위에 거품형 레이어 고려

거품형 레이어는 맵에서 지점으로 원을 렌더링하고 데이터 기반 식을 사용하여 해당 반지름과 색의 스타일을 쉽게 지정할 수 있습니다. 원은 WebGL이 그릴 수 있는 간단한 모양이기 때문에 렌더링 엔진은 이미지를 로드하고 렌더링해야 하는 기호 레이어보다 더 빠르게 렌더링할 수 있습니다. 수십 개의 지점을 렌더링하는 경우 두 렌더링 레이어의 성능 차이가 눈에 띄게 드러납니다.

HTML 마커 및 팝업 사용 최소화

WebGL을 사용하여 렌더링하는 Azure Maps 웹 컨트롤의 대부분의 레이어와는 달리, HTML 마커 및 팝업은 렌더링에 기존 DOM 요소를 사용합니다. 따라서 HTML 마커 및 팝업이 페이지를 더 추가할수록 DOM 요소가 더 많아집니다. HTML 마커 및 팝업을 많이 추가하면 성능이 저하될 수 있습니다. 더 큰 데이터 세트의 경우 데이터를 클러스터링하거나 기호 또는 거품형 레이어를 사용하는 것이 좋습니다.

여러 핀을 사용하여 팝업을 다시 사용 코드 샘플에서는 단일 팝업을 만들고 해당 콘텐츠와 위치를 업데이트하여 다시 사용하는 방법을 보여 줍니다. 소스 코드는 여러 핀을 사용하여 팝업을 다시 사용을 참조하세요.

A screenshot of a map of Seattle with three blue pins, demonstrating how to Reuse Popups with Multiple Pins.

즉, 맵에서 몇 가지 지점만 렌더링해야 하는 경우 HTML 마커의 단순성이 더 효과적일 수 있습니다. 또한 필요에 따라 HTML 마커를 쉽게 끌어올 수 있습니다.

레이어 결합

맵은 수백 개의 레이어를 렌더링할 수 있지만, 레이어가 많을수록 장면을 렌더링하는 데 걸리는 시간이 길어집니다. 레이어 수를 줄이기 위한 한 가지 전략은 스타일이 비슷하거나 데이터 기반 스타일을 사용하여 스타일을 지정할 수 있는 레이어를 결합하는 것입니다.

예를 들어 모든 기능에 true 또는 false의 값이 있을 수 있는 isHealthy 속성을 가진 데이터 세트를 생각해 보겠습니다. 이 속성에 따라 다른 색상의 거품을 렌더링하는 거품형 레이어를 만드는 경우 다음 목록에 표시된 것과 같이 성능이 가장 낮은 것에서 가장 높은 것까지 여러 가지 방법이 사용할 수 있습니다.

  • isHealthy 값을 기준으로 데이터를 두 데이터 원본으로 분할하고, 각 데이터 원본에 하드 코딩된 색 옵션이 있는 거품형 레이어를 연결합니다.
  • 모든 데이터를 단일 데이터 원본에 넣고 하드 코딩된 색 옵션과 isHealthy 속성을 기반으로 하는 필터가 있는 두 개의 거품형 레이어를 만듭니다.
  • 모든 데이터를 단일 데이터 원본에 넣고 isHealthy 속성을 기반으로 하는 색 옵션에 대해 case 스타일 식을 사용하여 단일 거품형 레이어를 만듭니다. 다음은 이 방법을 보여 주는 코드 샘플입니다.
var layer = new atlas.layer.BubbleLayer(source, null, {
    color: [
        'case',

        //Get the 'isHealthy' property from the feature.
        ['get', 'isHealthy'],

        //If true, make the color 'green'. 
        'green',

        //If false, make the color red.
        'red'
    ]
});

부드러운 기호 레이어 애니메이션 만들기

기호 레이어는 기본적으로 충돌 검색을 사용하도록 설정되어 있습니다. 이 충돌 검색은 두 기호가 겹치지 않도록 합니다. 기호 레이어의 아이콘 및 텍스트 옵션에는 두 가지 옵션이 있습니다.

  • allowOverlap - 다른 기호와 충돌하는 경우 기호를 표시할지를 지정합니다.
  • ignorePlacement - 다른 기호가 기호와 충돌하도록 허용할지 지정합니다.

두 옵션은 기본적으로 false로 설정됩니다. 기호에 애니메이션을 적용하는 경우 애니메이션의 각 프레임에 충돌 감지 계산이 실행되어 애니메이션 속도가 느려지고 덜 유동적으로 보일 수 있습니다. 애니메이션을 매끄럽게 하려면 해당 옵션을 true로 설정합니다.

단순 기호 애니메이션 코드 샘플에서는 기호 레이어에 애니메이션 효과를 주는 간단한 방법을 보여 줍니다. 이 샘플의 소스 코드는 단순 기호 애니메이션 샘플 코드를 참조하세요.

A screenshot of a map of the world with a symbol going in a circle, demonstrating how to animate the position of a symbol on the map by updating the coordinates.

확대/축소 수준 범위 지정

데이터가 다음 조건 중 하나를 충족하면 렌더링 엔진이 확대/축소 수준 범위를 벗어날 때 건너뛸 수 있도록 레이어의 최소 및 최대 확대/축소 수준을 지정해야 합니다.

  • 데이터가 벡터 타일 원본에서 제공되는 경우 다양한 데이터 유형의 원본 레이어는 확대/축소 수준 범위를 통해서만 사용할 수 있는 경우가 많습니다.
  • 0에서 24까지의 모든 확대/축소 수준에 대해 타일이 없는 타일 레이어를 사용하는 경우 타일을 포함하는 수준에서만 렌더링하고 다른 확대/축소 수준의 타일로 누락된 타일을 채우지 마세요.
  • 특정 확대/축소 수준에서만 레이어를 렌더링하려는 경우. 모든 레이어에는 이 논리 maxZoom > zoom >= minZoom에 따라 확대/축소 수준 간에 레이어가 렌더링되는 minZoom 및 maxZoom 옵션이 있습니다.

예제

//Only render this layer between zoom levels 1 and 9. 
var layer = new atlas.layer.BubbleLayer(dataSource, null, {
    minZoom: 1,
    maxZoom: 10
});

타일 레이어 경계 및 원본 확대/축소 범위 지정

기본적으로 타일 레이어는 전 세계 전체에 타일을 로드합니다. 그러나 타일 서비스에 특정 영역에 대한 타일만 있는 경우 맵은 이 영역 밖에서 타일을 로드하려고 시도합니다. 이 경우 각 타일에 대한 요청이 생성되고 맵에서 다른 요청을 차단하여 다른 레이어의 렌더링 속도를 늦출 수 있는 응답을 기다립니다. 타일 레이어의 경계를 지정하면 맵에서 해당 경계 상자 내에 있는 타일만을 요청하게 됩니다. 또한 특정 확대/축소 수준 간에서만 사용할 수 있는 타일 레이어의 경우 같은 이유로 최소 및 최대 원본 확대/축소를 지정합니다.

예제

var tileLayer = new atlas.layer.TileLayer({
    tileUrl: 'myTileServer/{z}/{y}/{x}.png',
    bounds: [-101.065, 14.01, -80.538, 35.176],
    minSourceZoom: 1,
    maxSourceZoom: 10
});

기본 맵이 표시되지 않는 경우 빈 맵 스타일 사용

맵에서 기본 맵을 완전히 포함하는 레이어가 중첩되는 경우 맵 스타일을 blank 또는 blank_accessible로 설정하여 기본 맵이 랜더링되지 않도록 하세요. 이 작업을 수행하는 일반적인 시나리오는 전체 지구본 타일을 오버레이할 때 기본 맵 위에 불투명도 또는 투명 영역이 없는 경우입니다.

이미지 또는 타일 레이어에 부드러운 애니메이션 효과 주기

맵에서 일련의 이미지 또는 타일 레이어를 통해 애니메이션 효과를 주려는 경우. 각 애니메이션 프레임에서 단일 레이어의 소스를 업데이트하는 것보다 각 이미지 또는 타일 레이어에 대한 레이어를 만들고 불투명도를 변경하는 것이 더 빠른 경우가 많습니다. 불투명도를 0으로 설정하여 레이어를 숨기고 불투명도를 0보다 큰 값으로 설정한 새 레이어를 표시하는 것이 레이어의 원본을 업데이트하는 것보다 더 빠릅니다. 또는 레이어의 표시 유형을 전환할 수는 있지만 레이어의 페이드 기간은 0으로 설정해야 합니다. 그렇지 않으면 레이어가 표시될 때 애니메이션 효과가 적용되어 새 레이어가 표시되기 전에 숨겨져 있던 이전 레이어로 인해 깜박임 효과가 발생합니다.

기호 레이어 충돌 검색 논리 조정

기호 레이어에는 아이콘과 텍스트 모두에 대한 allowOverlap 및 ignorePlacement라는 두 가지 옵션이 있습니다. 이 두 옵션은 기호의 아이콘 또는 텍스트가 겹치거나 겹쳐질 수 있는지를 지정합니다. 이를 false로 설정하면 기호 레이어는 각 지점을 렌더링할 때 계산을 수행하여 레이어의 이미 렌더링된 다른 기호와 충돌하는지 확인하고, 그렇지 않은 경우 충돌하는 기호를 렌더링하지 않습니다. 이는 맵의 혼란도를 줄이고 렌더링되는 개체 수를 줄이는 데 유용합니다. 옵션을 false로 설정하면 이 충돌 검색 논리를 건너뛰고 모든 기호가 맵에 렌더링됩니다. 최상의 성능 및 사용자 환경 조합을 얻으려면 이 옵션을 조정합니다.

대량 지점 데이터 세트 클러스터

대량의 데이터 요소 집합으로 작업하는 경우 특정 확대/축소 수준에서 렌더링될 때 대부분의 지점이 겹쳐서 표시되고 일부만 표시되는 것을 볼 수 있습니다. 클러스터링은 가까이 위치한 지점을 그룹화하고 클러스터링된 단일 지점으로 표시하는 프로세스입니다. 사용자가 맵을 확대하면 클러스터는 개별 점으로 분리됩니다. 이렇게 하면 렌더링해야 하는 데이터의 양이 크게 줄어들고, 맵이 덜 혼란스러워지며 성능은 향상됩니다. DataSource 클래스에는 데이터를 로컬로 클러스터링하는 옵션이 있습니다. 또한 벡터 타일을 생성하는 많은 도구에도 클러스터링 옵션이 있습니다.

또한 클러스터 반경 크기를 늘려 성능을 향상합니다. 클러스터 반경이 클수록 추적하고 렌더링해야 하는 클러스터링 포인트가 적습니다. 자세한 내용은 웹 SDK의 점 데이터 클러스터링을 참조하세요.

가중치가 적용된 클러스터링된 열 맵 사용

열 지도 레이어는 수만 개의 데이터 지점을 쉽게 렌더링할 수 있습니다. 더 큰 데이터 세트의 경우 데이터 원본에 대한 클러스터링을 사용하도록 설정하고 작은 클러스터 반경을 사용하는 것을 고려하고 클러스터 point_count 속성을 높이 맵의 가중치로 사용합니다. 클러스터 반경의 크기가 몇 픽셀에 불과한 경우 렌더링된 열 지도에 시각적 차이가 거의 없습니다. 더 큰 클러스터 반경을 사용하면 성능이 향상되지만 렌더링 된 열 지도의 해상도가 낮아질 수 있습니다.

var layer = new atlas.layer.HeatMapLayer(source, null, {
   weight: ['get', 'point_count']
});

자세한 내용은 클러스터링 및 열 지도 레이어를 참조하세요.

이미지 리소스 작게 유지

이미지를 맵 이미지 스프라이트에 추가하여 기호 레이어의 아이콘 또는 다각형 레이어의 패턴으로 렌더링할 수 있습니다. 다운로드해야 하는 데이터의 양과 맵 이미지 스프라이트에 필요한 공간의 크기를 최소화하기 위해 이미지를 작게 유지합니다. size 옵션을 사용하여 아이콘의 크기를 스케일링하는 기호 레이어를 사용하는 경우 계획이 맵에 표시할 최대 크기의 이미지를 사용합니다. 이렇게 하면 사용하는 리소스를 최소화하면서 아이콘이 고해상도로 렌더링됩니다. 또한 SVG는 단순한 아이콘 이미지에 대해 더 작은 파일 형식으로 사용할 수도 있습니다.

식 최적화

데이터 기반 스타일 식은 맵에서 데이터를 필터링하고 스타일을 지정할 수 있는 유연성과 성능을 제공합니다. 식을 최적화할 수 있는 여러 가지 방법이 있습니다. 몇 가지 팁은 다음과 같습니다.

필터의 복잡성을 줄입니다.

필터는 데이터 원본에 있는 모든 데이터를 반복하고 각 필터가 필터의 논리와 일치하는지 확인합니다. 필터가 복잡해지면 이로 인해 성능 문제가 발생할 수 있습니다. 문제를 해결하기 위한 몇 가지 가능한 전략은 다음과 같습니다.

  • 벡터 타일을 사용하는 경우 데이터를 다른 원본 레이어로 나눕니다.
  • DataSource 클래스를 사용하는 경우 해당 데이터를 별도의 데이터 원본으로 나눕니다. 데이터 원본 수를 필터의 복잡성으로 조정합니다. 데이터 원본이 너무 많아도 성능 문제가 발생할 수 있으므로 시나리오에 가장 적합한 것이 무엇인지 확인하기 위해 몇 가지 테스트를 수행해야 할 수 있습니다.
  • 레이어에 복잡한 필터를 사용하는 경우 필터의 복잡성을 줄이기 위해 스타일 식이 있는 여러 레이어를 사용하는 것이 좋습니다. 많은 수의 레이어로 스타일 식을 사용할 수 있는 경우에도 성능 문제가 발생할 수 있으므로 하드 코딩된 스타일 여러 레이어를 만들지 마세요.

식이 오류를 생성하지 않는지 확인합니다.

식은 렌더링 시 계산 또는 논리적 연산을 수행하는 코드를 생성하는 데 종종 사용됩니다. 애플리케이션의 나머지 부분에 있는 코드와 마찬가지로 계산과 논리가 타당하며 오류를 발생하지 않는지 확인합니다. 식에서 오류가 발생하면 식 계산에 문제가 발생하여 성능이 감소하고 문제를 렌더링하게 됩니다.

유의해야 하는 한 가지 일반적인 오류는 모든 기능에 존재하지 않을 수 있는 기능 속성에 의존하는 식을 사용하는 것입니다. 예를 들어 다음 코드에서는 식을 사용하여 거품형 레이어의 색 속성을 기능의 myColor 속성으로 설정합니다.

var layer = new atlas.layer.BubbleLayer(source, null, {
    color: ['get', 'myColor']
});

위의 코드는 데이터 원본의 모든 기능에 myColor 속성이 있고 해당 속성의 값이 색인 경우 제대로 작동합니다. 데이터 원본의 데이터를 완벽하게 제어하고 모든 특정 기능이 myColor 속성에서 유효한 색을 가지는 경우에는 문제가 되지 않을 수 있습니다. 즉, 이 코드를 오류로부터 안전하게 만들기 위해 case 식을 has 식과 함께 사용하여 해당 기능에 myColor 속성이 있는지 확인할 수 있습니다. 이 경우 to-color 형식의 식을 사용하여 해당 속성의 값을 색으로 변환할 수 있습니다. 색이 잘못된 경우 대체 색을 사용할 수 있습니다. 다음 코드에서는 이 작업을 수행하고 대체 색을 녹색으로 설정하는 방법을 보여 줍니다.

var layer = new atlas.layer.BubbleLayer(source, null, {
    color: [
        'case',

        //Check to see if the feature has a 'myColor' property.
        ['has', 'myColor'],

        //If true, try validating that 'myColor' value is a color, or fallback to 'green'. 
        ['to-color', ['get', 'myColor'], 'green'],

        //If false, return a fallback value.
        'green'
    ]
});

부울 식을 가장 구체적인 식에서 가장 덜 구체적인 식으로 정렬

여러 조건부 테스트가 포함된 부울 식을 사용할 때 식을 가장 구체적인 것부터 덜 구체적인 것까지 정렬하여 필요한 조건부 테스트 수를 줄입니다.

식 단순화

식은 강력하고 때로는 복잡할 수 있습니다. 식이 단순할수록 계산 속도가 빨라집니다. 예를 들어 간단한 비교가 필요한 경우 ['==', ['get', 'category'], 'restaurant']와 같은 식은 ['match', ['get', 'category'], 'restaurant', true, false]와 같은 일치 식을 사용하는 것보다 낫습니다. 이 경우 확인할 속성이 부울 값이면 get 식이 훨씬 더 간단해집니다['get','isRestaurant'].

웹 SDK 문제 해결

다음은 Azure Maps 웹 SDK를 사용하여 개발할 때 발생하는 몇 가지 일반적인 문제를 디버깅하는 팁입니다.

웹 컨트롤을 로드할 때 맵이 표시되지 않는 이유는 무엇인가요?

검사 항목:

  • 맵에서 인증 옵션을 완료해야 합니다. 인증 없이 맵은 빈 캔버스를 로드하고 브라우저 개발자 도구의 네트워크 탭에서 401 오류를 반환합니다.
  • 인터넷에 연결되어 있는지 확인합니다.
  • 콘솔에서 브라우저의 개발자 도구의 오류에 대한 콘솔을 확인합니다. 일부 오류로 인해 맵이 렌더링되지 않을 수 있습니다. 애플리케이션을 디버그합니다.
  • 지원되는 브라우저를 사용하고 있는지 확인합니다.

모든 데이터가 지구 반대편에서 나타나는 이유는 무엇인가요?

Azure Maps SDK의 좌표(위치라고도 함)는 [longitude, latitude]의 지리 공간적 산업 표준 형식과 일치합니다. 이와 동일한 형식은 GeoJSON 스키마에서 좌표를 정의하는 방식이기도 하며, Azure Maps SDK 내에서 사용되는 핵심 데이터 형식입니다. 데이터가 지구 반대편에서 표시되는 경우에는 경도 및 위도 값이 좌표/위치 정보에서 반전되었기 때문일 수 있습니다.

웹 컨트롤에서 HTML 마커가 잘못된 위치에 나타나는 이유는 무엇인가요?

검사 항목:

  • 마커에 대해 사용자 지정 콘텐츠를 사용하는 경우 anchor 및 pixelOffset 옵션이 올바른지 확인합니다. 기본적으로 콘텐츠의 아래쪽 중심은 맵에서의 위치와 일치합니다.
  • Azure Maps에 대한 CSS 파일이 로드되었는지 확인합니다.
  • HTML 마커 DOM 요소를 검사하여 앱의 CSS가 표식에 추가되고 해당 위치에 영향을 주는지 확인합니다.

기호 레이어의 아이콘이나 텍스트가 잘못된 곳에 표시되는 이유는 무엇인가요?

anchor 및 offset 옵션이 맵의 좌표와 일치하게 하려는 이미지 또는 텍스트의 부분에 맞게 올바르게 구성되어 있는지 확인합니다. 맵이 회전되는 경우에만 기호가 제자리에 없으면 rotationAlignment 옵션을 체크합니다. 기본적으로 기호는 맵 뷰포트와 함께 회전하여 사용자에게 똑바로 나타납니다. 그러나 시나리오에 따라 rotationAlignment 옵션을 map로 설정하여 기호를 맵 방향으로 잠그는 것이 바람직할 수 있습니다.

맵이 경사진/기울어진 경우에만 기호가 제자리에 없으면 pitchAlignment 옵션을 체크합니다. 기본적으로 맵이 경사지거나 기울어져도 기호는 맵 뷰포트에서 똑바로 표시됩니다. 그러나 시나리오에 따라 pitchAlignment 옵션을 map로 설정하여 기호를 맵 피치로 잠그는 것이 바람직할 수 있습니다.

맵에 데이터가 나타나지 않는 이유는 무엇인가요?

검사 항목:

  • 브라우저의 개발자 도구에서 콘솔에 오류가 있는지 확인합니다.
  • 데이터 원본이 만들어지고 맵에 추가되었는지, 그리고 데이터 원본이 맵에 추가된 렌더링 레이어에 연결되어 있는지 확인합니다.
  • 코드에 중단점을 추가하고 단계별로 실행합니다. 데이터가 데이터 원본에 추가되고 데이터 원본 및 계층이 맵에 추가되는지 확인합니다.
  • 렌더링 레이어에서 데이터 기반 식을 제거합니다. 그중 하나에 문제가 있어 오류가 발생할 수 있습니다.

샌드박스가 적용된 iframe에서 Azure Maps 웹 SDK를 사용할 수 있나요?

예.

지원 받기

다음은 문제에 따라 Azure Maps에 대한 지원을 받는 다양한 방법입니다.

데이터 문제 또는 주소와 관련된 문제를 어떻게 보고하나요?

Azure Maps 피드백 사이트를 사용하여 문제를 보고합니다. 데이터 문제 보고에 대한 자세한 지침은 Azure Maps에 데이터 피드백 제공 문서에 나와 있습니다.

참고 항목

제출된 각 이슈는 고유한 URL을 생성하여 추적됩니다. 해결 시간은 문제 유형 및 변경 내용이 올바른지 확인하는 데 필요한 시간에 따라 달라집니다. 변경 내용은 Render Services 주간 업데이트에 표시되고 지오코딩 및 라우팅과 같은 다른 서비스는 매월 업데이트됩니다.

서비스 또는 API에서 버그를 어떻게 보고하나요?

지원 요청 만들기 단추를 선택하여 Azure의 도움말 + 지원 페이지에서 문제를 보고합니다.

Azure Maps에 대한 기술 도움말은 어디에서 볼 수 있나요?

  • Azure Maps Power BI 시각적 개체와 관련된 질문은 Power BI 지원에 문의하세요.

  • 다른 모든 Azure Maps 서비스에 대한 질문은 Azure 지원에 문의하세요.

  • 특정 Azure Maps 기능에 대한 질문이나 의견이 있는 경우 Azure Maps 개발자 포럼을 사용하세요.

다음 단계

애플리케이션에서 사용자 환경을 개선하는 방법에 대한 자세한 설명은 다음 문서를 참조하세요.

애플리케이션을 액세스할 수 있게 만들기

Azure Maps 및 지리 공간적 산업에서 사용하는 용어에 대해 자세히 알아보세요.

Azure Maps 용어집