使用 Route Optimization API 網路服務的最佳做法

Google 地圖平台網路服務是一組 HTTP 介面，用於 Google 服務，為您的地圖應用程式提供地理資料。

本指南說明一些有助於設定網路服務要求及處理服務回應的常見做法。如需 Route Optimization API 的完整說明文件，請參閱開發人員指南。

什麼是網路服務？

Google 地圖平台網路服務是一個介面，可從外部服務要求 Maps API 資料，以及在 Google 地圖應用程式中使用資料。這些服務是依照《Google 地圖平台服務條款》的授權限制規定，與地圖搭配使用。

Maps API 網路服務使用為特定網址發出的 HTTP(S) 要求，將網址參數和/或 JSON 格式 POST 資料做為引數傳遞至服務。一般來說，這些服務會在回應主體中以 JSON 格式傳回資料，以便應用程式剖析和/或進行處理。

以下範例顯示向 optimizeTours 方法發出的 REST POST 要求網址：

https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER:optimizeTours

將 PROJECT_NUMBER 替換為已啟用 Route Optimization API 的 Cloud 專案數量或 ID。

將 OptimizeToursRequest 訊息納入 JSON 要求主體。

注意事項：所有 Route Optimization API 應用程式都需要驗證。進一步瞭解驗證憑證。

SSL/TLS 存取

所有使用 API 金鑰或包含使用者資料的 Google 地圖平台要求都必須提供 HTTPS。透過 HTTP 傳送含有機密資料的要求可能會遭拒。

建立有效網址

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

注意：瀏覽器和/或服務可能會在傳送前，自動為要求 URI 進行網址編碼。在使用加密編譯要求簽署的 API 上，如果網址編碼在簽署後變更了要求，簽章可能會因此失效。為了避免發生這個問題，請「一律」在簽署要求「之前」，將查詢字串進行網址編碼。

特殊字元

所有網址都必須符合統一資源 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 地圖平台網路服務和 Static Web API 的網址長度上限都是 16384 個字元。對於大部分的服務而言，很少出現接近此字元限制的情況。但請注意，某些服務的幾個參數可能會產生較長的網址。

友善使用 Google API

設計不良的 API 用戶端可能會在網際網路和 Google 伺服器上超量負載，本節針對 API 用戶端提供了一些最佳做法。只要採用這些最佳做法，即可避免應用程式因無意間濫用 API 而遭到封鎖。

指數型退讓

在極少數的情況下，系統可能無法處理您的要求；您可能會收到 4XX 或 5XX HTTP 回應代碼，或者 TCP 連線可能只是在用戶端和 Google 伺服器之間失敗。通常值得重試要求，因為原始要求失敗時，後續要求可能會成功。不過，請務必避免重複對 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 呼叫同步處理至分鐘的開始時間，即使在不同裝置之間亦然，而不是隨著時間平均分配。如果應用程式設計不良，會在每分鐘開始時以六十倍正常量產生流量尖峰。

相反地，最好將第二個鬧鐘設為隨機選擇的時間。當這第二次鬧鐘觸發時，應用程式會呼叫其所需的 API 並儲存結果。當應用程式要在一分鐘開始時更新畫面時，會使用先前儲存的結果，而不是再次呼叫 API。使用這個方法時，API 呼叫會在時間中平均分配。此外，螢幕更新時，API 呼叫不會延遲算繪。

除了一分鐘的開始外，其他常見的同步處理時間也「不要」分別在一小時的開始時間和午夜開始時。

處理回應

注意：我們無法保證包含網路服務要求的個別回應採用何種格式 (部分元素可能會遺失或位於多個位置)，請您切勿假設不同查詢有任何特定回應傳回的格式都相同。請改為處理回應，並透過「運算式」選取適當的值。

本章節討論如何從網路服務回應中，以動態方式擷取這些值。

Google 地圖網路服務提供的回應容易理解，但不太容易使用。執行查詢時，與其顯示一組資料，您可能會想擷取某些特定值。一般而言，您會想剖析網路服務的回應，並只擷取感興趣的值。

您使用的剖析配置取決於您是否以 JSON 格式傳回輸出內容。JSON 回應已採用 JavaScript 物件形式，可以在用戶端於 JavaScript 內處理。