이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Geolocation API 웹 서비스를 사용한 권장사항

Google Maps Platform 웹 서비스는 지도 애플리케이션에 지리적 데이터를 제공하는 Google 서비스에 대한 HTTP 인터페이스 모음입니다.

이 가이드에서는 웹 서비스 요청을 설정하고 서비스 응답을 처리하는 데 유용한 몇 가지 일반적인 관행을 설명합니다. Geolocation API에 관한 전체 문서는 개발자 가이드를 참고하세요.

웹 서비스란 무엇인가요?

Google Maps Platform 웹 서비스는 외부 서비스에서 Maps API 데이터를 요청하고 지도 애플리케이션 내에서 데이터를 사용하는 인터페이스입니다. 이러한 서비스는 Google Maps Platform 서비스 약관의 라이선스 제한에 따라 지도와 함께 사용하도록 설계되었습니다.

Maps API 웹 서비스는 특정 URL에 대한 HTTP(S) 요청을 사용하여 URL 매개변수 또는 JSON 형식의 POST 데이터를 서비스에 인수로 전달합니다. 일반적으로 이러한 서비스는 애플리케이션에서 파싱 또는 처리할 수 있도록 응답 본문의 데이터를 JSON으로 반환합니다.

Geolocation 요청은 POST를 사용하여 다음과 같은 URL로 전송됩니다.

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

참고: 모든 Geolocation API 애플리케이션에는 인증이 필요합니다. 인증 사용자 인증 정보에 대해 자세히 알아보세요.

SSL/TLS 액세스

API 키를 사용하거나 사용자 데이터를 포함하는 모든 Google Maps Platform 요청에는 HTTPS가 필요합니다. 민감한 정보가 포함된 HTTP를 통한 요청은 거부될 수 있습니다.

적절한 Google API 사용

설계가 잘못된 API 클라이언트는 인터넷과 Google 서버에 필요 이상으로 많은 부하를 줄 수 있습니다. 이 섹션에는 API 클라이언트의 모범 사례가 포함되어 있습니다. 이러한 권장사항을 따르면 API를 의도치 않게 악용하여 애플리케이션이 차단되는 것을 방지할 수 있습니다.

지수 백오프

드물지만 요청을 처리하는 중에 문제가 발생할 수 있습니다. 4XX 또는 5XX HTTP 응답 코드가 수신되거나 클라이언트와 Google 서버 간에 TCP 연결이 실패할 수 있습니다. 원래 요청이 실패한 경우 후속 요청이 성공할 수 있으므로 요청을 다시 시도하는 것이 좋습니다. 하지만 Google 서버에 반복적으로 요청을 반복하지 않는 것이 중요합니다. 이러한 루핑 동작은 클라이언트와 Google 간의 네트워크에 과부하를 일으켜 여러 당사자에게 문제가 발생할 수 있습니다.

따라서 시도 사이의 지연 시간을 늘려 재시도하는 것이 훨씬 좋습니다. 일반적으로 지연은 시도할 때마다 배수로 증가하며 이를 지수 백오프라고 합니다.

예를 들어 Time Zone API에 다음과 같은 요청을 하고자 하는 애플리케이션을 생각해 보겠습니다.

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

다음 Python 예시는 지수 백오프 요청 방법을 보여줍니다.

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

또한 애플리케이션 호출 체인 위에 요청이 빠르게 반복되는 재시도 코드가 없는지 확인해야 합니다.

동기화된 요청

Google API에 대한 동기화된 대량의 요청은 Google 인프라에 대한 분산형 서비스 거부 (DDoS) 공격처럼 보일 수 있으며, 이에 따라 처리될 수 있습니다. 이를 방지하려면 API 요청이 클라이언트 간에 동기화되지 않도록 해야 합니다.

예를 들어, 현재 시간대의 시간을 표시하는 애플리케이션을 생각해 봅시다. 이 애플리케이션은 표시된 시간이 업데이트될 수 있도록 분 시작 시 클라이언트 운영체제에서 알람을 설정할 수 있습니다. 애플리케이션은 해당 알람과 관련된 처리의 일환으로 API를 호출해서는 안 됩니다.

고정된 알람에 응답하여 API를 호출하는 것은 좋지 않습니다. 시간이 지남에 따라 균등하게 분산되는 대신 API 호출이 여러 기기 간에 분 시작 시점에 동기화되기 때문입니다. 이렇게 설계된 애플리케이션은 매분마다 시작 시 정상 수준의 60배에 달하는 트래픽이 급증합니다.

이 문제를 해결하려면 두 번째 알람을 임의로 선택한 시간으로 설정하도록 설계하면 됩니다. 이 두 번째 알람이 발생하면 애플리케이션은 필요한 API를 호출하고 결과를 저장합니다. 애플리케이션이 분 시작 시 디스플레이를 업데이트하려고 하면 API를 다시 호출하는 대신 이전에 저장된 결과를 사용합니다. 이 접근 방식을 사용하면 API 호출이 시간 경과에 따라 균등하게 분산됩니다. 또한 API 호출은 디스플레이가 업데이트될 때 렌더링을 지연시키지 않습니다.

분 시작 시간 외에도 주의해서 타겟팅하지 않아야 하는 다른 일반적인 동기화 시간은 시간 시작 시간과 자정에 시작하는 각 날짜입니다.

응답 처리

이 섹션에서는 웹 서비스 응답에서 이들 값을 동적으로 추출하는 방법에 대해 설명합니다.

Google 지도 웹 서비스는 이해하기 쉽지만 사용자 친화적이지 않은 응답을 제공합니다. 쿼리를 실행할 때는 데이터 세트를 표시하는 대신 몇 가지 특정 값을 추출하는 것이 좋습니다. 일반적으로 웹 서비스의 응답을 파싱하고 관심 있는 값만 추출하는 것이 좋습니다.

사용하는 파싱 스키마는 JSON으로 출력을 반환하는지에 따라 다릅니다. 이미 JavaScript 객체 형식인 JSON 응답은 클라이언트의 JavaScript 자체 내에서 처리될 수 있습니다.