總覽
只要按照下列步驟進行即可:
查看目前的用戶端 ID 用量
開始遷移程序前,請先列出下列項目:
- 您使用用戶端 ID 存取的地圖平台服務。
- 使用用戶端 ID 的應用程式、網站或系統。
Google 已向受影響的客戶傳送通知電子郵件,說明用戶端 ID 將於 2025 年 5 月淘汰。您也可以在通知電子郵件中找到這項資訊。
在 Cloud 控制台的 Google 地圖指標頁面,您可以查看用戶端 ID 的最新使用狀態。
如需地圖平台服務清單:
- 在 Cloud 控制台中開啟「Metrics」(指標) 頁面。
- 使用下列設定篩選用量:
- 憑證:僅選取「project_number:<numerical identifier>」。
- 設定下列篩選器。
- 分組依據:API
應用程式、網站或系統的提示:
Cloud 控制台不會顯示應用程式、網站或系統的詳細資料。不過,您可以找到一些線索,瞭解用戶端 ID 流量的來源。步驟如下:
- 在 Cloud 控制台中開啟「Metrics」(指標) 頁面。
- 從下拉式選單中選取地圖平台服務。
- 使用下列設定篩選用量:
- 憑證:僅選取「project_number:<numerical identifier>」。
- 設定下列篩選器。
- 分組依據:平台或網域
- 針對需要檢查流量的每個 Maps Platform 服務,從步驟 2 開始重複執行。
準備 API 金鑰
所有用戶端 ID 都與 Google Cloud 專案相關聯,使用該專案的 API 金鑰,即可存取先前透過用戶端 ID 存取的功能。建議您遷移至相關聯的專案,以免發生配額問題或缺少功能。
- 找出與用戶端 ID 連結的雲端專案:
- 確認 Cloud 專案已連結至有效的帳單帳戶。
- 建立新的 API 金鑰,用於遷移用戶端 ID。
- 您可以重複使用雲端專案中的任何現有 API 金鑰。
- 您可以使用同一個雲端專案的多個 API 金鑰,例如區隔各項 Maps Platform 服務的流量,或區隔不同平台 (瀏覽器、行動應用程式等) 的流量。如需 API 金鑰管理的最佳做法,請參閱安全性指南。
保護 API 金鑰
請務必妥善保管 API 金鑰,防止未經授權的存取。
- 為 API 金鑰設定應用程式限制 (例如網站、IP 位址、Android 應用程式或 iOS 應用程式)。
- 設定 API 金鑰的 API 限制。
詳情請參閱 Google 地圖平台安全性指南。
如果是 Maps JavaScript API、Maps Static API 和街景服務 Static API,您可以將用戶端 ID 的信任參照網址,遷移至 API 金鑰限制。您可以在 Cloud 控制台查看信任的參照網址清單。
查看配額設定
請確認 Cloud 專案的配額設定符合預期。只有在您從用戶端 ID 呼叫 Maps JavaScript API 用戶端服務時,才需要執行這項操作。您可以在 Google 地圖配額頁面查看及調整配額設定。
提高 Maps JavaScript API 用戶端服務配額
如果您在 Maps JavaScript API 使用下列服務,遷移 API 金鑰後,配額用量會增加。
查看目前的配額設定和用量,並據此調整配額限制。
- 確認您是否使用用戶端 ID 存取 Maps JavaScript API 用戶端服務。
API 方法 |
用戶端服務 |
要調整配額的服務 |
google.routes.Directions.Javascript |
路線規劃服務 |
Directions API |
google.routes.DistanceMatrix.Javascript |
距離矩陣服務 |
Distance Matrix API |
google.maps.Elevation.Javascript |
海拔高度服務 |
Elevation API |
google.places.Geocoding.Javascript |
地理編碼服務 |
Geocoding API |
google.places.*.Javascript (google.places.Geocoding.Javascript 除外) |
Places Library |
Places API |
- 如果您不使用這些 API 方法,就不必擔心配額設定,因為用戶端 ID 流量已耗用專案配額。
- 預估用戶端 ID 配額用量
- 針對每項服務,請檢查「每秒」和「每天」精細程度。
- 「每秒」圖表:將流量尖峰乘以 60,即可得出額外的每分鐘配額需求。
- 「Per Day」(每日) 圖表:流量高峰應為每日所需的額外配額。
- 調整相應地圖平台服務的配額
- 根據您在步驟 1 中找到的方法名稱,調整對應服務的配額。
更新程式碼
將用戶端參數替換為金鑰參數
請將傳出 GMP API 呼叫中的驗證憑證從 URL&client={value} 更新為 URL&key={value}。如果應用程式使用 HTTP 存取 GMP 服務,請更新為使用 HTTPS。
更新報表管道參數
您可以在 API 要求中指定管道參數,追蹤各管道的用量。API 金鑰僅支援數值做為管道參數。如果用戶端 ID 的管道參數使用非數值,請更新為支援的數值。
詳情請參閱「Google 地圖平台報表」一文。
移除網路服務的簽章參數
使用 API 金鑰存取下列 Web Service API 時,不需要簽名參數。請只從 API 要求中移除簽章參數。
- Directions API (舊版)
- Distance Matrix API (舊版)
- Geocoding API
- Elevation API
- Time Zone API
詳情請參閱付費方案總覽。
Imagery API 的簽署 Secret
Maps Static API 和街景服務 Static API 仍需要簽章參數。他們會接受少量未簽署的要求,以便進行測試,但一旦達到正式環境中的門檻,就會開始失敗。將簽署密鑰從用戶端 ID 的密鑰,替換為 API 金鑰的密鑰。您可以使用相同的簽署演算法,但必須使用其他簽署密鑰。詳情請參閱「使用數位簽章」。
監控用戶端 ID 流量
部署完成後,請使用 Cloud 控制台資訊主頁,確認流量已成功遷移。用戶端 ID 流量會開始減少,在資訊主頁中依憑證分組時,會以「project_number:123456」格式顯示。
暫停用戶端 ID
強烈建議開發人員在遷移後暫停用戶端 ID。這是為了保護憑證不受任何非預期流量影響,並確認用戶端 ID 的剩餘用量不重要 (例如測試、快取、機器人等),且可傳回錯誤,不會造成業務影響。您可以在 Cloud 控制台暫停用戶端 ID。詳情請參閱「付費方案驗證總覽」。
自行暫時重新啟用用戶端 ID
Google Maps Platform 用戶端 ID 已於 2026 年 5 月進入分階段淘汰期,因此無法再保證服務可用性。在排定的服務終止程序中,系統會定期限制存取權。服務通常會在幾小時內自動恢復,但如果您需要立即恢復,可以選擇手動重新啟用存取權。
如要緊急恢復存取權,您可以透過 Google Cloud 控制台執行自助式重新啟用:
- 前往 Google Maps Platform 憑證頁面。
- 找出連結至用戶端 ID 的雲端專案。
- 按一下項目最右側的「取消暫停」圖示,即可還原服務。
如果您無法快速改用 API 金鑰,且希望暫時免除進一步中斷,請與 Google 地圖平台支援團隊聯絡,並提供下列詳細資料:
- 用戶端 ID
- 特定用途
- 預定遷移日期
- 業務影響評估
用戶端 ID 用量報表 - 來自帳單報表
如果使用者無法存取專案指標,例如帳單管理員 (尤其是 Maps Platform 平台合作夥伴),則可查看帳單報表,而非專案指標。雖然帳單報表有 1 到 2 天的延遲,但優點是可顯示超過 30 天的用量和費用深入分析。
您可以透過 Google Cloud 控制台監控用戶端 ID 使用情形,步驟如下:
- 前往 Google Cloud 控制台的「帳單」>「報表」頁面。
- (選用,僅適用於合作夥伴) 套用篩選器,選取所需的子帳單帳戶。
- 依標籤鍵
goog-maps-api-key-suffix將報表資料分組。這個標籤會顯示 API 金鑰的結尾字元。 - 如要找出用戶端 ID 流量,請尋找缺少
goog-maps-api-key-suffix標籤或該標籤為空的項目,因為用戶端 ID 要求不會填入這個標籤。 - 忽略不應與 API 要求相關聯的 SKU,例如訂閱 SKU。
疑難排解
如何查看要求是否失敗?
您可以在回應代碼圖表中查看錯誤統計資料,
ApiNotActivatedMapError 或 REQUEST_DENIED 錯誤
如果未在 Cloud 專案中啟用服務,就會看到 ApiNotActivatedMapError 或 REQUEST_DENIED 錯誤。按照操作說明啟用服務。
RefererNotAllowedMapError 個錯誤
如果來源網域未加入 API 金鑰,就會看到 RefererNotAllowedMapError 錯誤。查看「保護 API 金鑰」一節,並將網域新增至 API 金鑰。
OverQuotaMapError 或 OVER_QUERY_LIMIT 錯誤
如果設定的配額不足以涵蓋流量,系統會顯示 OverQuotaMapError 或 OVER_QUERY_LIMIT。查看「查看配額設定」部分,並據此調整配額。
「Requests to this API must be over SSL」錯誤
如果收到下列錯誤訊息,請將 API 要求從「http://」更新為「https://」。
{
"error_message" : "Requests to this API must be over SSL. Load the API with
\"https://\" instead of \"http://\".",
"results" : [],
"status" : "REQUEST_DENIED"
}