클라이언트 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 프로젝트를 찾습니다.
   • 포털 이전 FAQ
2. Cloud 프로젝트가 열려 있는 결제 계정에 연결되어 있는지 확인합니다.
3. 클라이언트 ID 이전을 위해 새 API 키를 만듭니다.
   • Cloud 프로젝트에서 기존 API 키를 재사용할 수 있습니다.
   • 예를 들어 각 Maps Platform 서비스의 트래픽을 분리하거나 여러 플랫폼 (브라우저, 모바일 앱 등)의 트래픽을 분리하기 위해 동일한 Cloud 프로젝트에서 여러 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 클라이언트 측 서비스에서 클라이언트 ID를 사용해도 프로젝트 할당량이 소모되지 않습니다. 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.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 및 Street View Static API에는 여전히 서명 매개변수가 필요합니다. 테스트 목적으로 서명 없이 소수의 요청을 수락하지만 프로덕션에서 기준점에 도달하면 실패하기 시작합니다. 클라이언트 ID의 서명 보안 비밀을 API 키의 서명 보안 비밀로 바꿉니다. 동일한 서명 알고리즘을 사용할 수 있지만 다른 서명 보안 비밀을 사용해야 합니다. 자세한 내용은 디지털 서명 사용을 참고하세요.

경고: 코드 변경사항을 프로덕션에 배포하기 전에 엔드 투 엔드 기능이 영향을 받지 않았는지 확인하세요.

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

배포 후 Cloud Console 대시보드를 사용하여 트래픽이 성공적으로 이전되었는지 확인합니다. 사용자 인증 정보별로 그룹화할 때 대시보드에 '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"
}