用戶端 ID 遷移指南

總覽

為提升驗證安全性和可靠性，Maps 平台用戶端 ID 已於 2025 年 5 月 26 日淘汰，並將於 2026 年 5 月 31 日後無法再使用。

您必須使用 API 金鑰憑證，而非用戶端 ID 來驗證 Google 地圖 API 服務流量。本指南說明如何從使用用戶端 ID 改為使用 API 金鑰。

只要按照下列步驟進行即可：

  1. 查看目前的用戶端 ID 用量
  2. 準備 API 金鑰
  3. 查看配額設定
  4. 更新程式碼
  5. 監控用戶端 ID 流量
  6. 暫停用戶端 ID

查看目前的用戶端 ID 用量

開始遷移程序前，請列出下列項目：

  • 您使用用戶端 ID 搭配使用的 Google 地圖平台服務。
  • 您使用用戶端 ID 的應用程式、網站或系統。

Google 已向受影響的客戶傳送電子郵件通知，說明客戶端 ID 將於 2025 年 5 月淘汰。您也可以在通知電子郵件中找到這項資訊。

您可以在 Cloud 控制台的 Google 地圖指標頁面上，查看用戶端 ID 使用情形的最新狀態。

如需 Google 地圖平台服務的清單：

  1. 在 Cloud Console 中開啟「指標」頁面。
  2. 使用下列設定篩選用量：
    • 憑證：僅選取「project_number:<數字 ID>」。
  3. 設定下列篩選器。
    • 分組依據：API

應用程式、網站或系統提示：

Cloud 控制台不會顯示應用程式、網站或系統的詳細資料。不過，您可以找到一些用戶端 ID 流量來源的線索。步驟如下：

  1. 在 Cloud Console 中開啟「指標」頁面。
  2. 從下拉式選單中選取 Google 地圖平台服務。
  3. 使用下列設定篩選用量：
    • 憑證：僅選取「project_number:<數字 ID>」。
  4. 設定下列篩選器。
    • 分組依據：平台或網域
  5. 針對需要檢查流量的每項地圖平台服務，重複執行步驟 2。

準備 API 金鑰

所有用戶端 ID 都會與 Google Cloud 專案建立關聯，使用該專案的 API 金鑰即可存取先前透過用戶端 ID 存取的功能。建議您遷移至相關聯的專案，以免出現配額或功能遺漏的問題。

  1. 找出用戶端 ID 連結的 Cloud 專案：
  2. 請確認 Cloud 專案已連結至有效的帳單帳戶。
  3. 建立新的 API 金鑰，用於用戶端 ID 遷移作業。
    • 您可以重複使用 Cloud 專案中的任何現有 API 金鑰。
    • 您可以使用同一 Cloud 專案中的多個 API 金鑰，例如為每項 Google 地圖平台服務區分流量，或區分來自不同平台 (瀏覽器、行動應用程式等) 的流量。如要瞭解 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 金鑰遷移後，您會發現配額用量增加。

查看目前的配額設定和目前用量，並據此調整配額上限。

  1. 確認您是否使用 Maps JavaScript API 用戶端服務搭配用戶端 ID。
    • 在 Cloud Console 中開啟「指標」頁面。
    • 使用下列設定篩選用量：
      • 分組依據：API 方法
      • 憑證：僅選取「project_number:<數字 ID>」。
    • 接著，您會在「依 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，即可瞭解每分鐘額外配額的需求。
    • 「每日」圖表：高峰流量應為額外的每日配額需求。
  • 調整對應 Google 地圖平台服務的配額
    • 根據您在步驟 1 中找到的方法名稱，調整對應服務的配額。

更新程式碼

在傳出的 GMP API 呼叫中，將驗證憑證從 URL&client={value} 更新為 URL&key={value}。如果您的應用程式使用 HTTP 存取 GMP 服務，請更新應用程式以使用 HTTPS。

移除網路服務的簽名參數

對於 Web 服務 API (*)，如果您使用 API 金鑰存取這些 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 控制台資訊主頁確認流量是否已成功遷移。您會開始看到用戶端 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。請查看「查看配額設定」部分，並據此調整配額。

「對此 API 的請求必須透過 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"
}