개요
시작하려면 다음 단계를 따르세요.
- 현재 클라이언트 ID 사용량 확인
- API 키 준비
- 할당량 설정 검토
- 코드 업데이트
- 클라이언트 ID 트래픽 모니터링하기
- 클라이언트 ID 일시중지하기
- 클라이언트 ID 셀프 서비스 임시 재활성화
현재 클라이언트 ID 사용량 확인
마이그레이션 프로세스를 시작하기 전에 다음을 나열합니다.
- 클라이언트 ID와 함께 사용 중인 지도 플랫폼 서비스
- 클라이언트 ID를 사용하는 애플리케이션, 사이트 또는 시스템
Google은 2025년 5월에 영향을 받는 고객에게 클라이언트 ID 지원 중단에 관한 알림 이메일을 보냈습니다. 이 정보는 알림 이메일에서도 확인할 수 있습니다.
Cloud 콘솔의 Google 지도 측정항목 페이지에서 클라이언트 ID 사용량의 최신 상태를 확인할 수 있습니다.
지도 플랫폼 서비스 목록:
- Cloud 콘솔에서 측정항목 페이지를 엽니다.
- 다음 설정을 사용하여 사용량을 필터링합니다.
- 사용자 인증 정보: 'project_number:<숫자 식별자>'만 선택합니다.
- 다음 필터를 설정합니다.
- 그룹화 기준: API
애플리케이션, 사이트 또는 시스템에 대한 힌트:
Cloud 콘솔에는 애플리케이션, 사이트 또는 시스템의 세부정보가 표시되지 않습니다. 하지만 클라이언트 ID 트래픽의 소스에 대한 몇 가지 힌트를 찾을 수 있습니다. 다음 단계를 따르세요.
- Cloud 콘솔에서 측정항목 페이지를 엽니다.
- 드롭다운에서 Maps Platform 서비스를 선택합니다.
- 다음 설정으로 사용량을 필터링합니다.
- 사용자 인증 정보: 'project_number:<숫자 식별자>'만 선택합니다.
- 다음 필터를 설정합니다.
- 그룹화 기준: 플랫폼 또는 도메인
- 트래픽을 확인해야 하는 각 Maps Platform 서비스에 대해 2단계부터 반복합니다.
API 키 준비
모든 클라이언트 ID는 Google Cloud 프로젝트와 연결되어 있으며 해당 프로젝트의 API 키를 사용하면 이전에 클라이언트 ID로 액세스했던 동일한 기능에 액세스할 수 있습니다. 할당량 문제나 누락된 기능을 방지하려면 연결된 프로젝트로 마이그레이션하는 것이 좋습니다.
- 클라이언트 ID가 연결된 Cloud 프로젝트를 찾습니다.
- Cloud 프로젝트가 열려 있는 결제 계정에 연결되어 있는지 확인합니다.
- 클라이언트 ID 이전을 위해 새 API 키를 만듭니다.
- Cloud 프로젝트에서 기존 API 키를 재사용할 수 있습니다.
- 동일한 Cloud 프로젝트에서 여러 API 키를 사용할 수 있습니다. 예를 들어 각 Maps Platform 서비스의 트래픽을 분리하거나 여러 플랫폼 (브라우저, 모바일 앱 등)의 트래픽을 분리할 수 있습니다. 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 키 이전 후 할당량 사용량이 증가합니다.
현재 할당량 구성, 현재 사용량을 검토하고 그에 따라 할당량 한도를 조정합니다.
- 클라이언트 ID를 사용하여 Maps JavaScript API 클라이언트 측 서비스를 사용하고 있는지 확인합니다.
- Cloud 콘솔에서 측정항목 페이지를 엽니다.
- 다음 설정으로 사용량을 필터링합니다.
- 그룹화 기준: 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.Geocoding.Javascript를 제외한 google.places.*.Javascript |
장소 라이브러리 |
Places API |
- 이러한 API 메서드를 사용하지 않는 경우 클라이언트 ID 트래픽이 이미 프로젝트 할당량을 사용하므로 할당량 설정을 걱정하지 않아도 됩니다.
- 클라이언트 ID 할당량 사용량 추정
- 각 서비스에 대해 초당 및 일별 세부사항을 모두 확인합니다.
- 초당 그래프: 분당 추가 할당량 요구사항을 위해 최대 트래픽에 60을 곱합니다.
- 일일 그래프: 최대 트래픽은 일일 추가 할당량 요구사항이어야 합니다.
- 해당 Maps Platform 서비스의 할당량을 조정합니다.
- 1단계에서 찾은 메서드 이름을 기반으로 해당 서비스의 할당량을 조정합니다.
코드 업데이트
클라이언트 매개변수를 키 매개변수로 대체
발신 GMP API 호출에서 사용자 인증 정보를 URL&client={value}에서 URL&key={value}로 업데이트합니다. 앱에서 HTTP를 사용하여 GMP 서비스에 액세스하는 경우 HTTPS를 사용하도록 업데이트하세요.
보고를 위한 채널 매개변수 업데이트
API 요청에 채널 매개변수를 지정하여 채널별 사용량을 추적할 수 있습니다. API 키는 채널 매개변수에 숫자 값만 지원합니다. 채널 매개변수에 숫자가 아닌 값을 포함하는 클라이언트 ID를 사용하는 경우 지원 값으로 업데이트하세요.
자세한 내용은 Google Maps Platform 보고를 참고하세요.
웹 서비스의 서명 매개변수 삭제
다음 웹 서비스 API의 경우 API 키로 액세스할 때는 서명 매개변수가 필요하지 않습니다. API 요청에서 서명 매개변수만 삭제하세요.
- Directions API (기존)
- Distance Matrix API (레거시)
- Geocoding API
- Elevation API
- Time Zone API
자세한 내용은 프리미엄 플랜 개요를 참고하세요.
이미지 API 서명 비밀번호
Maps Static API 및 스트리트 뷰 Static API에는 여전히 서명 매개변수가 필요합니다. 테스트 목적으로 서명 없이 소수의 요청을 수락하지만 프로덕션에서 한도에 도달하면 실패하기 시작합니다. 서명 보안 비밀번호를 클라이언트 ID용에서 API 키용으로 바꿉니다. 동일한 서명 알고리즘을 사용할 수 있지만 다른 서명 비밀번호를 사용해야 합니다. 자세한 내용은 디지털 서명 사용을 참고하세요.
클라이언트 ID 트래픽 모니터링
배포 후 Cloud 콘솔 대시보드를 사용하여 트래픽이 성공적으로 이전되었는지 확인합니다. 사용자 인증 정보별로 그룹화할 때 대시보드에 'project_number:123456' 형식으로 표시되는 클라이언트 ID 트래픽이 감소하기 시작합니다.
클라이언트 ID 일시중지
개발자는 이전 후 클라이언트 ID를 일시중지하는 것이 좋습니다. 이는 의도치 않은 트래픽으로부터 사용자 인증 정보를 보호하고 클라이언트 ID의 남은 사용량이 중요하지 않으며 (예: 테스트, 캐시, 봇 등) 비즈니스에 영향을 주지 않고 오류를 반환할 수 있음을 확인하기 위한 것입니다. Cloud 콘솔에서 클라이언트 ID를 일시중지할 수 있습니다. 자세한 내용은 프리미엄 플랜 인증 개요를 참고하세요.
클라이언트 ID 셀프 서비스 임시 재활성화
Google Maps Platform 클라이언트 ID가 2026년 5월에 단계적 지원 중단 기간에 들어감에 따라 서비스 가용성이 더 이상 보장되지 않습니다. 예약된 서비스 종료 프로세스의 일환으로 액세스가 주기적으로 제한됩니다. 일반적으로 서비스는 몇 시간 이내에 자동으로 복원되지만 즉시 복원해야 하는 경우 액세스를 수동으로 다시 활성화할 수 있습니다.
액세스 권한을 긴급하게 복원하려면 Google Cloud 콘솔을 통해 셀프 서비스 재활성화를 수행하세요.
- Google Maps Platform 사용자 인증 정보 페이지로 이동합니다.
- 클라이언트 ID에 연결된 특정 Cloud 프로젝트를 찾습니다.
- 항목의 맨 오른쪽에 있는 일시중지 해제 아이콘을 클릭하여 서비스를 복원합니다.
API 키로 빠르게 이전할 수 없으며 일시적으로 추가 중단에서 제외되려면 다음 세부정보를 포함하여 Google Maps Platform 지원팀에 문의하세요.
- 클라이언트 ID
- 특정 사용 사례
- 목표 이전 날짜
- 비즈니스 영향 평가
클라이언트 ID 사용 보고서 - 결제 보고서
프로젝트 측정항목에 액세스할 수 없는 사용자(예: 결제 관리자, 특히 Maps Platform 파트너)의 경우 프로젝트 측정항목 대신 결제 보고서를 확인하는 것이 유용할 수 있습니다. 결제 보고서에는 1~2일의 지연 시간이 있지만 30일 이상의 사용량 및 비용 통계를 표시하는 이점이 있습니다.
다음 단계를 따라 Google Cloud 콘솔을 통해 클라이언트 ID 사용량을 모니터링할 수 있습니다.
- Google Cloud 콘솔에서 결제 > 보고서 페이지로 이동합니다.
- (선택사항, 파트너에게만 해당) 필터를 적용하여 원하는 하위 결제 계정을 선택합니다.
- 라벨 키
goog-maps-api-key-suffix별로 보고서 데이터를 그룹화합니다. 이 라벨에는 API 키의 후행 문자가 표시됩니다. goog-maps-api-key-suffix라벨이 누락되었거나 비어 있는 항목을 찾아 클라이언트 ID 트래픽을 식별합니다. 이 라벨은 클라이언트 ID 요청에 대해 채워지지 않기 때문입니다.- API 요청과 연결되지 않는 SKU(예: 정기 결제 SKU)를 무시합니다.
문제 해결
요청이 실패하는지 어떻게 확인할 수 있나요?
응답 코드 그래프에서 오류 통계를 확인할 수 있습니다.
ApiNotActivatedMapError 또는 REQUEST_DENIED 오류
Cloud 프로젝트에서 서비스를 사용 설정하지 않으면 ApiNotActivatedMapError 또는 REQUEST_DENIED 오류가 표시됩니다. 안내에 따라 서비스를 사용 설정합니다.
오류 RefererNotAllowedMapError개
소스 도메인이 API 키에 추가되지 않으면 RefererNotAllowedMapError 오류가 표시됩니다. 'API 키 보안' 섹션을 확인하고 API 키에 도메인을 추가합니다.
OverQuotaMapError 또는 OVER_QUERY_LIMIT 오류
구성된 할당량이 트래픽을 처리하기에 충분하지 않으면 OverQuotaMapError 또는 OVER_QUERY_LIMIT이 표시됩니다. '할당량 설정 검토' 섹션을 확인하고 그에 따라 할당량을 조정합니다.
'Requests to this API must be over 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"
}