凡是使用 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 金鑰的做法如下:
- 前往憑證面板。
- 選取要刪除的 API 金鑰。
- 按一下靠近頁面頂端的 [刪除] 按鈕。
- 畫面出現「刪除憑證」彈出式視窗時,按一下 [刪除]。
-
重新產生 API 金鑰時請特別謹慎:如果將應用程式從舊 API 金鑰遷移至重新產生的 API 金鑰,需要超過 24 小時的時間,則未更新的執行個體會繼續參照舊金鑰 (其將在重新產生 API 金鑰 24 小時後刪除),因而無法運作。
重新產生 API 金鑰時,預計會有以下情況:
- 重新產生金鑰。
- 新金鑰會沿用舊金鑰的所有限制。
- 系統開始倒數 24 小時,並在時間到後刪除舊金鑰。
-
密切觀察 API 使用情況是否有任何異常:若發現未經授權的使用情況,請輪替金鑰並通知 Google。
在輪替之前,先在檔案中建立副本,以便留存與金鑰相關聯的限制。
-
在使用 Maps Web Service API 或 Static Web API 的應用程式中,請採用下列方法來保護應用程式和 API 金鑰:
- 不要直接在程式碼中嵌入 API 金鑰或簽署密鑰:請勿直接在應用程式的程式碼中嵌入 API 金鑰或任何其他私密資訊,建議做法是將這類資訊放在環境變數中,或放在包含檔案內並與大量程式碼分開儲存 (應儲存於應用程式原始檔存放區之外)。這樣當您要共用程式碼,共用檔案內就不會含有 API 金鑰或簽署密鑰。
- 不要將 API 金鑰或簽署密鑰儲存在應用程式原始碼樹狀結構中的檔案內:如果您將 API 金鑰或任何其他私密資訊儲存在檔案中,請將這類檔案存放在應用程式原始碼樹狀結構之外的位置,以免金鑰或其他私密資訊出現在原始碼控管系統中。假如您使用的是公開原始碼管理系統 (例如 GitHub),特別需要注意這點。
- 公開發布前應先檢查程式碼:在公開發布程式碼之前,請確保程式碼內沒有 API 金鑰、簽署密鑰或任何其他私密資訊。
-
在使用 Web Service API 或 Static Web API 的行動應用程式中,考慮採用下列一或多項技術來進一步保護 API 金鑰或簽署密鑰:
-
使用 Proxy 伺服器:Proxy 伺服器提供可靠來源,讓應用程式與適當的 Google 地圖平台 API 互動。想進一步瞭解如何使用 Proxy 伺服器,請參閱「Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries」(善用代理伺服器:搭配 Google Data API 用戶端程式庫使用 Proxy 伺服器) 一文。
- 將 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 金鑰設定應用程式限制
- 前往憑證面板。
- 選取要設定限制的 API 金鑰,畫面隨即顯示 API 金鑰屬性頁面。
- 在「金鑰限制」下方,選取 [應用程式限制]。
請選取其中一個限制類型,然後按照限制清單中的說明提供必要資訊。限制類型 說明 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。
- 按一下 [儲存]。
這個步驟完成後,設定的限制就會成為 API 金鑰定義的一部分。但如果您未提供正確的詳細資訊,或是未點選 [儲存],API 金鑰就不會受到限制。如要進一步瞭解詳情,請到「取得 API 金鑰」指南中查看特定 API 或 SDK 的相關說明。
為 API 金鑰設定 API 限制
- 前往憑證面板。
- 選取要設定限制的 API 金鑰。
畫面會隨即顯示「限制並重新命名 API 金鑰」頁面。 - 在「API 限制」下方:
- 按一下 [限制金鑰]。
- 按一下 [選取 API] 下拉式選單,然後選擇您要讓應用程式利用 API 金鑰存取的 API 或 SDK。如果選單未列出您需要的 API 或 SDK,則您必須啟用該 API 或 SDK。
- 按一下 [儲存]。
這個步驟完成後,設定的限制就會成為 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 Android 和 Maps 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 Android 和 Places SDK for iOS。