클라이언트 ID 이전 가이드

개요

인증 보안 및 안정성을 높이기 위해 2025년 5월 26일부터 Maps Platform 클라이언트 ID가 지원 중단되었으며 2026년 5월 31일 이후에는 더 이상 사용할 수 없습니다.

클라이언트 ID 대신 API 키 사용자 인증 정보를 사용하여 Google Maps API 서비스 트래픽을 인증해야 합니다. 이 가이드에서는 클라이언트 ID 사용에서 API 키 사용으로 이전하는 방법을 보여줍니다.

시작하려면 다음 단계를 따르세요.

  1. 현재 클라이언트 ID 사용량 확인하기
  2. API 키 준비하기
  3. 할당량 설정 검토
  4. 코드 업데이트
  5. 클라이언트 ID 트래픽 모니터링
  6. 클라이언트 ID 일시중지하기

현재 클라이언트 ID 사용량 확인

이전 프로세스를 시작하기 전에 다음을 나열하세요.

  • 클라이언트 ID와 함께 사용 중인 Maps Platform 서비스
  • 클라이언트 ID를 사용하는 애플리케이션, 사이트 또는 시스템입니다.

Google은 2025년 5월에 클라이언트 ID 지원 중단에 대해 영향을 받는 고객에게 알림 이메일을 보냈습니다. 이 정보는 알림 이메일에서도 확인할 수 있습니다.

Cloud 콘솔의 Google 지도 측정항목 페이지에서 클라이언트 ID 사용의 최신 상태를 확인할 수 있습니다.

Maps Platform 서비스 목록:

  1. Cloud Console에서 측정항목 페이지를 엽니다.
  2. 다음 설정을 사용하여 사용량을 필터링합니다.
    • 사용자 인증 정보: 'project_number:<숫자 식별자>"만 선택합니다.
  3. 다음 필터를 설정합니다.
    • 그룹화 기준: API

애플리케이션, 사이트 또는 시스템 힌트:

Cloud 콘솔에는 애플리케이션, 사이트 또는 시스템의 세부정보가 표시되지 않습니다. 하지만 클라이언트 ID 트래픽의 소스에 관한 몇 가지 힌트를 찾을 수 있습니다. 다음 단계를 따르세요.

  1. Cloud Console에서 측정항목 페이지를 엽니다.
  2. 드롭다운에서 Maps Platform 서비스를 선택합니다.
  3. 다음 설정을 사용하여 사용량을 필터링합니다.
    • 사용자 인증 정보: 'project_number:<숫자 식별자>"만 선택합니다.
  4. 다음 필터를 설정합니다.
    • 그룹화 기준: 플랫폼 또는 도메인
  5. 트래픽을 확인해야 하는 각 Maps Platform 서비스에 대해 2단계부터 반복합니다.

API 키 준비

모든 클라이언트 ID는 Google Cloud 프로젝트와 연결되며, 해당 프로젝트의 API 키를 사용하면 이전에 클라이언트 ID로 액세스한 것과 동일한 기능에 액세스할 수 있습니다. 할당량 문제 또는 누락된 기능을 방지하려면 연결된 프로젝트로 이전하는 것이 좋습니다.

  1. 클라이언트 ID가 연결된 Cloud 프로젝트를 찾습니다.
  2. Cloud 프로젝트가 사용 가능한 결제 계정에 연결되어 있는지 확인합니다.
  3. 클라이언트 ID 이전을 위해 새 API 키를 만듭니다.
    • Cloud 프로젝트에서 기존 API 키를 재사용할 수 있습니다.
    • 예를 들어 각 Maps Platform 서비스의 트래픽을 분리하거나 여러 플랫폼 (브라우저, 모바일 앱 등)의 트래픽을 분리하기 위해 동일한 Cloud 프로젝트에서 여러 API 키를 사용할 수 있습니다. API 키 관리에 관한 권장사항은 보안 가이드를 참고하세요.

API 키 보호

API 키를 무단 액세스로부터 보호하려면 API 키를 안전하게 보호해야 합니다.

  • API 키에 애플리케이션 제한사항 (예: 웹사이트, IP 주소, Android 앱 또는 iOS 앱)을 설정합니다.
  • API 키에 API 제한사항을 설정합니다.

자세한 내용은 Google Maps Platform 보안 가이드를 참고하세요.

Maps JavaScript API, Maps Static API, Street View Static API의 경우 클라이언트 ID의 신뢰할 수 있는 리퍼러를 API 키 제한으로 이전할 수 있습니다. Cloud Console에서 신뢰할 수 있는 추천 사이트 목록을 확인할 수 있습니다.

할당량 설정 검토

Cloud 프로젝트에 예상되는 할당량 설정이 있는지 확인합니다. 클라이언트 ID에서 Maps JavaScript API 클라이언트 측 서비스를 호출하는 경우에만 이 작업을 실행하면 됩니다. Google 지도 할당량 페이지에서 할당량 설정을 확인하고 조정할 수 있습니다.

할당량 보고서 자세히 알아보기

Maps JavaScript API 클라이언트 측 서비스의 할당량 증가

Maps JavaScript API에서 다음 서비스를 사용하는 경우 API 키 이전 후 할당량 사용량이 증가합니다.

현재 할당량 구성, 현재 사용량을 검토하고 해당에 따라 할당량 한도를 조정합니다.

  1. 클라이언트 ID로 Maps JavaScript API 클라이언트 측 서비스를 사용하고 있는지 확인합니다.
    • Cloud Console에서 측정항목 페이지를 엽니다.
    • 다음 설정을 사용하여 사용량을 필터링합니다.
      • 그룹화 기준: API 메서드
      • 사용자 인증 정보: 'project_number:<숫자 식별자>"만 선택합니다.
    • 그러면 'API 메서드별 트래픽' 차트에 트래픽과 함께 메서드 이름 목록이 표시됩니다.

API 메서드

클라이언트 측 서비스

할당량을 조정하는 서비스

google.routes.Directions.Javascript

경로 서비스

Directions API

google.routes.DistanceMatrix.Javascript

거리 행렬 서비스

Distance Matrix API

google.maps.Elevation.Javascript

고도 서비스

Elevation API

google.places.Geocoding.Javascript

지오코딩 서비스

Geocoding API

google.places.*.Javascript(google.places.Geocoding.Javascript 제외)

장소 라이브러리

Places API
  • 이러한 API 메서드를 사용하지 않는 경우 클라이언트 ID 트래픽이 이미 프로젝트 할당량을 사용하고 있으므로 할당량 설정에 관해 걱정할 필요가 없습니다.
  • 클라이언트 ID 할당량 사용량 추정
    • 각 서비스의 경우 '초당' 및 '일일' 세부사항을 모두 선택합니다.
    • 초당 그래프: 최대 트래픽에 60을 곱하여 분당 할당량 추가 필요량을 확인합니다.
    • 일일 그래프: 최대 트래픽은 일일 추가 할당량 요구사항입니다.
  • 해당 Maps Platform 서비스에서 할당량을 조정합니다.
    • 1단계에서 찾은 메서드 이름을 기반으로 해당 서비스의 할당량을 조정합니다.

코드 업데이트

발신 GMP API 호출에서 인증 사용자 인증 정보를 URL&client={value}에서 URL&key={value}로 업데이트합니다. 앱에서 HTTP를 사용하여 GMP 서비스에 액세스하는 경우 HTTPS를 사용하도록 업데이트합니다.

웹 서비스의 서명 매개변수 삭제

웹 서비스 API (*)의 경우 API 키로 액세스할 때 서명 매개변수가 필요하지 않습니다. API 요청에서 서명 매개변수만 삭제합니다.

  • Directions API (기존)
  • Distance Matrix API (기존)
  • Geocoding API
  • Elevation API
  • Time Zone API

자세한 내용은 프리미엄 요금제 개요를 참고하세요.

Imagery API의 서명 보안 비밀

Maps Static API 및 Street View Static API에는 여전히 서명 매개변수가 필요합니다. 테스트 목적으로 서명 없이 소수의 요청을 허용하지만 프로덕션에서 임곗값에 도달하면 실패하기 시작합니다. 서명 비밀을 클라이언트 ID용 비밀에서 API 키용 비밀로 바꿉니다. 동일한 서명 알고리즘을 사용할 수 있지만 다른 서명 비밀을 사용해야 합니다. 자세한 내용은 디지털 서명 사용을 참고하세요.

클라이언트 ID 트래픽 모니터링

배포 후 Cloud 콘솔 대시보드를 사용하여 트래픽이 성공적으로 이전되었는지 확인합니다. 사용자 인증 정보별로 그룹화할 때 대시보드에 'project_number:123456' 형식으로 표시되는 클라이언트 ID 트래픽이 감소하기 시작합니다.

클라이언트 ID 일시중지

개발자는 이전 후 클라이언트 ID를 일시중지하는 것이 좋습니다. 의도하지 않은 트래픽으로부터 사용자 인증 정보를 보호하고 클라이언트 ID의 남은 사용량이 중요하지 않으며 (예: 테스트, 캐시, 봇 등) 비즈니스 영향 없이 오류를 반환할 수 있는지 확인하기 위함입니다. Cloud 콘솔에서 클라이언트 ID를 일시중지할 수 있습니다. 자세한 내용은 프리미엄 요금제 인증 개요를 참고하세요.

문제 해결

요청이 실패했는지 여부는 어떻게 알 수 있나요?

응답 코드 그래프에서 오류 통계를 확인할 수 있습니다.

ApiNotActivatedMapError 또는 REQUEST_DENIED 오류

Cloud 프로젝트에서 서비스를 사용 설정하지 않은 경우 ApiNotActivatedMapError 또는 REQUEST_DENIED 오류가 표시됩니다. 안내에 따라 서비스를 사용 설정합니다.

오류 RefererNotAllowedMapError개

소스 도메인이 API 키에 추가되지 않은 경우 RefererNotAllowedMapError 오류가 표시됩니다. 'API 키 보호' 섹션을 선택하고 API 키에 도메인을 추가합니다.

OverQuotaMapError 또는 OVER_QUERY_LIMIT 오류

구성된 할당량이 트래픽을 처리하기에 충분하지 않으면 OverQuotaMapError 또는 OVER_QUERY_LIMIT이 표시됩니다. '할당량 설정 검토' 섹션을 확인하고 할당량을 적절하게 조정합니다.

'이 API에 대한 요청은 SSL을 통해 이루어져야 합니다.' 오류

다음과 같은 오류 메시지가 표시되면 API 요청을 'http://'에서 'https://'으로 업데이트합니다.

{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}