Google Maps API 프리미엄 플랜 URL 승인 문제 해결

Google Maps API 프리미엄 플랜 클라이언트 ID는 승인된 특정 URL로 제한됩니다. 승인되지 않은 URL에서 클라이언트 ID를 사용하려고 시도할 경우 오류 메시지가 나타납니다.

이 문서는 이러한 문제가 발생하여 승인할 정확한 URL을 찾아야 하는 Google Maps API 프리미엄 플랜 고객을 대상으로 합니다.

기본 사항

제삼자가 자사 웹사이트에서 여러분의 클라이언트 ID를 사용하는 것을 막기 위해, 이 클라이언트 ID 사용은 여러분이 승인해야 하는 URL 목록으로 제한됩니다. 각 URL은 단일 웹 페이지 수준으로 구체적으로 지정하거나 전체 도메인 수준으로 포괄적으로 지정할 수 있습니다.

승인된 URL 목록을 얻거나 추가 URL을 승인하는 방법:

  1. Google Cloud Support Portal에 로그인합니다.
  2. 왼쪽 메뉴에서 Maps: Manage Client ID를 클릭합니다.

한 번에 최대 100개까지 총 3,000개의 URL을 추가할 수 있습니다. 한도를 늘려야 하는 경우 Google Cloud Support에 문의하세요.

URL 승인에 대한 자세한 내용은 개발자 가이드를 참조하세요.

문제

클라이언트 ID에 대해 승인되지 않은 URL에서 실행되는 애플리케이션은 클라이언트 ID로 Google Maps APIs를 사용할 수 없습니다. 이러한 애플리케이션을 사용하려는 사용자는 애플리케이션에서 로드하려는 API에 따라 오류 메시지를 받게 됩니다. 사용자는 Google Maps JavaScript API를 활용하는 기능을 사용할 수 없게 됩니다.

  • Google Maps JavaScript API는 다음과 같은 메시지를 표시합니다.

    이 페이지는 Google 지도 요소를 표시할 수 없습니다. 이 URL은 제공된 Google 지도 클라이언트 ID를 사용할 권한이 없습니다. Error Code: UnauthorizedURLForClientIdMapError

  • Google Maps JavaScript API v3.18 이전 버전을 사용하는 경우 다음 메시지가 표시됩니다.

    Google이 이 애플리케이션에 대해 Google Maps APIs 사용을 비활성화했습니다. 이 사이트는 제공된 Google Maps 클라이언트 ID를 사용할 권한이 없습니다. 이 애플리케이션의 소유자라면 개발자 가이드에서 URL 등록에 대한 자세한 내용을 참조하세요.

애플리케이션에서 클라이언트 ID를 제거하는 것은 올바른 수정 방법이 아닙니다*. 클라이언트 ID를 제거하면 해당 애플리케이션에서 Google Maps API 프리미엄 플랜이 제공하는 모든 혜택을 잃게 됩니다. 즉, 다음과 같은 혜택이 상실됩니다.

  • 안정적인 SLA(서비스 수준 계약).
  • 고객 지원.
  • 웹 서비스 한도 증가.
  • 상업적 목적의 사용 약관.
  • 직장 내 인트라넷 애플리케이션 지원.

따라서 내부용이거나 무료가 아니고 유효한 Google Maps API 프리미엄 플랜 클라이언트 ID를 올바르게 사용하지 않는 애플리케이션은 무료 Google Maps APIs 서비스 약관을 준수하지 못하게 됩니다.

해결 방법

이 문제를 올바르게 해결하는 방법은 클라이언트 ID를 사용할 적절한 URL을 찾아서 승인하는 것입니다.

대부분의 경우, 클라이언트 ID를 사용할 애플리케이션을 승인해야 합니다. 일반적으로 애플리케이션은 공통 패턴을 공유하는 여러 개의 URL을 사용합니다. 예를 들어, 스토어 로케이터는 example.com/stores 또는 stores.example.com에서 실행될 수 있습니다. 애플리케이션이 사용하는 모든 URL과 일치하는 URL을 찾아야 합니다.

참고: www.example.com을 승인하더라도 stores.example.com이나 example.com의 다른 하위 도메인은 승인되지 않습니다.

여러분이 승인하는 각 URL은 단일 웹 페이지 수준으로 구체적으로 지정하거나 하위 도메인을 포함한 전체 도메인 수준으로 포괄적으로 지정할 수 있습니다. 자세한 내용은 개발자 가이드를 참조하세요. 여러분이 관리하는 것 중에서 상당히 광범위한 URL 세트와 일치하는 URL을 승인하는 것이 좋습니다.

참고: 여러분의 조직이 해당 도메인 콘텐츠 전체를 완벽히 제어하지 않는 한, 전체 도메인은 승인하지 않는 것이 좋습니다. 예를 들어, blogspot.com 도메인 전체를 승인하면 모든 사람이 해당 도메인에서 여러분이 낸 비용으로 여러분의 클라이언트 ID를 사용할 수 있습니다. 특정 블로그(예: googlegeodevelopers.blogspot.com) 또는 해당 블로그의 특정 페이지만 승인하는 것이 좋습니다.

올바른 URL을 찾는 방법

일반적으로는 브라우저 위치 표시줄에서 URL을 찾습니다. <iframe> 태그를 사용하지 않는 공개 웹사이트에서는 상당히 쉽게 찾을 수 있습니다. 확신하기 어려울 경우, 아래의 방법을 사용하여 확인해보세요.

복잡한 애플리케이션은 사용자 위치 표시줄에 있는 URL이 아닌 곳에서 Google Maps APIs를 로드할 수 있습니다. <iframe> 태그를 사용하거나 API를 로드하는 페이지의 URL이 서버에서 동적으로 생성된 다음 브라우저로 전송되었을 때 이런 상황이 발생합니다. 이 경우 올바른 URL을 찾으려면 브라우저에서 Google 서버로 보내는 특정한 HTTP 요청을 조사해야 합니다.

승인할 필요가 있는 URL은 브라우저가 API를 로드하기 위해 Google에 보내는 요청의 Referer 헤더에 포함된 URL입니다. 각 API는 다른 URL에서 로드됩니다.

maps.googleapis.com에 대한 모든 요청은 애플리케이션에서 설정된 API 로드 방식에 따라 maps.google.com이나 maps-api-ssl.google.com으로 전송됩니다. 따라서 일반적으로 중요한 경로(굵은 글꼴)에서 위의 요청을 찾아야 합니다.

브라우저의 HTTP 헤더

위의 요청에서 Referer 헤더를 조사하기 전에 브라우저에서 헤더를 캡처해야 합니다. 모든 주요 브라우저에서 HTTP 헤더를 캡처하기 위한 여러 가지 도구를 무료로 제공하고 있습니다.

참고: HTTPS 트래픽을 캡처하려면 Fiddler2를 구성해야 합니다. 자세한 내용은 여기를 참조하세요.

브라우저에서 직접 HTTP 헤더를 캡처하지 못할 경우, Wireshark와 같은 네트워크 프로토콜 분석기를 사용하여 HTTP 트래픽을 캡처할 수 있습니다. 이 도구는 위에서 언급한 도구보다 사용 방법이 더욱 복잡할 수 있습니다. 친숙하지 않다면 웹에서 몇 가지 Wireshark 튜토리얼을 찾아보세요.

원하는 도구를 선택했다면 다음 절차에 따라 승인이 필요한 URL을 찾습니다.

  1. 캡처 도구를 시작합니다. 브라우저에서 HTTP 요청을 캡처하는지 확인합니다.
  2. 브라우저가 클라이언트 ID를 사용하여 Google Maps APIs를 로드하지 못하는 애플리케이션을 가리키게 합니다. 위에서 설명한 오류 메시지 중 하나가 나타나야 합니다.
  3. HTTP 트래픽 캡처를 중단합니다. 그러면 캡처된 트래픽을 쉽게 조사할 수 있습니다.
  4. 클라이언트 ID로 Google Maps APIs를 로드하려는 요청을 찾습니다. 예를 들어 애플리케이션이 Google Maps JavaScript API를 로드하려고 한다면 다음과 같은 요청을 찾습니다.
    GET /maps/api/js?client=gme-yourclientid HTTP/1.1
  5. 줄바꿈 없이 이 줄 바로 뒤에 HTTP 요청 헤더가 이어집니다. 다음과 같은 내용을 찾습니다.
    Referer: http://www.example.com/stores/find?zip=94043
  6. 이 줄에 있는 URL이 클라이언트 ID를 사용하도록 승인해야 하는 URL입니다.

브라우저의 JavaScript 콘솔

권한이 없는 사이트에서 API 키 또는 클라이언트 ID를 사용하면 Google Maps JavaScript API가 window.console에 오류 메시지를 기록합니다. 오류 메시지에서 올바른 URL을 찾을 수 있습니다. 콘솔에서 다음과 같은 오류 메시지를 찾습니다.

Google Maps APIs error: UnauthorizedURLForClientIdMapError ...
Your site URL to be authorized: http://www.example.com/stores/find?zip-94043

오류 메시지를 찾는 방법에 대해서는 브라우저에서 오류 확인 섹션을 참조하세요.

공통 패턴 찾기

전체 애플리케이션이 클라이언트 ID를 사용하여 Google Maps APIs를 로드할 수 있게 하려면 애플리케이션이 사용하는 모든 URL에서 공통 패턴을 찾고 개발자 가이드에서 설명한 규칙에 따라 이러한 패턴을 대표하는 URL을 승인해야 합니다.

디렉토리(예: example.com/stores)나 하위 도메인(예: stores.example.com)처럼 간단한 형태인 경우가 많습니다. 대개는 몇 개의 URL에서 쉽게 추론할 수 있습니다.

복잡한 애플리케이션을 다룰 때는 사용자가 사용하는 지도 표시 URL 여러 개에서 위의 절차를 반복해야 할 수도 있습니다. 그러나 이러한 작업은 너무 복잡하고 불완전한 URL 집합이 나올 수도 있습니다. 복잡한 애플리케이션의 경우 개발자가 URL 패턴을 제공하는 것이 가장 좋습니다.