출시 전 검사 목록

개발팀에 필수 리소스 액세스 권한이 있는지 확인

Google Maps API 프리미엄 플랜 환영 편지를 안전한 곳에 보관

중요한 이유: 환영 편지는 곧 개발자의 Google Maps API 프리미엄 플랜 스타터 키트이며, 응급 키트가 될 수도 있습니다. 환영 편지에는 프리미엄 플랜를 사용하는 데 필요한 Google API Console 프로젝트 ID, 클라이언트 ID와 암호화 키 등의 중요한 정보가 포함되어 있습니다. 또한, Google Maps API에서 기술적 문제가 발생할 경우 프리미엄 플랜 지원팀에 문의하는 데 필요한 모든 정보가 있습니다.

Google Cloud Support Portal 사용

중요한 이유: 지원 포털에서는 사용량 보고서, 뉴스 피드, 유용한 개발자 리소스 등의 정보에 액세스할 수 있습니다. 또한 지원 포털에서는 개발 또는 출시 시에 기술적 문제가 발생하면 프리미엄 플랜 지원팀에 지원 케이스를 제출할 수 있습니다. 지원 포털 액세스 URL은 다음과 같습니다.

https://google.secure.force.com/

출시 전에 애플리케이션 유지 관리를 책임지는 모든 개발자에게 지원 포털에 대한 액세스 권한을 제공하세요. 기술적 문제가 발생했을 때 지원 포털에 액세스하면 여러분의 개발팀 구성원이 지원팀에 문의하고 지원팀이 여러분 조직 내의 적절한 이해관계자에게 연락할 수 있는 장점을 동시에 누릴 수 있습니다. 예를 들어, 지원팀이 애플리케이션에 장애를 일으킬 수 있는 비정상적인 트래픽이나 동작을 감지하면 여러분의 조직에 연락을 취해야 할 수도 있습니다. 지원팀이 적절한 개발자에게 연락을 취할 수 있는지에 따라 예상치 못한 시스템 중단이 발생하기도 하고 이를 예방하기도 합니다. 지원 포털에 액세스할 수 없다면 다음 링크에서 액세스 권한을 요청하세요.

Google Cloud Support Portal 계정 요청

관련 알림 피드 구독

중요한 이유: Maps API에서 개발과 변경 사항에 대한 최신 소식을 파악하려면 FAQ에서 설명한 바와 같이 관련 알림 피드를 구독하세요.

Google Maps Premier API 알림: 중단, 업데이트, 서비스 알림의 RSS 피드를 구독할 수도 있습니다.

http://google.force.com/services/xml/MapsRSS

지원 핫라인 준비

미국 고객은 1-877-355-5787, 미국 외 고객은 +1 404-978-9282를 사용합니다.

중요한 이유: 핫라인은 Google Cloud Support Portal에 전화를 걸 수 있는 방법입니다. 이 페이지를 북마크하고 최신 지원 핫라인 번호를 확인하세요. 지원 핫라인을 사용하여 지원팀에 기술적 문제를 보고할 수 있지만 프로덕션 중단, 서비스 사용 중단 사례로 제한됩니다. Google의 우선순위 수준은 다음 문서에 정의되어 있습니다.

https://support.google.com/work/answer/184028

애플리케이션 최적화

Google Maps APIs 서비스에 액세스할 수 있도록 방화벽 구성

중요한 이유: Google Maps APIs 서비스는 다양한 도메인을 사용합니다. 그중 일부는 *google.com 도메인에 속하지 않습니다. 제한이 심한 방화벽이 설치되어 있다면 각 Maps API 서비스가 사용하는 도메인 액세스를 허용하는 것이 중요합니다. 방화벽에서 해당 도메인 액세스를 허용하지 않을 경우, API 요청이 실패하고 애플리케이션에 장애가 발생할 수 있습니다. 지원 포털에서 Maps API가 사용하는 모든 도메인 목록을 확인할 수 있습니다.

  1. Google Cloud Support Portal에 로그인합니다.
    지원 포털은 Google Maps API 프리미엄 플랜 또는 이전 Google Maps APIs for Work, Google Maps for Business 라이선스를 사용하는 고객에게만 제공됩니다.
  2. Resources 탭으로 이동합니다.
  3. List of domains used by the Google Maps APIs family를 선택합니다. (직접 링크)
  4. 애플리케이션이 목록에 있는 도메인에 액세스하도록 허용합니다.

이 도메인에 연결된 IP는 고정되어 있지 않으므로 IP 주소로 방화벽 제한을 관리하지 않는 것이 좋습니다.

참고: Google Maps APIs 서비스는 인바운드 및 아웃바운드 트래픽에 포트 80(http)과 443(https)을 사용합니다. 이 서비스는 GET, POST, PUT, DELETE 및 HEAD 요청이 필요합니다. 이 포트에서 트래픽을 허용하고 API와 사용 사례에 따라 요청을 허용하도록 방화벽을 구성합니다.

올바른 SSL 호스트 이름으로 API 로드

중요한 이유: Maps API를 SSL로 로드하는 애플리케이션은 레거시 호스트 이름인 https://maps-api-ssl.google.com이 아니라 https://maps.googleapis.com을 사용해야 합니다.

Google Maps JavaScript API와 함께 사용하도록 SSL 도메인 승인

중요한 이유: Google Maps JavaScript API API를 SSL 도메인과 사용할 때는 명시적으로 HTTPS 도메인을 승인하여 요청이 거절되지 않게 해야 합니다. http://yourdomain.com을 승인하더라도 SSL의 https://yourdomain.com을 자동으로 활성화하지 않습니다. Google Cloud Support Portal의 왼쪽 내비게이션 메뉴에서 Maps: Manage Client ID 링크를 클릭하여 승인된 도메인 목록을 확인할 수 있습니다. 클라이언트측 API를 SSL 도메인과 함께 사용하는 것과 관련된 오류를 해결할 때는 먼저 페이지의 요소가 HTTP로 로드되지 않는지 확인하는 것이 좋습니다. 승인 문제 해결 가이드도 참조하세요.

적절한 API 버전 선택

중요한 이유: 애플리케이션을 개발하기 전에 어느 버전의 API가 지원이 중단되었는지 확인하는 것이 중요합니다. 지원이 중단되지 않은 API 버전을 개발하면 개발 시간을 절약하고 지원이 중단된 버전을 사용할 수 없게 되었을 때 비용을 줄일 수 있습니다.

특히 Google Maps JavaScript API가 사용하는 버전 관리 구성표를 이해하고 개발자의 환경에서 부적절한 API 버전을 잘못 사용하지 않도록 해야 합니다.

예를 들어 개발이나 테스트 환경에서는 API의 시험용 버전을 사용하는 것이 적절할 수 있으나 프로덕션 환경에서는 시험용 버전을 사용하지 않는 것이 좋습니다. Google의 SLA는 안정적인 API 버전에만 적용되므로 프로덕션 환경에서는 안정적 버전만 사용해야 합니다.

Google Maps JavaScript API 버전 가이드를 참조하세요.

클라이언트측 디자인과 서버측 디자인 선택

중요한 이유: 클라이언트측 또는 서버측 접근방식을 선택하는 것은 아키텍처와 관련된 결정이며, 애플리케이션의 안정성과 확장성에 매우 중요합니다. 일반적으로 서버측 디자인은 기록을 오프라인으로 사전/사후에 처리할 때 사용해야 합니다(즉, 애플리케이션 외부). 반면, 클라이언트측 디자인은 사용자와 상호작용하는 부분에 사용해야 합니다(즉, 실시간으로 사용자가 제출한 요청 처리).

클라이언트측 디자인을 사용해야 할 곳에 서버측 디자인을 배포하는 것은 할당량을 초과하여 애플리케이션이 장애를 일으키는 주요 원인입니다. 서버측 호출을 사용하는 애플리케이션을 디자인하거나 출시하기 전에 지오코딩 전략을 참조하는 것이 좋습니다.

사용 할당량 최적화

중요한 이유: 애플리케이션이 Maps API 크레딧이라는 할당량을 사용하는 방식을 이해하면 유료로 결제하는 비용을 줄이는 데 도움이 됩니다. 예를 들어 Google Maps JavaScript API를 사용 중이라면 애플리케이션은 각 지도 로드에 대해 Maps API 크레딧을 사용합니다. 프리미엄 플랜 사용 요금 및 제한 가이드를 참조하세요.

웹 서비스 할당량 사용 관리

중요한 이유: 기본적으로 공동 웹 서비스 할당량은 매일 100,000개의 무료 요청으로 설정되어 있습니다. API별 자세한 할당량 내역은 사용 제한 가이드를 참조하세요. 프로젝트에서 얼마나 많은 할당량을 사용할 수 있는지 확인하려면 지원 케이스를 제출하세요.

서비스를 출시하기 전에 다양한 할당량 관련 오류(예: OVER_QUERY_LIMIT, User Rate Limit Exceeded)를 이해하고 할당량을 초과했을 때 이러한 오류에 대응할 수 있도록 애플리케이션에 적절한 로직을 설정하는 것이 중요합니다. 먼저 사용 제한 FAQ를 읽어보세요. 각 API가 반환하는 상태 코드에 대한 자세한 내용은 해당 API의 개발자 가이드를 참조하세요. 예를 들어, Google Maps Directions API 상태 코드를 참조하세요. 이러한 개념을 이해하고 구현하면 애플리케이션이 허용된 할당량을 초과하여 Google에서 차단되거나 장애를 일으킬 가능성이 현저히 줄어듭니다.

앱에서 부하 테스트 수행

중요한 이유: 애플리케이션의 부하 테스트를 사용하여 Maps API 할당량을 초과하지 않고 대량의 요청을 처리할 수 있는지 확인합니다.

라이브 Google 서비스에 대해 부하 테스트를 하면 애플리케이션이 허용된 할당량을 초과하여 Google에서 차단됩니다. Google Maps APIs는 매우 많은 용량을 처리할 수 있습니다. 2012년에 Santa Tracker는 초당 1,600,000개 요청을 처리했습니다. 따라서 Google 서비스에 대해 부하 테스트를 수행할 필요가 없습니다. 대신 애플리케이션 부하 테스트로 Maps API에서 제공하는 할당량을 초과하지 않고 대량의 요청을 처리할 수 있는지 확인해야 합니다. 예: Google Maps Geocoding API의 할당량이 20 QPS(초당 쿼리)라면 애플리케이션 부하 테스트로 Google Maps Geocoding API에 20 QPS 이상을 전송하지 않고 600 QPS를 처리할 수 있는지 확인해야 합니다.

이 목표를 안전하게 달성하기 위해서는 가짜 API에 부하 테스트를 해야 합니다. 가짜 API는 Google Maps APIs를 포함하지 않고 대량의 요청을 흡수해서 유효한 응답을 보낼 수 있는 서비스입니다. 따라서 Google Maps APIs에 차단될 위험을 무릅쓰지 않고도 애플리케이션의 부하를 테스트할 수 있습니다.

작은 Google App Engine 애플리케이션으로 구현된 가짜 API 예시를 참조하세요. (appengine.google.com에 등록 후) 자체 App Engine 애플리케이션에 이 예시를 업로드하고 maps.googleapis.com이 아니라 본인의 애플리케이션에서 요청을 보내도록 할 수 있습니다.

일반적으로 기본(무료) App Engine 할당량으로도 충분히 Maps API 웹 서비스에서 제공하는 할당량 이상까지 애플리케이션 부하를 테스트할 수 있습니다. 애플리케이션에서 올바른 User-Agent 헤더를 설정하여 응답 압축이 활성화되었는지 확인하세요. 이는 효율적인 대역폭 사용에 중요합니다. 특히, 대량의 일반 텍스트(JSON/XML) 응답을 지원하는 App Engine 애플리케이션에 중요합니다. App Engine 애플리케이션에 더 많은 할당량이 필요하다면 결제를 활성화할 수 있습니다. 그러나 이런 경우는 매우 드뭅니다.

표준에서 프리미엄 라이선스로 애플리케이션 마이그레이션

API 요청에 클라이언트 ID 또는 API 키 포함

중요한 이유: 애플리케이션에서 할 수 있는 가장 중요한 일은 API 요청에 클라이언트 ID(gme-yourclientid) 또는 API 키(예: AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0)를 포함하는 것입니다. 클라이언트 ID 또는 API 키는 여러분의 요청을 Google Maps API 프리미엄 플랜 요청으로 식별합니다.

프리미엄 플랜에서 제공하는 기능을 사용하려면 애플리케이션에 클라이언트 ID 또는 API 키를 포함해야 합니다. 기술 지원을 받고 애플리케이션이 SLA를 준수하는지 확인하기 위해서도 애플리케이션에 클라이언트 ID 또는 API 키를 포함해야 합니다.

대부분 API는 클라이언트 ID 또는 API 키 중에서 어느 것을 사용할지 선택할 수 있습니다. 클라이언트 ID는 여러분 조직의 기본 담당자에게 발급된 환영 편지에 포함되어 있습니다. Google API Console에서 자신의 API 키 또는 키를 생성할 수 있습니다.

자세한 내용은 인증 및 승인 가이드를 참조하세요.

API 키 또는 클라이언트 ID 중 하나만 API 요청에 포함

중요한 이유: Google Maps JavaScript API를 올바르게 로드하거나 다른 Google Maps API에 요청을 전송하려면 클라이언트 ID 또는 API 키 중에서 둘 중 하나만 포함해야 합니다. 클라이언트 ID를 사용하기로 했다면 key 매개변수를 제거해야 합니다. 요청에 클라이언트 ID와 키가 모두 포함되어 있다면 요청이 실패합니다.

API별로 프리미엄 플랜 요청의 서식을 올바르게 지정하는 방법에 대한 자세한 내용은 인증 및 승인을 참조하세요.

클라이언트 ID를 사용할 때는 Google Maps JavaScript API와 함께 사용하도록 도메인을 승인합니다.

중요한 이유: 권한이 없는 사이트가 클라이언트 ID를 사용하지 못하게 차단하기 위해 Google Maps JavaScript API는 클라이언트 ID를 사용할 모든 사이트에 대해 지원팀에서 모든 도메인을 승인받아야 합니다. (클라이언트 ID가 아닌 API 키를 사용한다면 URL 등록은 하지 않아도 됩니다.) 클라이언트 ID를 사용하도록 승인된 URL과 클라이언트 ID를 사용하려고 시도하는 사이트가 일치하지 않으면 해당 사이트는 클라이언트 ID로 API를 사용하지 못합니다. 언제든지 도메인을 승인할 수 있습니다. 출시 전에 모든 사이트의 도메인을 승인했는지 확인하세요.

Google Cloud Support Portal의 왼쪽 내비게이션 메뉴에서 Maps: Manage Client ID 링크를 클릭하여 승인된 도메인 목록을 확인할 수 있습니다.

승인 문제는 케이스를 제출하기 전에 승인 문제 해결 가이드를 참조하세요.

클라이언트 ID를 사용할 때는 개인 암호화 키로 생성한 서명으로 웹 서비스 요청에 서명

중요한 이유: 비공개 암호화 키는 디지털 서명을 생성하는 데 사용하며, Google에 요청의 출처가 신뢰하는 소스임을 알려줍니다. Google의 Web Service API에서는 클라이언트 ID를 인증에 사용하면 요청에 디지털 서명을 추가해야 합니다. 그러면 요청의 보안이 한층 강화되어 클라이언트 ID와 관련된 할당량을 지키는 데 도움이 됩니다. 암호화 키(예: vNIXE0xscrmjlyV-12Nj_BvUPaw=)는 여러분의 조직 내 기본 담당자에게 발급된 환영 편지에서 확인할 수 있습니다.

참고: 암호화 키는 서명을 생성하는 데 사용됩니다. 요청에 서명으로 추가하지 마세요. 암호화 키는 ATM 핀 번호와 유사합니다. 계정에 액세스하기 위한 인증 수단으로 사용되므로 절대 신뢰할 수 없는 소스와 공유하거나 이러한 소스에 보이게 해서는 안 됩니다. 올바르게 서명되지 않은 프리미엄 플랜 웹 서비스 요청은 Google 서버에서 거절되므로 출시 전에 애플리케이션에서 요청에 적절히 서명하는 것이 중요합니다. 인증 및 승인 가이드를 참조하세요.

애플리케이션 사용량 추적

중요한 이유: 프리미엄 플랜 고객은 전송한 요청, 사용한 크레딧, 반환된 오류 등을 포함하여 애플리케이션 사용에 대한 자세한 보고서에 액세스할 수 있습니다. 보고서 가이드를 참조하세요.

channel 매개변수는 선택적 매개변수이며, 각 애플리케이션에 별개의 채널을 할당하여 클라이언트 ID로 사용량을 추적합니다. channel 매개변수는 클라이언트 ID에 등록할 필요가 없습니다. API 요청에 channel 매개변수를 추가하면 구현 후 1~2일 후에 채널당 사용 결과가 지원 포털 사용량에 나타나기 시작합니다. 채널을 구현하는 장소는 개발자의 결정에 달려 있고, 그에 따라 사용량 집계 방법도 달라집니다. 애플리케이션 사용량을 추적할 channel 매개변수를 애플리케이션에 통합하려면 출시 전에 결정하세요.

channel 매개변수는 다음 형식을 사용해야 합니다.

  • ASCII 영숫자 문자열이어야 합니다.
  • 마침표(.), 밑줄(_) 하이픈(-) 문자가 허용됩니다.
  • channel 매개변수는 대/소문자를 구분하고 대문자, 대/소문자 혼합, 소문자 channel 매개변수는 소문자에 병합됩니다. 예를 들어 CUSTOMER 채널 사용량은 customer 채널 사용량과 통합됩니다.

클라이언트 ID당 최대 2,000개 채널을 구현할 수 있습니다.

channel 매개변수를 사용하려면 클라이언트 ID 전달에 사용하는 client 매개변수와 함께 요청 URL에 포함하세요.

channel 매개변수는 애플리케이션에 따라 통계적으로 할당된 값이어야 합니다. 동적으로 생성되어 개별 사용자를 추적하는 데 사용해야 합니다.