Maps JavaScript API 애플리케이션을 v2에서 v3으로 업그레이드

2021년 5월 26일부터 Maps JavaScript API v2를 더 이상 사용할 수 없습니다. 따라서 사이트의 v2 지도 작동이 중지되고 JavaScript 오류가 반환됩니다. 사이트에서 지도를 계속 사용하려면 Maps JavaScript API v3으로 이전하세요. 이 가이드를 참고하여 이 과정을 진행하세요.

개요

모든 애플리케이션의 이전 프로세스는 약간 다르지만 모든 프로젝트에 공통적인 몇 가지 단계가 있습니다.

  1. 새 키를 받습니다. 이제 Maps JavaScript API는 Google Cloud 콘솔을 사용하여 키를 관리합니다. 아직 v2 키를 사용하고 있다면 이전을 시작하기 전에 새 API 키를 가져와야 합니다.
  2. API 부트스트랩을 업데이트합니다. 대부분의 애플리케이션은 다음 코드로 Maps JavaScript API v3을 로드합니다.
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. 코드를 업데이트합니다. 필요한 변경사항의 양은 애플리케이션에 따라 크게 달라집니다. 일반적인 변경사항은 다음과 같습니다.
    • 항상 google.maps 네임스페이스를 참조합니다. v3에서는 모든 Maps JavaScript API 코드가 전역 네임스페이스 대신 google.maps.* 네임스페이스에 저장됩니다. 이 과정에서 대부분의 객체 이름도 변경되었습니다. 예를 들어 이제 GMap2 대신 google.maps.Map를 로드합니다.
    • 사용하지 않는 메서드에 대한 참조를 삭제합니다. GDownloadURLGLog와 같은 여러 범용 유틸리티 메서드가 삭제되었습니다. 이 기능을 서드 파티 유틸리티 라이브러리로 대체하거나 코드에서 이러한 참조를 삭제합니다.
    • (선택사항) 코드에 라이브러리를 추가합니다. 각 앱에서 사용될 API 부분만 로드하면 되도록 많은 기능이 유틸리티 라이브러리로 외부화되었습니다.
    • (선택사항) v3 externs를 사용하도록 프로젝트를 구성합니다. v3 extern은 Closure 컴파일러로 코드의 유효성을 검사하거나 IDE에서 자동 완성을 트리거하는 데 사용할 수 있습니다. 고급 컴파일 및 외부 참조에 대해 자세히 알아보세요.
  4. 테스트하고 반복하세요. 이 시점에서 아직 할 일이 남아 있지만 좋은 소식은 새 v3 지도 애플리케이션을 만드는 데 한 걸음 더 다가가게 되었다는 것입니다.

Maps JavaScript API V3의 변경사항

이전을 계획하기 전에 Maps JavaScript API v2와 Maps JavaScript API v3의 차이점을 이해하는 데 시간을 할애해야 합니다. 최신 버전의 Maps JavaScript API는 최신 JavaScript 프로그래밍 기법, 라이브러리 사용 증가, 간소화된 API에 중점을 두고 처음부터 다시 작성되었습니다. API에 많은 새로운 기능이 추가되었으며 익숙한 기능 중 일부가 변경되거나 삭제되었습니다. 이 섹션에서는 두 버전 간의 주요 차이점을 설명합니다.

v3 API 변경 사항:

  • 핵심 라이브러리가 간소화되었습니다. 많은 보조 함수가 라이브러리로 이동되어 Core API의 로드 및 파싱 시간이 줄어들고 모든 기기에서 지도가 빠르게 로드됩니다.
  • 다각형 렌더링, 마커 배치와 같은 여러 기능의 성능이 개선되었습니다.
  • 모바일 프록시 및 기업 방화벽에서 사용하는 공유 주소를 더 잘 수용하기 위한 클라이언트 측 사용량 한도에 대한 새로운 접근 방식입니다.
  • 여러 최신 브라우저 및 모바일 브라우저에 대한 지원을 추가했습니다. Internet Explorer 6 지원이 삭제되었습니다.
  • 많은 범용 도우미 클래스( GLog 또는 GDownloadUrl)를 삭제했습니다. 오늘날 Closure 또는 jQuery와 같이 유사한 기능을 제공하는 우수한 JavaScript 라이브러리가 많이 있습니다.
  • 모든 모바일 기기에서 로드되는 HTML5 스트리트 뷰가 구현되었습니다.
  • 직접 찍은 사진으로 맞춤 스트리트 뷰 파노라마를 만들어 스키장, 매물 주택 또는 기타 흥미로운 장소의 파노라마를 공유할 수 있습니다.
  • 스타일 지도가 적용된 지도 맞춤설정을 사용하면 기본 지도의 요소 표시를 고유한 시각적 스타일에 맞게 변경할 수 있습니다.
  • ElevationServiceDistance Matrix와 같은 여러 새로운 서비스 지원
  • 개선된 경로 서비스는 대체 경로, 경로 최적화 ( 여행하는 영업사원 문제의 근사 솔루션), 자전거 경로 ( 자전거 레이어 포함), 대중교통 경로, 드래그 가능한 경로를 제공합니다.
  • Geocoding API v2의 accuracy 값보다 더 정확한 유형 정보를 제공하는 업데이트된 Geocoding 형식입니다.
  • 단일 지도에 여러 정보 창 지원

애플리케이션 업그레이드

새로운 키

Maps JavaScript API v3은 v2의 새로운 키 시스템을 사용합니다. 애플리케이션에서 이미 v3 키를 사용하고 있을 수 있으며, 이 경우 변경할 필요가 없습니다. 확인하려면 Maps JavaScript API를 로드하는 URL에서 key 매개변수를 확인하세요. 키 값이 'ABQIAA'로 시작하면 v2 키를 사용하고 있는 것입니다. v2 키가 있는 경우 마이그레이션의 일환으로 v3 키로 업그레이드해야 합니다. 업그레이드하면 다음과 같은 이점이 있습니다.

키는 Maps JavaScript API v3을 로드할 때 전달됩니다. API 키 생성에 대해 자세히 알아보기

업무용 Google 지도 API 고객인 경우 key 매개변수 대신 client 매개변수와 함께 클라이언트 ID를 사용하고 있을 수 있습니다. 클라이언트 ID는 Maps JavaScript API v3에서 계속 지원되며 키 업그레이드 프로세스를 거칠 필요가 없습니다.

API 로드

코드에서 먼저 수정해야 할 사항은 API를 로드하는 방법입니다. v2에서는 http://maps.google.com/maps 요청을 통해 Maps JavaScript API를 로드합니다. Maps JavaScript API v3를 로드하는 경우 다음과 같이 변경해야 합니다.

  1. //maps.googleapis.com/maps/api/js에서 API 로드
  2. file 매개변수를 삭제합니다.
  3. 새 v3 키로 key 매개변수를 업데이트합니다. 업무용 Google 지도 API 고객은 client 매개변수를 사용해야 합니다.
  4. (Google Maps Platform 프리미엄 요금제만 해당) client 매개변수가 Google Maps Platform 프리미엄 요금제 개발자 가이드에 설명된 대로 제공되는지 확인합니다.
  5. v 매개변수를 삭제하여 최신 출시 버전을 요청하거나 v3 버전 관리 스킴에 따라 값을 변경합니다.
  6. (선택사항) hl 매개변수를 language로 바꾸고 값을 유지합니다.
  7. (선택사항) libraries 매개변수를 추가하여 선택적 라이브러리를 로드합니다.

가장 간단한 경우 v3 부트스트랩은 API 키 매개변수만 지정합니다.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

아래 예에서는 독일어로 최신 버전의 Maps JavaScript API v2를 요청합니다.

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

아래 예시는 v3 요청과 같습니다.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

google.maps 네임스페이스 도입

Maps JavaScript API v3에서 가장 눈에 띄는 변경사항은 google.maps 네임스페이스의 도입일 것입니다. v2 API는 기본적으로 모든 객체를 전역 네임스페이스에 배치하므로 이름 충돌이 발생할 수 있습니다. v3 내에서 모든 객체는 google.maps 네임스페이스 내에 있습니다.

애플리케이션을 v3로 이전할 때는 새 네임스페이스를 활용하도록 코드를 변경해야 합니다. 안타깝게도 'G'를 검색하여 'google.maps'로 대체해도 완전히 작동하지는 않습니다. 하지만 코드를 검토할 때 적용할 만한 좋은 경험칙입니다. 다음은 v2와 v3의 상응하는 클래스의 몇 가지 예입니다.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

사용하지 않는 코드 제거

Maps JavaScript API v3에는 v2의 대부분의 기능에 상응하는 기능이 있습니다. 하지만 더 이상 지원되지 않는 클래스도 있습니다. 이전의 일환으로 이러한 클래스를 서드 파티 유틸리티 라이브러리로 대체하거나 코드에서 이러한 참조를 삭제해야 합니다. Closure 또는 jQuery와 같이 유사한 기능을 제공하는 우수한 JavaScript 라이브러리가 많이 있습니다.

다음 클래스는 Maps JavaScript API v3에 상응하는 클래스가 없습니다.

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

코드 비교

v2 및 v3 API로 작성된 비교적 간단한 두 애플리케이션을 비교해 보겠습니다.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

보시다시피 두 애플리케이션에는 몇 가지 차이점이 있습니다. 눈에 띄는 변경 사항은 다음과 같습니다.

  • API를 로드하는 주소가 변경되었습니다.
  • GBrowserIsCompatible()GUnload() 메서드는 v3에서 더 이상 필요하지 않으며 API에서 삭제되었습니다.
  • GMap2 객체가 API의 중앙 객체로 google.maps.Map로 대체됩니다.
  • 속성이 옵션 클래스를 통해 로드됩니다. 위 예에서는 삽입된 MapOptions 객체를 통해 지도 로드에 필요한 세 가지 속성(center, zoom, mapTypeId)을 설정했습니다.
  • v3에서는 기본 UI가 기본값입니다. MapOptions 객체에서 disableDefaultUI 속성을 true로 설정하여 사용 중지할 수 있습니다.

요약

이제 Maps JavaScript API의 v2에서 v3로 이전하는 데 관련된 몇 가지 주요 사항을 살펴봤습니다. 알아야 할 정보가 더 있지만 이는 애플리케이션에 따라 다릅니다. 다음 섹션에는 발생할 수 있는 특정 케이스에 대한 이전 안내가 포함되어 있습니다. 또한 업그레이드 프로세스 중에 유용할 수 있는 몇 가지 리소스도 있습니다.

  • Maps JavaScript API v3 개발자 문서는 API와 작동 방식에 대해 자세히 알아볼 수 있는 최고의 리소스입니다.
  • Maps JavaScript API v3 참조를 통해 v3 API의 새로운 클래스와 메서드에 관해 자세히 알아볼 수 있습니다.
  • Stack Overflow 커뮤니티는 코드 관련 질문을 할 수 있는 좋은 장소입니다. 사이트에서 Maps JavaScript API와 관련된 질문과 답변에는 'google-maps' 또는 'google-maps-api-3' 태그가 사용됩니다.
  • Google Maps Platform 프리미엄 요금제 고객은 Google Maps Platform 프리미엄 요금제 문서를 읽어보세요.
  • Google Geo 개발자 블로그에서 API의 최신 변경사항을 확인할 수 있습니다.

이 도움말과 관련하여 문제가 있거나 궁금한 점이 있으면 이 페이지 상단의 의견 보내기 링크를 사용하세요.

상세 참조

이 섹션에서는 Maps JavaScript API의 v2 및 v3에서 가장 많이 사용되는 기능을 자세히 비교합니다. 참조의 각 섹션은 개별적으로 읽을 수 있도록 설계되었습니다. 이 참조를 전체적으로 읽지 않는 것이 좋습니다. 대신 이 자료는 경우에 따라 이전을 돕는 데 사용하세요.

  • 이벤트 - 이벤트를 등록하고 처리합니다.
  • 컨트롤 - 지도에 표시되는 탐색 컨트롤을 조작합니다.
  • 오버레이 - 지도에 객체를 추가하고 수정합니다.
  • 지도 유형: 기본 지도를 구성하는 타일입니다.
  • 레이어 - KML 또는 트래픽 레이어와 같은 콘텐츠를 그룹으로 추가하고 수정합니다.
  • 서비스 - Google의 지오코딩, 경로 또는 스트리트 뷰 서비스를 사용합니다.

이벤트

Maps JavaScript API v3의 이벤트 모델은 v2에서 사용된 모델과 유사하지만 내부적으로 많은 부분이 변경되었습니다.

컨트롤

Maps JavaScript API는 사용자가 지도와 상호작용할 수 있는 UI 컨트롤을 표시합니다. API를 사용하여 이러한 컨트롤이 표시되는 방식을 맞춤설정할 수 있습니다.

오버레이

오버레이는 지도에 '추가'하여 점, 선, 영역 또는 객체의 모음을 지정하는 객체를 반영합니다.

지도 유형

v2와 v3에서 사용할 수 있는 지도 유형은 약간 다르지만 모든 기본 지도 유형은 두 API 버전에서 모두 사용할 수 있습니다. 기본적으로 v2는 표준 '페인팅된' 도로 지도 타일을 사용합니다. 그러나 v3에서는 google.maps.Map 객체를 만들 때 특정 맵 유형을 제공해야 합니다.

레이어

레이어는 하나 이상의 오버레이로 구성된 지도상의 객체입니다. 단일 단위로 조작할 수 있으며 일반적으로 객체 모음을 반영합니다.

서비스