API 金鑰最佳做法

凡是使用 Google Maps Platform API 和 SDK 的應用程式和專案,都必須具備 API 金鑰。本文件說明 API 金鑰的用途、如何保護金鑰 (就同保護其他憑證),以及應為專案設定哪些限制。

API 金鑰簡介

API 金鑰是以專案為主的憑證,有以下兩種用途:

  • 識別專案
    識別呼叫 API 或 SDK 的應用程式或專案。
  • 授權專案
    檢查發出呼叫的應用程式是否已獲得呼叫 API 或 SDK 的權限,並啟用專案中的 API 或 SDK。

API 金鑰建立後就會與專案產生關聯,而且能辨識發出呼叫的專案,然後連結用量資料,並確保一律拒絕來自其他專案的呼叫。

保護 API 金鑰

請妥善保護您應用程式目前使用的所有 Google 地圖平台產品 API 金鑰。指定相關限制,或是在應用程式中導入 Google 地圖平台 API 適用的最佳做法,都是您可以採用的保護措施。一旦未受保護的憑證外洩,可能會讓憑證遭到誤用,導致帳戶產生非預期的費用。

下列做法是 API 金鑰的保護策略;如需個別 Google 地圖平台產品 (例如 Maps JavaScript API) 適用的做法,請參閱「API 金鑰限制和最佳做法」一節。

  • 限制 API 金鑰您可以限制 API 金鑰只能用於特定 IP 位址、參照網址/行動應用程式及特定 API,藉此保障 API 金鑰安全;萬一金鑰遭駭,也可大幅減輕受到的影響。

    您可以在主控台開啟「憑證」頁面,然後建立新的 API 金鑰並依需求進行相關設定,或是編輯現有 API 金鑰的設定,藉此指定金鑰的套用方式和 API 限制。完整詳情請參閱「限制 API 金鑰」一節。

  • 讓不同的應用程式使用獨立的 API 金鑰這個做法可限制每個金鑰的範圍,要是 API 金鑰遭駭,您可以直接刪除及撤銷受影響的金鑰,無須更新其他 API 金鑰。
  • 刪除不需要的 API 金鑰。

    刪除 API 金鑰的做法如下:

    1. 前往憑證面板
    2. 選取要刪除的 API 金鑰。
    3. 按一下靠近頁面頂端的 [刪除] 按鈕。
    4. 畫面出現「刪除憑證」彈出式視窗時,按一下 [刪除]
  • 重新產生 API 金鑰時請特別謹慎如果將應用程式從舊 API 金鑰遷移至重新產生的 API 金鑰,需要超過 24 小時的時間,則未更新的執行個體會繼續參照舊金鑰 (其將在重新產生 API 金鑰 24 小時後刪除),因而無法運作。

    重新產生 API 金鑰時,預計會有以下情況:

    • 重新產生金鑰。
    • 新金鑰會沿用舊金鑰的所有限制。
    • 系統開始倒數 24 小時,並在時間到後刪除舊金鑰。
  • 密切觀察 API 使用情況是否有任何異常若發現未經授權的使用情況,請輪替金鑰並通知 Google。

    在輪替之前,先在檔案中建立副本,以便留存與金鑰相關聯的限制。

  • 在使用 Maps Web Service APIStatic Web API 的應用程式中,請採用下列方法來保護應用程式和 API 金鑰:

    • 不要直接在程式碼中嵌入 API 金鑰或簽署密鑰請勿直接在應用程式的程式碼中嵌入 API 金鑰或任何其他私密資訊,建議做法是將這類資訊放在環境變數中,或放在包含檔案內並與大量程式碼分開儲存 (應儲存於應用程式原始檔存放區之外)。這樣當您要共用程式碼,共用檔案內就不會含有 API 金鑰或簽署密鑰。
    • 不要將 API 金鑰或簽署密鑰儲存在應用程式原始碼樹狀結構中的檔案內如果您將 API 金鑰或任何其他私密資訊儲存在檔案中,請將這類檔案存放在應用程式原始碼樹狀結構之外的位置,以免金鑰或其他私密資訊出現在原始碼控管系統中。假如您使用的是公開原始碼管理系統 (例如 GitHub),特別需要注意這點。
    • 公開發布前應先檢查程式碼在公開發布程式碼之前,請確保程式碼內沒有 API 金鑰、簽署密鑰或任何其他私密資訊。
  • 在使用 Web Service APIStatic Web API 的行動應用程式中,考慮採用下列一或多項技術來進一步保護 API 金鑰或簽署密鑰:

限制 API 金鑰

API 金鑰是憑證,請務必謹慎保管。建議您至少應採用以下建議做法,以保障金鑰的安全;此外,請務必設定相關限制,減輕 API 金鑰遭駭時可能受到的影響。

有關限制 API 金鑰的做法,您可以指定應用程式限制,也可以設定一或多項 API 限制。

應用程式限制:用來限制只能在特定網站 (IP 位址和網站) 或平台 (Android 和 iOS) 使用 API 金鑰。您在這個類別只能選取最多一項限制,相關詳情請見不同平台適用的 Google 地圖平台 API

API 限制:用來限制只能在一或多個 Google 地圖平台 API 或 SDK 使用 API 金鑰。系統會處理已與 API 金鑰建立關聯的 API 或 SDK 的使用要求;如果要求使用的 API 或 SDK 並未與 API 金鑰建立關聯,要求將會失敗。您可以視需要為 API 金鑰指定 API 限制,數量不限,但必須確保與 API 金鑰建立關聯的 API 或 SDK 支援該金鑰的應用程式限制

為 API 金鑰設定應用程式限制

  1. 前往憑證面板
  2. 選取要設定限制的 API 金鑰,畫面隨即顯示 API 金鑰屬性頁面。
  3. 在「金鑰限制」下方,選取 [應用程式限制]。
    請選取其中一個限制類型,然後按照限制清單中的說明提供必要資訊。
    限制類型 說明
    HTTP 參照網址

    接受由您提供的網站清單中所列的要求。

    在類型下方指定一或多個參照網址網站。您可以使用萬用字元來命名類似網站,舉例來說,*.google.com 接受網址以 google.com 結尾的所有網站 (例如 https://developers.google.com)。

    IP 位址

    接受由您提供的網路伺服器 IP 位址清單中所列的要求。

    在類型下方指定一個 IPv4 或 IPv6 位址,或是採用 CIDR 標記法的子網路 (例如 192.168.0.0/22)。如果您還需要輸入其他項目,系統會在您新增上述項目後顯示新的對話方塊。

    Android 應用程式

    新增套件名稱和 SHA-1 簽署憑證指紋,限制金鑰僅供您的 Android 應用程式存取。

    將您 AndroidManifest.xml 檔案中的 SHA-1 簽署憑證指紋和 Android 套件名稱,加到類型下方。

    iOS 應用程式

    iOS 應用程式軟體包 ID 必須與您提供的 ID 吻合,才接受該應用程式送出的要求。

    從類型下方的清單中選取正確的 iOS 軟體包 ID。

  4. 按一下 [儲存]
    這個步驟完成後,設定的限制就會成為 API 金鑰定義的一部分。但如果您未提供正確的詳細資訊,或是未點選 [儲存],API 金鑰就不會受到限制。如要進一步瞭解詳情,請到「取得 API 金鑰」指南中查看特定 API 或 SDK 的相關說明。

為 API 金鑰設定 API 限制

  1. 前往憑證面板
  2. 選取要設定限制的 API 金鑰。
    畫面會隨即顯示「限制並重新命名 API 金鑰」頁面。
  3. 在「API 限制」下方:
    • 按一下 [限制金鑰]
    • 按一下 [選取 API] 下拉式選單,然後選擇您要讓應用程式利用 API 金鑰存取的 API 或 SDK。如果選單未列出您需要的 API 或 SDK,則您必須啟用該 API 或 SDK。
  4. 按一下 [儲存]
    這個步驟完成後,設定的限制就會成為 API 金鑰定義的一部分。但如果您未提供正確的詳細資訊,或是未點選 [儲存],API 金鑰就不會受到限制。如要進一步瞭解詳情,請到「取得 API 金鑰」指南中查看特定 API 或 SDK 的相關說明。

API 金鑰限制和最佳做法

以下表格列出了各個 Google 地圖平台 API、SDK 或服務適用的 API 金鑰限制和最佳做法,希望對您有幫助。

使用 Maps JavaScript API、Maps Embed API 或 Maps Static API 的網站

API/SDK/服務 應用程式限制(1) API 限制(1) 最佳做法
Maps JavaScript API(2) HTTP 參照網址限制 Maps JavaScript API
Directions Service、Maps JavaScript API HTTP 參照網址限制 Directions API、Maps JavaScript API
Distance Matrix Service、Maps JavaScript API HTTP 參照網址限制 Distance Matrix API、Maps JavaScript API
Elevation Service、Maps JavaScript API HTTP 參照網址限制 Elevation API、Maps JavaScript API
Geocoding Service、Maps JavaScript API HTTP 參照網址限制 Geocoding API、Maps JavaScript API
地點資料庫、Maps JavaScript API HTTP 參照網址限制 Places API、Maps JavaScript API
Maps Embed API HTTP 參照網址限制 Maps Embed API
Maps Static API HTTP 參照網址限制 Maps Static API
Street View Static API HTTP 參照網址限制 Street View Static API

使用網路服務的應用程式和伺服器

API/SDK/服務 應用程式限制(1) API 限制(1) 最佳做法
Directions API IP 位址限制(4) Directions API
Distance Matrix API IP 位址限制(4) Distance Matrix API
Elevation API IP 位址限制(4) Elevation API
Geocoding API IP 位址限制(4) Geocoding API
Geolocation API IP 位址限制(4) Geolocation API
Places API(5) IP 位址限制(4) Places API
Roads API IP 位址限制(4) Roads API
Time Zone API IP 位址限制(4) Time Zone API

Android 應用程式

API/SDK/服務 應用程式限制(1) API 限制(1) 最佳做法
Maps SDK for Android Android 限制 Maps SDK for Android
Places SDK for Android Android 限制 Places API

iOS 應用程式

API/SDK/服務 應用程式限制(1) API 限制(1) 最佳做法
Maps SDK for iOS iOS 限制 Maps SDK for iOS
Places SDK for iOS iOS 限制 Places API

1 您可以將未受限制的 API 金鑰用於任何 Google 地圖平台 API 或 SDK,不過我們強烈建議您限制 API 金鑰,尤其是在下列情況下:

  • 測試環境將設為或已設為開放給所有人檢視。
  • 採用 API 金鑰的應用程式可用於實際執行環境中。

2 考慮為行動應用程式採用原生的 Maps SDK for AndroidMaps SDK for iOS

3 針對 Maps Static API 和 Street View Static API,除了 API 金鑰之外,您還需要提供數位簽章,每日地圖載入量才能超過 25,000 次。

注意事項:用於簽署的共用密鑰安全性層級,至少要與 Maps Web Service API 搭配使用的 API 金鑰同等級。

如果您需要動態簽署圖片要求,請從伺服器端進行。如果應用程式依賴用戶端輸入內容來產生靜態圖片,請採用下列一或多項技術來保護這些內容:

如果簽署要求,請一併查看您每天願意允許的未簽署要求數量,然後據此調整未簽署要求的配額。

4 有時候設定 IP 限制的做法可能並不實際,例如對行動應用程式和仰賴動態 IP 位址的雲端環境來說,就可能不太適用。在這類情境中使用 Maps Web Service API 時,請採用下列一或多項技術來保護應用程式:

5 針對行動應用程式,我們建議使用原生的 Places SDK for AndroidPlaces SDK for iOS