Maps JavaScript API: API 키 또는 클라이언트 ID 가져오기

참고: Google Maps Platform 프리미엄 플랜은 신규 가입이 불가능하며 신규 고객에게 제공되지 않습니다.

인증 방식 선택

Maps JavaScript API를 사용하려면 다음 단계를 따르세요.

  • 프리미엄 플랜을 보유한 고객은 API 키 또는 클라이언트 ID를 사용하여 요청을 인증할 수 있습니다.
  • 이전 라이선스를 보유한 고객은 클라이언트 ID를 사용하여 요청을 인증해야 합니다.

인증 방법별로 다음과 같은 도구와 보고서를 사용할 수 있습니다.

  • API 키를 사용한 인증(프리미엄 플랜)
    API 키를 사용하여 요청을 인증하면 다음 작업이 가능합니다.
    • 모든 API를 Google Cloud Console의 API 페이지에서 관리합니다.
    • Cloud Console에서 실시간 사용 데이터 및 이전 30일간의 사용 데이터에 액세스합니다.
    • channel 매개변수를 요청에 추가하여 더 자세한 사용량 확인
    • Cloud Console에서 30일 이상 지난 데이터가 포함된 사용량 보고서를 조회합니다.
  • 클라이언트 ID(프리미엄 플랜 또는 이전 라이선스)
    클라이언트 ID를 사용하여 요청을 인증하면 다음 작업이 가능합니다.
    • channel 매개변수를 요청에 추가하여 더 자세한 사용량 확인
    • Cloud Console에서 30일 이상 지난 데이터가 포함된 사용량 보고서를 조회합니다.
    • Maps JavaScript API에 지도 애널리틱스 도구 사용

자세한 내용은 프리미엄 요금제 고객이 사용할 수 있는 보고서를 참고하세요.

API 키를 사용한 인증

API 키 만들기

API 키는 사용 및 결제 목적으로 프로젝트와 관련된 요청을 인증하는 고유 식별자입니다. 프로젝트에 연결된 API 키가 하나 이상 있어야 합니다.

API 키를 만들려면 다음 단계를 따르세요.

  1. Cloud Console의 프로젝트 선택기 페이지에서 API 키를 추가할 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기 페이지로 이동

    참고: 플랜의 모든 기능을 이용하려면 프리미엄 고객은 프리미엄 계정과 연결된 프로젝트를 사용해야 합니다. 라이선스를 구매할 때 프리미엄 애셋의 이름이 gme-[company] > proj-[number] ([type]) 형식으로 제공됩니다. 올바른 프로젝트에 액세스하고 있는지 확인하려면 console.cloud.google.com/project/number를 사용하여 프로젝트 소유자로 콘솔에 로그인하세요(number를 프로젝트 번호로 바꾸세요). 프로젝트 소유자는 환영 메일에서 찾을 수 있습니다.

  2. Google Maps Platform > 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동하기

  3. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 > API 키를 클릭합니다.
    API 키 생성 완료 대화상자에 새로 만든 API 키가 표시됩니다.
  4. 닫기를 클릭합니다.
    새 API 키는 사용자 인증 정보 페이지에서 API 키 아래에 표시됩니다.
    (프로덕션에 사용하기 전에 API 키를 제한하세요)

앱에 API 키 추가

모든 Google Maps Platform 요청에 API 키를 포함해야 합니다. 다음 예에서 YOUR_API_KEY를 API 키로 바꾸세요.

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

HTTPS는 API 키를 사용하는 요청에 필요하며 클라이언트 ID를 사용하는 요청에 권장됩니다. 사용자의 위치와 같은 민감한 사용자 데이터를 요청에 포함하는 애플리케이션에도 HTTPS가 필요합니다.

API 키 제한

API 키를 제한하면 승인된 요청만 API 키로 실행되기 때문에 애플리케이션 보안이 강화됩니다. 안내에 따라 API 키에 대한 제한을 설정하시기 바랍니다. 자세한 내용은 API 키 권장사항을 참고하세요.

API 키를 제한하는 방법은 다음과 같습니다.

  1. Google Maps Platform > 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동하기

  2. 제한을 설정할 API 키를 선택합니다. API 키 속성 페이지가 나타납니다.
  3. 키 제한사항에서 다음 제한사항을 설정합니다.
    • 애플리케이션 제한:
      1. 제공하는 웹사이트 목록에서 요청을 수락하려면 애플리케이션 제한사항 목록에서 HTTP 리퍼러(웹사이트)를 선택합니다.
      2. 리퍼러 웹사이트를 하나 이상 지정합니다. 예를 들어 *.google.com에서는 google.com으로 끝나는 모든 사이트(예: https://developers.google.com)가 허용됩니다.

        참고: file:// 리퍼러의 경우 특별한 표현을 키 제한에 추가해야 합니다. 'file://' 부분은 키 제한에 추가하기 전에 '__file_url__'로 바꿔야 합니다. 예를 들어 'file:///path/to/'는 '__file_url__//path/to/*'로 형식을 지정해야 합니다. file:// 리퍼러를 사용 설정한 후에는 사용량을 정기적으로 확인하여 예상과 일치하는지 확인하는 것이 좋습니다.

    • API 제한:
      1. 키 제한을 클릭합니다.
      2. API 선택 드롭다운에서 Google Maps Platform을 선택합니다. Google Maps Platform이 나열되지 않는 경우 사용 설정해야 합니다.
      3. 프로젝트에서 장소 라이브러리를 사용하는 경우 Places API도 선택합니다. 마찬가지로 프로젝트에서 JavaScript API의 다른 서비스(Directions 서비스, Distance Matrix 서비스, Elevation 서비스 또는 Geocoding 서비스)를 사용하는 경우 이 목록에서 해당 API를 사용 설정하고 선택해야 합니다.
  4. 변경사항을 완료하려면 저장을 클릭합니다.

클라이언트 ID를 사용한 인증

Google Maps Platform 프리미엄 플랜 라이선스를 구매하면 Google로부터 Google Maps Platform 프리미엄 플랜의 다양한 보고서와 도구를 이용하는 데 사용할 수 있는 클라이언트 ID가 포함된 환영 이메일을 받게 됩니다.

모든 클라이언트 ID는 gme-라는 접두어로 시작됩니다. 일반적인 클라이언트 ID의 형식은 다음과 같습니다.

gme-[company] > proj-[number] ([type])

클라이언트 ID를 API 키 대신 URL 등록과 함께 사용하여 Maps JavaScript API 요청을 인증할 수 있습니다.

참고: 이 클라이언트 ID는 키가 아니며 사용자가 승인한 URL에서만 사용할 수 있습니다. 승인된 URL 등록에 대해 자세히 알아보세요.

API를 로드할 때 클라이언트 ID 지정

아래 코드는 Maps JavaScript API를 로드할 때 YOUR_CLIENT_ID를 자신의 클라이언트 ID로 대체하는 방법을 보여줍니다.

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

v=quarterly 매개변수를 추가하여 출시 버전(feature-stable 버전이라고도 함) 또는 이전 버전을 지정해야 합니다. 시험용 버전을 사용하는 애플리케이션에는 Google Maps Platform 프리미엄 플랜 SLA가 적용되지 않습니다.

참고: 이전에 인증에 API 키를 사용하다가 클라이언트 ID로 전환하는 경우 API를 로드하기 전에 key 매개변수를 삭제해야 합니다. 클라이언트 ID와 API 키가 모두 포함되면 API가 로드되지 않습니다.

인증된 URL 등록

제3자가 자신의 웹사이트에서 사용자의 클라이언트 ID를 사용하지 못하도록 하기 위해 사용자의 클라이언트 ID는 사용자가 명시적으론 승인한 URL 목록에만 사용할 수 있습니다.

이미 승인한 URL을 확인하거나 추가 URL을 승인하려면 다음단계를 따르세요.

  1. Google Cloud Console에 로그인합니다.
  2. 왼쪽 메뉴에서 지도: 클라이언트 ID 관리를 클릭합니다.

URL은 한 번에 100개까지 추가할 수 있습니다. 클라이언트 ID에는 승인된 URL을 3,000개까지 연결할 수 있습니다. 애플리케이션이 3,000개가 넘는 곳에서 Google 지도 콘텐츠를 호스팅해야 한다면 API 키를 사용하도록 전환해야 합니다.

승인되는 URL과 관련하여 다음 사항을 고려하세요.

도메인 이름이나 IP 주소에 공개적으로 액세스할 수 없어도 됩니다.
예를 들어 http://myintranethttp://192.168.1.1는 유효한 항목입니다.
지정된 도메인의 모든 하위 도메인도 승인됩니다.
예를 들어 http://example.com이 승인되면 http://www.example.com도 승인됩니다. 그 반대는 사실이 아닙니다. http://www.example.com이 승인되어도 http://example.com도 반드시 승인되지는 않습니다.
승인된 경로의 모든 하위 경로도 승인됩니다.
예를 들어 http://example.com이 승인되면 http://example.com/foo도 승인됩니다. 또한 지정된 도메인의 하위 도메인도 승인되므로 http://sub.example.com/bar가 승인됩니다.
경로는 대/소문자를 구분합니다.
예를 들어 http://www.example.com/ThisPath/http://www.example.com/thispath/와 다릅니다.
유효한 경로를 특정한 포트를 사용하는 경로로 제한할 수도 있습니다.
예를 들어 http://example.com:8080/foo가 지정되면 http://example.com이 승인되지 않습니다.
HTTP 및 HTTPS 프로토콜은 다른 URL로 간주됩니다.
예를 들어 https://example.com이 승인되어도 http://example.com도 반드시 승인되지는 않습니다.

위의 모든 규칙은 각 승인에 적용되므로 승인을 신중하게 계획해야 합니다. 예를 들어 지정된 경로의 모든 하위 경로와 모든 하위 도메인이 승인되므로 의도하지 않았던 페이지가 승인될 수도 있습니다. 예:

http://example.com/이 승인되면 http://sub.example.com/path도 승인됩니다.

자세한 내용은 Google Maps Platform 프리미엄 플랜 URL 승인 문제 해결을 참고하세요.