使用 Aerial View API 網路服務的最佳做法

Google 地圖平台網路服務集合了 Google 的 HTTP 介面 為您的地圖應用程式提供地理資料的服務。

本指南說明一些常見的設定做法, Web 服務 要求及處理服務回應請參閱開發人員指南 查看 Aerial View API 的完整說明文件。

什麼是網路服務?

Google 地圖平台網路服務是一種用來要求 Maps API 資料的介面 並在地圖應用程式中使用資料。這些服務 設計為與地圖搭配使用,如 授權限制

Maps API 網路服務使用對特定網址的 HTTP(S) 要求,並傳遞網址參數和/或 JSON 格式的 POST 資料做為服務的引數。一般而言,這些服務會在 做為剖析的 JSON 回應內文 和/或應用程式處理的流程

傳送 HTTP GET 要求給 lookupVideo 方法:

https://aerialview.googleapis.com/v1/videos:lookupVideo

將查詢參數傳遞至請求,以指定地址或影片 ID。

注意:所有 Aerial View API 應用程式都需要驗證。 進一步瞭解驗證憑證

SSL/TLS 存取

凡是使用 API 金鑰或包含使用者的 Google 地圖平台要求,一律必須採用 HTTPS 資料。如果透過 HTTP 傳送包含機密資料的要求,可能會遭到拒絕。

建立有效網址

您可能認為網址是否「有效」一眼就能判斷,但實際情況不然。例如,在瀏覽器的網址列內輸入的網址可能包含特殊字元 (例如 "上海+中國");瀏覽器必須在內部將這些字元轉譯為其他編碼方式才能傳送。同理可證,產生或接受 UTF-8 輸入值的任何程式碼都可能會將含有 UTF-8 字元的網址視為「有效網址」,但也需要先轉譯這些字元,才能向外傳送至網路伺服器。這個過程稱為網址編碼百分比編碼

特殊字元

所有網址都必須符合統一資源 ID (URI) 規格指定的語法,因此我們必須轉譯特殊字元。實務上,這表示網址只能包含一部分特殊 ASCII 字元:慣用的英數字元符號,以及用做網址內控制字元的部分預留字元。下表摘要列出這些字元:

有效網址字元摘要
字元集字元網址使用情況
英數字元 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 文字字串、結構用途 (http)、通訊埠 (8080) 等。
非預留 - _ . ~ 文字字串
預留 ! * ' ( ) ; : @ & = + $ , / ? % # [ ] 控制字元和 (或) 文字字串

建立有效網址時,您必須確定網址僅包含 表格。如果網址使用上述字元集,通常會導致兩個問題:一個是遺漏問題,一個則是代換問題:

  • 您需要處理的字元不屬於上述字元集。舉例來說,外國語言的字元 (例如「上海+中國」) 就需要使用上述字元加以編碼。依照普遍慣例,空格 (網址內不允許使用) 通常也用加號 '+' 字元來表示。
  • 字元屬於上方字元集中的預留字元,但需要直接使用。舉例來說,網址內會使用 ? 來表示查詢字串的開頭;如果您想使用「? and the Mysterions」這個字串,就必須對 '?' 字元進行編碼。

所有字元進行網址編碼時,都會使用 '%' 字元,外加對應至各自 UTF-8 字元的雙字元十六進位值。舉例來說,「上海+中國」以 UTF-8 編碼形式進行網址編碼的結果是 %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B,「? and the Mysterians」字串則是 %3F+and+the+Mysterians%3F%20and%20the%20Mysterians

需要編碼的常見字元

必須編碼的部分常見字元如下:

不安全的字元 經過編碼的值
空格 %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

將使用者輸入內容轉換成網址的過程有時會遇到困難。舉例來說,使用者輸入的地址可能是「5th&Main St.」。一般來說,您應該根據各組成部分來建立網址,並將任何使用者輸入內容當成常值字元來處理。

此外,所有 Google 地圖平台網路服務的網址長度上限都是 16384 個字元 以及靜態網路 API對於大部分的服務而言,很少出現接近此字元限制的情況。但請注意,某些服務的幾個參數可能會產生較長的網址。

謹慎使用 Google API

設計不良的 API 用戶端,可能承載於網際網路和網際網路上的負載 Google 伺服器。本節包含 API 用戶端的一些最佳做法。追蹤中 這些最佳做法,有助於避免您因為無意間濫用 並嚴謹測試及提升 API 的公平性後 我們才能放心地推出 API

指數型退讓

在極少數情況下,您的要求可能發生錯誤。您可能會收到 4XX 或 5XX HTTP 否則 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 格式JSON 回應,目前格式為 JavaScript 物件,可以在 JavaScript 本身內處理 呼叫。