Google Maps APIs for Work 推出前檢查清單

本頁面僅適用於舊版 Maps APIs for Work 或 Maps API for Business 授權的客戶。本頁面不適用於 2016 年 1 月推出之新版 Google Maps APIs Premium Plan 的客戶。

  1. 確保您的團隊可以存取必要資源
    1. 接收 Google Maps APIs for Work 歡迎函
    2. 存取並使用 Google Cloud Support Portal
    3. 訂閱相關通知訊息
    4. 備妥支援熱線
  2. 應用程式最佳化
    1. 設定防火牆以允許存取 Google Maps APIs 服務
    2. 透過 SSL 載入 API
    3. 在您的 SSL 網域中使用用戶端 Maps API
    4. 正確的 API 版本選擇
    5. 最佳化頁面檢視使用量
    6. 用戶端 Vs.伺服器端設計:選擇適合您使用案例的設計
    7. Web 服務配額與管理
    8. 負載測試
  3. 從免費版遷移到 Google Maps APIs for Work 實作
    1. 網域授權
    2. 整合用戶端編號
    3. 利用密碼編譯金鑰來簽署 Web 服務要求
    4. 追蹤應用程式使用量與管道參數
    5. 從 API 要求中移除過時參數

確保您的團隊可以存取必要資源

接收 Google Maps APIs for Work 歡迎函

為何重要:您的歡迎函是您的 Google Maps APIs for Work 入門套件,很可能也是您的急救箱。其中包含非常重要的資訊,例如您的用戶端編號和密碼編譯金鑰,是開始使用 Google Maps APIs 的必要資訊。萬一您使用 Google Maps APIs 時遇到任何技術問題,其中也包含聯絡 Google Cloud Support 團隊所需的全部資訊。

存取並使用 Google Cloud Support Portal

為何重要:支援入口網站能讓您存取各種資訊,例如使用量報告、最新消息,以及實用的開發人員資源。更重要的是,萬一您在開發或推出產品時遇到任何技術問題,支援入口網站能讓您向 Google Maps APIs 支援團隊提出支援案件。您可以在下列網址存取支援入口網站:

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

推出前,請花點時間來為所有負責維護應用程式的開發人員啟用支援入口網站的存取權。萬一您遇到技術問題,支援入口網站的存取權有雙重好處,一是可讓您的團隊成員聯絡支援人員,二是可讓我們的支援團隊聯絡您組織中正確的專案關係人。例如,萬一我們偵測到可能讓您的應用程式無法運作的不正常流量或行為,支援團隊可能需要聯絡您的組織。確保我們可以聯絡正確的開發人員,便可能是應用程式意外中斷與防止其中斷之間的關鍵差異。如果您沒有支援入口網站的存取權,請在此處要求存取權:

要求 Google Cloud Support Portal 帳戶

訂閱相關通知訊息

為何重要:為確保您能掌握 Google Maps APIs 的最新發展與變更,建議您訂閱相關通知訊息。您應該訂閱 Google Geo Developers Blog 以及您所使用的 API 之相關 Google 網上論壇,如此處所述:

https://developers.google.com/maps/faq#notify

請花點時間來訂閱您正在使用或計畫使用的 API 之論壇。您也可以訂閱下列 RSS 資訊提供:

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

以接收來自 Google Maps APIs 支援團隊的更新。

備妥支援熱線

美國內的客戶請撥打 1-877-355-5787,美國外的客戶請撥打 +1 404-978-9282

為何重要:此熱線是您以電話聯繫 Google Cloud Support Portal 的方式。請將此頁面加入書籤來取得最新的支援熱線號碼。請注意,儘管我們歡迎您利用支援熱線來回報技術問題,但此熱線僅處理生產停擺、無法使用服務的案例。我們的優先順序層級已界定於以下網域:

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 APIs Premium Plan 授權、舊 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

為何重要:透過 SSL 載入 Maps JavaScript APIWeb 服務 APIimage API 的應用程式必須從 https://maps.googleapis.com 載入,而非舊版主機名稱 https://maps-api-ssl.google.com

在您的 SSL 網域中使用用戶端 Maps API

為何重要:使用 SSL 網域中的用戶端 API 時,您必須明確授權您的 HTTPS 網域以確保要求不會遭到拒絕。請注意,授權 http://yourdomain.com 並不會自動啟用其對等的 SSL 網域 https://yourdomain.com。您可以在 Google Cloud Support Portal 中,從左側的導覽選單中選擇 [Maps:Manage Client ID] 連結來查看已授權的網域清單。要疑難排解在 SSL 網域使用用戶端 API 的相關錯誤,建議您先檢查頁面上是否有任何透過 HTTP 載入的元素。另請參閱我們的為 Google Maps APIs for Work 實作的疑難排解授權文章。

正確的 API 版本選擇

為何重要:開始開發應用程式前,必須留意哪些版本的 API 已被淘汰。選擇以未淘汰的 API 版本進行開發,最終會在已淘汰版本變成無法使用時,為您省下開發時間與成本。

您也務必要了解 API 版本配置,以避免意外在您的環境中使用到不適當的 API 版本:

https://developers.google.com/maps/documentation/javascript/versions

例如,每晚更新(意即:實驗功能)版本的 API 可能適用於您的開發/測試環境中,但強烈不建議您將每晚更新版本用於生產環境。我們的 SLA 僅適用於穩定版本的 API,因此您在生產環境中應只使用穩定版本。

最佳化頁面檢視使用量

為何重要:如果您不總是在網站上顯示 Google 地圖,為什麼要為它花錢呢?建議您以非同步方式,將 Maps API 載入到真正會顯示地圖的頁面上,這是更有效率地使用頁面檢視的最佳做法。這會大幅減少應用程式取用已購買頁面的檢視數量。請記得,每次載入 API 的頁面重新整理時,便會產生一次頁面檢視。因此,設計您的應用程式時,建議載入 API 的網站僅在絕對必要時才啟動頁面重新整理。

用戶端 Vs.伺服器端設計:選擇適合您使用案例的設計

為何重要:選擇用戶端或伺服器端處理方式是一項架構層面的抉擇,對您應用程式的穩定性和擴充性來說至關重要。大致上,伺服器端方式應該用於離線(也就是在應用程式之外)記錄的前期、後期處理。另一方面,用戶端方式應該用於您應用程式中會與使用者互動(也就是即時處理使用者提交的要求)的部分。

在應該使用用戶端方式的地方部署伺服器端方式,是造成超出配額、並進而使應用程式無法運作的主因。強烈建議您在設計或推出依賴伺服器端呼叫的應用程式前,先參閱地理編碼策略文件。

Web 服務配額與管理

為何重要:根據預設,Web 服務配額設定在每 24 小時 100,000 個查詢。如需進一步了解每個 API 的配額明細,請參閱使用限制文件。若要確認您的用戶端編號可以使用多少配額,請提出支援案件。推出服務前,請務必了解各種配額相關錯誤(例如 OVER_QUERY_LIMITUser Rate Limit Exceeded),並在應用程式中設定正確的邏輯,以便在您超過配額時,對這些錯誤做出回應。請先從閱讀 Google Maps APIs Web 服務使用限制文章開始。了解並實作這些概念將能大幅降低應用程式超過其允許的配額、遭到 Google 封鎖,和/或無法運作的機率。

負載測試

為何重要:針對即時 Google 服務進行負載測試會導致應用程式超過允許配額,而遭到 Google 封鎖。

Google Maps APIs 可以處理非常龐大的資料量;在 2012 年,聖誕老人追蹤器每秒處理了 1,600,000 個要求。因此,您並不需針對 Google 服務進行負載測試。應用程式負載測試反而須確保您的應用程式能在不超過 Maps API 配額的情況下,處理大量要求。範例:如果您的 Google Maps Geocoding API 配額是 20 QPS(每秒查詢數),則應用程式負載測試須確保您的應用程式能在不傳送超過 20 QPS 至 Google Maps Geocoding API 的情況下,處理 600 QPS。

若要安全地達成此目標,您應針對模擬(假)API(可吸收大量要求並做出有效回應的服務)進行負載測試,「而不」涉及 Google Maps APIs。如此,您不必冒著被 Google Maps APIs 封鎖的風險,便能進行應用程式負載測試。

請參考這個實作為小型 Google App Engine 應用程式的模擬 API 範例: https://github.com/googlemaps/js-v2-samples/blob/gh-pages/mock_maps_apis/。您可以將其上傳到您自己的 App Engine 應用程式(於 https://appengine.google.com/ 註冊一個後),再讓應用程式傳送要求到那裡,而非 maps.googleapis.com。

一般而言,預設(免費)App Engine 配額應該足以讓您以遠超過您 Maps API Web 服務的配額進行應用程式負載測試。請確認您的應用程式已設定正確的 User-Agent 標頭來啟用回應壓縮。這是確保能有效率地使用頻寬的關鍵,而頻寬對處理大量純文字 (JSON/XML) 回應的 App Engine 應用程式來說尤其重要。萬一您的 App Engine 應用程式需要更多配額,您也可以啟用計費,雖然這幾乎不太可能發生。

將 API 從免費版遷移到 Google Maps APIs for Work 授權

網域授權

為何重要:為避免未經授權的網站使用您的用戶端編號,Google Maps JavaScript API 要求您針對所有會利用您用戶端編號的網站,透過我們的支援團隊授權所有網域。如果嘗試使用您用戶端編號的網站不符合已授權使用您用戶端編號的網址,則該網站便無法透過您的用戶端編號使用 API。您可隨時授權網域,因此請確保您在推出服務前,已授權您所有網站的網域。

Google Street View Image APIGoogle Static Maps API 可用於用戶端或伺服器端,且皆會產生頁面檢視數。因此,這些 API 需要您使用密碼編譯金鑰來簽署要求,並授權所有利用這些 API 的網域。這會確保您的應用程式已被正確計費、遵循我們的服務條款、已被支援,並已涵蓋在我們的 SLA 中。

您可以在 Google Cloud Support Portal 中,從左側的導覽選單中選擇 [Maps:Manage Client ID] 連結來查看已授權的網域清單。

針對授權問題,建議您在提出支援案件前,先檢閱為 Google Maps APIs for Work 實作的疑難排解授權文章。

整合用戶端編號(例如 &client=gme-yourclientid

為何重要:您可為應用程式做的一件最重要的工作,便是確認您在要求中包含 '&client=gme-yourclientid'。您可以在核發給組織主要聯絡人的歡迎函中找到您的唯一用戶端編號。用戶端編號會將您的要求識別為 Google Maps APIs for Work 要求。您必須在應用程式中包含用戶端編號,才能使用 Google Maps APIs for Work 專屬的功能。若要接受技術支援,並確保應用程式涵蓋於我們的 SLA 中,用戶端編號的納入也是必要的。

利用密碼編譯金鑰(例如 vNIXE0xscrmjlyV-12Nj_BvUPaw=)來簽署 Web 服務要求

為何重要:您的私密密碼編譯金鑰可用來產生簽章,告知 Google 您的要求來自受信任的來源。您可以在核發給組織主要聯絡人的歡迎函中找到您的密碼編譯金鑰。我們的 Web 服務 需要身為 Google Maps APIs for Work 客戶的您使用密碼編譯金鑰來簽署要求。這會為您的要求增加一層安全性,更進一步保護與您用戶端編號關聯的配額。

請注意:密碼編譯金鑰的作用是產生簽章。請勿將其做為簽章本身,附加到要求上。您的密碼編譯金鑰就像 ATM 密碼。其作用是提供驗證方式以存取您的帳戶,因此絕對不要公開分享或揭露在未受信任的來源上。我們的伺服器會拒絕未正確簽署的 Google Maps APIs for Work Web 服務要求,因此請務必在推出前,讓應用程式正確簽署要求(注意:v2 Google Maps Geocoding API 目前不需要簽章)。請參閱我們的網址簽署文件:

https://developers.google.com/maps/premium/previous-licenses/webservices/auth

追蹤應用程式使用量與管道參數

為何重要channel 參數是一種選擇性參數,可指定不同管道給每個應用程式,讓您追蹤用戶端編號下的使用量。您不需將管道參數註冊到用戶端編號。只要新增管道參數到 API 要求,實作後一兩天內,它們就會出現在您的支援入口網站使用量報告中。您可以自行決定要在哪裡實作管道,以及使用量彙總的方式。請在推出前決定是否要在應用程式整合管道參數以追蹤應用程式使用量:

https://developers.google.com/maps/premium/previous-licenses/clientside/quota#reporting

channel 參數必須使用下列格式:

  • 必須為 ASCII 英數字串。
  • 允許句點 (.)、底線 (_) 和連字號 (-) 字元。
  • channel 參數不區分大小寫;大寫、大小寫混用、小寫 channel 參數都會合併成相對應的小寫。例如,CUSTOMER 管道上的使用量會和 customer 管道上的使用量合併。

每個用戶端編號最多可以實作 2,000 個不同管道。

若要使用 channel 參數,請將其和用來傳遞用戶端編號的 client 參數一同包含在要求網址中。

請注意,管道參數必須是每個應用程式中靜態指派的值。不得動態產生此參數,或用來追蹤個別使用者。

從 API 要求中移除過時參數(例如 '&key=ABQIAAAA…' 參數)

為何重要:為正確載入 Google Maps JavaScript API,您必須納入用戶端編號。您也必須移除所有 key 參數。如果您的要求同時包含用戶端編號和金鑰,此要求將會失敗。

請參考 Google Maps APIs for Work 指南來取得如何正確為每個 API 格式化 Google Maps APIs for Work 要求的完整資訊: https://developers.google.com/maps/premium/previous-licenses/