Maps JavaScript API:取得 API 金鑰或用戶端 ID

注意事項:Google 地圖平台付費方案不再開放註冊或提供給新客戶。

選擇驗證方法

使用 Maps JavaScript API 的方法如下:

  • 採用付費方案的客戶可以使用 API 金鑰用戶端 ID 來驗證要求。
  • 使用舊版授權的客戶則必須使用用戶端 ID 來驗證要求。

以下概述各種驗證方法可用的工具和報表:

  • 使用 API 金鑰進行驗證 (付費方案)
    如果使用 API 金鑰來驗證要求,您可以:
    • 在 Google Cloud Console 的「API」頁面管理所有的 API。
    • 透過 Cloud Console 存取應用程式的即時使用資料和 30 天的歷來使用資料。
    • channel 參數加進要求中,以便查看更詳細的使用情況報表。
    • 透過 Cloud Console 查看內含超過 30 天資料的使用情況報表。
  • 使用用戶端 ID 進行驗證 (付費方案或舊版授權)
    使用用戶端 ID 來驗證要求,您可以:
    • channel 參數加進要求中,以便查看更詳細的使用情況報表。
    • 透過 Cloud Console 查看內含超過 30 天資料的使用情況報表。
    • 使用 Maps JavaScript API 適用的地圖 Analytics (分析) 工具。

進一步瞭解付費方案客戶可用的報表

使用 API 金鑰進行驗證

建立 API 金鑰

API 金鑰是一組專屬 ID,用於驗證與您專案有關的使用權限及帳單處理請求。您的專案必須有至少一個相關聯的 API 金鑰。

建立 API 金鑰的方法如下:

  1. 在 Cloud Console 的專案選取器頁面中,選取或建立您想新增 API 金鑰的 Google Cloud 專案。

    前往專案選取器頁面

    注意事項:付費客戶應使用與付費帳戶連結的專案,才能運用方案的完整功能。購買授權後,您會收到以下列格式編寫的付費資產名稱:gme-[company] > proj-[number] ([type])。 為確保您存取的是正確的專案,請透過 console.cloud.google.com/project/number (將 number 替換成專案編號) 以「專案擁有者身分」登入 Cloud Console。 您可以在歡迎信中查看專案擁有者是誰。

  2. 前往「Google 地圖平台」>「憑證」頁面。

    前往「憑證」頁面

  3. 在「憑證」頁面上,按一下 [建立憑證] > [API 金鑰]
    「建立的 API 金鑰」對話方塊會顯示您新建立的 API 金鑰。
  4. 按一下 [關閉]
    新建立的 API 金鑰便會出現在「憑證」頁面的「API 金鑰」下方。
    (在實際工作環境中使用新建立的金鑰前,記得要先限制 API 金鑰。)

在應用程式中加入 API 金鑰

每個 Google 地圖平台要求都必須包含 API 金鑰。請將以下範例中的 YOUR_API_KEY 替換成您的 API 金鑰。

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

使用 API 金鑰的要求必須透過 HTTPS 傳送,至於使用用戶端 ID 的要求,也建議採用 HTTPS。此外,應用程式要求如果含有敏感的使用者資料 (如使用者所在位置),也必須採用 HTTPS。

限制 API 金鑰

限制 API 金鑰可確保只有經授權的要求才能使用 API 金鑰,進而提升您應用程式的安全性。我們極力建議您按照操作說明設定 API 金鑰的限制。詳情請參閱 API 安全性最佳做法

限制 API 金鑰的方法如下:

  1. 前往「Google 地圖平台」>「憑證」頁面。

    前往「憑證」頁面

  2. 選取您要設定限制的 API 金鑰。畫面隨即顯示 API 金鑰屬性頁面。
  3. 在「金鑰限制」下方,設定下列限制:
    • 應用程式限制:
      1. 如要接受來自您提供的清單中網站提出的要求,請從「應用程式限制」清單中選取 [HTTP 參照網址 (網站)]
      2. 指定一或多個參照網址網站。舉例來說,*.google.com 接受網址以 google.com 結尾的所有網站 (例如 https://developers.google.com)。

        注意事項:file:// 參照網址需要使用特殊表示法才能新增至金鑰限制。您必須將「file://」部分替換為「__file_url__」,參照網址才能新增至金鑰限制。例如,「file:///path/to/」的格式應為「__file_url__//path/to/*」。啟用 file:// 參照網址後,建議您定期檢查使用情形,確保與您的預期一致。

    • API 限制:
      1. 按一下 [限制金鑰]
      2. 從「選取 API」下拉式選單中選取 [Google 地圖平台]。 如果選單未列出 Google 地圖平台,您必須先加以啟用
      3. 如果您的專案使用地點介面集程式庫,也請一併選取 [Places API]。同樣地,如果您的專案使用 JavaScript API 中的其他服務 (路線規劃服務距離矩陣服務海拔高度服務及/或地理編碼服務),您也必須先啟用再於清單中選取相對應的 API。
  4. 如要完成變更,請按一下 [儲存]

使用用戶端 ID 進行驗證

購買 Google 地圖平台付費方案授權後,您會收到 Google 寄送的歡迎電子郵件,內含您的用戶端 ID,可供您用來存取 Google 地圖平台付費方案的各式報表與工具

所有用戶端 ID 開頭的前置字串都是 gme-。以下是一般用戶端 ID 的格式。

gme-[公司] > proj-[編號] ([類型])

您可以使用用戶端 ID 搭配網址註冊 (取代 API 金鑰),來驗證 Maps JavaScript API 要求。

注意事項:此用戶端 ID 不是金鑰,而且只能由您授權的網址使用。進一步瞭解如何註冊授權的網址

在載入 API 時指定用戶端 ID

以下程式碼示範如何在載入 Maps JavaScript API 時,以自己的用戶端 ID 取代 YOUR_CLIENT_ID。

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

您必須附加 v=quarterly 參數來指定發布版本 (也稱為功能穩定版本) 或較舊版本。使用實驗版本的應用程式無法享有 Google 地圖平台付費方案服務水準協議的權益。

注意:如果您原先使用 API 金鑰進行驗證,但現在要改用用戶端 ID,就必須先移除 key 參數才能載入 API。如果要求同時包含用戶端 ID 與 API 金鑰,API 就會無法載入

註冊授權的網址

為避免第三方網站使用您的用戶端 ID,只有您清單所列的特別授權網址才能使用您的用戶端 ID。

查看您已授權的網址或為更多網址授權的方法如下:

  1. 登入 Google Cloud Console
  2. 按一下左側選單中的 [地圖:管理用戶端 ID]

您一次最多可新增 100 個網址。而每一個用戶端 ID 可連結最多 3,000 個已授權網址。假如您預計讓應用程式代管的 Google 地圖內容超過 3,000 個地點,請改用 API 金鑰。

以下是有關授權網址的注意事項:

網域名稱或 IP 位址不一定要開放公開存取。
舉例來說,http://myintranethttp://192.168.1.1 都是有效網址。
指定網域的所有子網域都在授權範圍內。
例如,如果 http://example.com 獲得授權,則 http://www.example.com 也在授權範圍內。但反向推論並不成立,亦即 http://www.example.com 獲得授權,http://example.com 卻不一定在授權範圍內。
已獲得授權路徑的所有子路徑也會獲得授權。
例如,如果 http://example.com 已獲得授權,則 http://example.com/foo 也同樣已獲授權。此外,因為指定網域的子網域也會獲得授權,因此 http://sub.example.com/bar 也同樣獲得授權。
路徑會區分大小寫。
舉例來說,http://www.example.com/ThisPath/ 不等於 http://www.example.com/thispath/
您可以限定只有使用特定連接埠的網址才算是有效網址。
例如,如果指定 http://example.com:8080/foo,則不會授權 http://example.com
系統會將 HTTP 和 HTTPS 通訊協定視為不同的網址。
舉例來說,即使 https://example.com 已獲得授權,http://example.com 也不一定已獲得授權。

上述所有規則適用於每項授權,因此請審慎規劃您的授權。例如,因為指定路徑的所有子路徑和子網域都會獲得授權,因此您可能會將原本沒有打算授權的網頁也一併授權。舉例來說:

http://example.com/ 也會授權 http://sub.example.com/path

詳情請參閱「排解 Google 地圖平台付費方案網址授權相關問題」一文。