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

Maps JavaScript API v2는 2021년 5월 26일부터 더 이상 사용할 수 없습니다. 따라서 사이트의 v2 지도 작동이 중지되고 자바스크립트 오류가 반환됩니다. 사이트에서 지도를 계속 사용하려면 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 extern을 사용하도록 프로젝트를 구성합니다. v3 extern은 클로저 컴파일러로 코드의 유효성을 검사하거나 IDE에서 자동 완성을 트리거하는 데 사용할 수 있습니다. 고급 컴파일 및 Extern에 대해 자세히 알아보세요.
  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)가 많이 삭제되었습니다. 오늘날 유사한 기능을 제공하는 훌륭한 자바스크립트 라이브러리(예: 클로저 또는 jQuery)가 많이 있습니다.
  • 모든 모바일 기기에서 로드되는 HTML5 스트리트 뷰가 구현되었습니다.
  • 내 사진이 있는 맞춤 스트리트 뷰 파노라마를 사용하여 스키 슬로프, 매매용 주택, 기타 흥미로운 장소를 공유할 수 있습니다.
  • 스타일 지도 맞춤설정 - 고유한 시각적 스타일에 맞게 기본 지도의 요소 표시를 변경할 수 있습니다.
  • ElevationServiceDistance Matrix와 같은 몇 가지 새로운 서비스 지원
  • 개선된 경로 서비스는 대체 경로, 경로 최적화 ( 순회 영업사원 문제에 대한 대략적인 해결책), 자전거 경로 ( 자전거 레이어 사용), 대중교통 경로 및 드래그 가능한 경로를 제공합니다.
  • Geocoding API v2의 accuracy 값보다 더 정확한 유형 정보를 제공하는 업데이트된 지오코딩 형식입니다.
  • 단일 지도에서 여러 정보 창 지원

애플리케이션 업그레이드

새로운 키

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

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

Google Maps API for Work 고객의 경우 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 Maps API for Work 고객은 client 매개변수를 사용해야 합니다.
  4. (Google Maps Platform 프리미엄 플랜만 해당) Google Maps Platform 프리미엄 플랜 개발자 가이드에 설명된 대로 client 매개변수를 제공해야 합니다.
  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의 기능과 대부분 동일하지만 더 이상 지원되지 않는 클래스도 있습니다. 이전의 일환으로 이러한 클래스를 서드 파티 유틸리티 라이브러리로 대체하거나 코드에서 이러한 참조를 삭제해야 합니다. 클로저jQuery 같이 비슷한 기능을 제공하는 여러 뛰어난 자바스크립트 라이브러리가 있습니다.

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로 대체됩니다.
  • 속성이 옵션 클래스를 통해 로드됩니다. 위의 예에서는 지도를 로드하는 데 필요한 세 가지 속성(center, zoom, mapTypeId)을 인라인 MapOptions 객체를 통해 설정합니다.
  • v3에서는 기본 UI가 기본값입니다. MapOptions 객체에서 disableDefaultUI 속성을 true로 설정하여 이를 사용 중지할 수 있습니다.

요약

이제 Maps JavaScript API v2에서 v3으로 이전하는 것과 관련된 몇 가지 핵심 사항을 살펴보았습니다. 알아야 할 추가 정보가 있지만 이는 애플리케이션에 따라 다릅니다. 다음 섹션에는 발생할 수 있는 특정 사례에 대한 마이그레이션 안내가 포함되어 있습니다. 또한 업그레이드 프로세스 중에 도움이 될 수 있는 몇 가지 리소스가 있습니다.

  • Maps JavaScript API v3 개발자 문서에서 API와 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 객체를 만들 때 특정 지도 유형을 지정해야 합니다.

레이어

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

서비스