總覽
為提高驗證安全性和可靠性，地圖平台用戶端 ID 已於 2025 年 5 月 26 日淘汰，並於 2026 年 5 月 31 日停用。
您必須使用 API 金鑰憑證驗證 Google 地圖 API 服務流量，而非使用用戶端 ID。本指南說明如何從使用用戶端 ID 遷移至使用 API 金鑰。
只要按照下列步驟進行即可：
查看目前用戶端 ID 用量
開始遷移程序前，請列出下列項目：
- 您透過用戶端 ID 使用的地圖平台服務。
- 您使用用戶端 ID 的應用程式、網站或系統。
Google 已在 2025 年 5 月向受影響的客戶傳送電子郵件通知，說明用戶端 ID 即將淘汰。您也可以在通知電子郵件中找到這項資訊。
在 Cloud 控制台的「Google 地圖指標」頁面，您可以查看用戶端 ID 使用情況的最新狀態。
如需地圖平台服務清單：
- 在 Cloud Console 中開啟「指標」頁面。
- 使用下列設定篩選用量：
- 憑證：僅選取「project_number:<numerical identifier>」。
- 設定下列篩選器。
- 分組依據：API
應用程式、網站或系統提示：
Cloud Console 不會顯示應用程式、網站或系統的詳細資料。 但您可以從中找出用戶端 ID 流量來源的蛛絲馬跡。步驟如下：
- 在 Cloud Console 中開啟「指標」頁面。
- 從下拉式選單中選取地圖平台服務。
- 使用下列設定篩選用量：
- 憑證：僅選取「project_number:<numerical identifier>」。
- 設定下列篩選器。
- 分組依據：平台或網域
- 針對需要檢查流量的每項 Maps Platform 服務，從步驟 2 開始重複執行。
準備 API 金鑰
所有用戶端 ID 都與 Google Cloud 專案相關聯，使用該專案的 API 金鑰，即可存取先前使用用戶端 ID 時的相同功能。建議您遷移至相關聯的專案，以免發生配額問題或缺少功能。
- 找出與用戶端 ID 連結的 Cloud 專案：
- 確認 Cloud 專案已連結至開放的帳單帳戶。
- 建立新的 API 金鑰，
用於遷移用戶端 ID。
- 您可以沿用 Cloud 專案中的現有 API 金鑰。
- 您可以從同一個 Cloud 專案使用多個 API 金鑰，例如為了區隔各項地圖平台服務的流量，或是區隔不同平台 (瀏覽器、行動應用程式等) 的流量。如需 API 金鑰管理最佳做法，請參閱安全性指南。
保護 API 金鑰
請務必妥善保存 API 金鑰，避免未經授權的存取。
- 為 API 金鑰設定應用程式限制 (例如網站、IP 位址、Android 應用程式或 iOS 應用程式)。
- 設定 API 金鑰的 API 限制。
詳情請參閱 Google 地圖平台安全指南。
對於 Maps JavaScript API、Maps Static API 和 Street View 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，即可得出每分鐘的額外配額需求。
- 每日圖表：尖峰流量應為每日額外配額需求。
- 調整對應地圖平台服務的配額
- 根據步驟 1 中找到的方法名稱，調整對應服務的配額。
更新程式碼
將用戶端參數換成金鑰參數
在傳出的 GMP API 呼叫中，將驗證憑證從 URL&client={value} 更新為 URL&key={value}。如果您的應用程式使用 HTTP 存取 GMP 服務，請更新為使用 HTTPS。
更新報表適用的管道參數
如要追蹤各管道的使用情況，請在 API 要求中指定管道參數。API 金鑰僅支援管道參數的數值。如果使用用戶端 ID，且管道參數含有任何非數值，請將其更新為支援的數值。
詳情請參閱「Google 地圖平台報表」一文。
移除 Web 服務的簽章參數
使用 API 金鑰存取下列 Web 服務 API 時，不需要簽章參數。請只從 API 要求中移除簽章參數。
- Directions API (舊版)
- Distance Matrix API (舊版)
- Geocoding API
- Elevation API
- Time Zone API
詳情請參閱「付費方案總覽」。
圖像 API 的簽署密鑰
Maps Static API 和 Street View Static API 仍須使用簽章參數。為進行測試，他們會接受少量沒有簽章的要求，但一旦達到正式版中的門檻，就會開始失敗。將簽署密鑰從用戶端 ID 專用的密鑰，改為 API 金鑰專用的密鑰。您可以使用相同的簽署演算法，但必須使用其他簽署密鑰。詳情請參閱「使用數位簽章」。
監控用戶端 ID 流量
部署完成後，請使用 Cloud Console 資訊主頁確認流量是否已順利遷移。您會開始看到用戶端 ID 流量減少，以憑證分組時，資訊主頁會以「project_number:123456」格式顯示。
暫停用戶端 ID
強烈建議開發人員在遷移後暫停用戶端 ID。這是為了保護您的憑證免於任何非預期流量，並確認用戶端 ID 的任何剩餘用量都不重要 (例如測試、快取、機器人等)，且可傳回錯誤，不會對業務造成影響。您可以在 Cloud 控制台暫停用戶端 ID。詳情請參閱「付費方案驗證總覽」一文。
疑難排解
如何查看要求是否失敗？
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"
}