本頁面由 Cloud Translation API 翻譯而成。

使用 Air Quality API 網路服務的最佳做法

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

本指南將說明一些常見做法，協助您設定網路服務要求和處理服務回應。請參閱開發人員指南查看 Air Quality API 的完整說明文件。

什麼是網路服務？

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

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

使用以下方式要求目前的每小時空氣品質 currentConditions 方法是傳送 HTTP POST 要求至：

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

傳遞 JSON 主體要求傳入定義位置的要求中

注意：所有 Air Quality 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 而遭到封鎖。

指數型退讓

在極少數情況下，系統可能會在處理要求時發生錯誤；您可能會收到 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 呼叫因為就算是在不同裝置之間同步平均分配時間設計不良的應用程式會在每分鐘的開始時，產生比正常值高出六十倍的流量尖峰。

相反的，可以考慮將第二個鬧鐘設定為隨機選擇的時間。當第二個鬧鐘觸發時，應用程式會呼叫所需的任何 API，並儲存結果。當應用程式想要在一開始就更新顯示畫面時，會使用不必再次呼叫 API使用這種方法時，API 呼叫會在一段時間內平均分散。此外，在更新顯示畫面時，API 呼叫不會延遲算繪。

除了每一刻開始，也應特別留意其他常見的同步處理時間「不」在指定小時開始時是每天午夜，而從每天午夜開始。

處理回應

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

Google 地圖網路服務提供但不代表使用者容易使用執行查詢時比起顯示一組資料，您可能會希望輕鬆分配獎金一般來說，您會想要剖析網路服務的回應，並只擷取您感興趣的值。

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