Google 地圖平台安全指南

使用 Google 地圖平台 API 和 SDK 的應用程式和專案「必須」使用 API 金鑰或 OAuth 2.0 (如支援) 來驗證自身。

這些最佳做法說明如何保護 Maps Platform 存取權。

如果您想使用 OAuth 2.0 授權伺服器對伺服器流量，請在 API 說明文件中查找 OAuth 主題。詳情請參閱「為伺服器端應用程式使用 OAuth」。

除了套用應用程式和 API 金鑰限制，也請務必遵守 Google 地圖平台產品適用的安全性做法，舉例來說，您可以參閱下文「建議的應用程式和 API 限制」一節中的 Maps JavaScript API 相關內容。

如果目前已有使用中的 API 金鑰，請參閱下方「限制目前使用中的 API 金鑰」一節的建議。

如要進一步瞭解 Maps Static API 和 Street View Static API 支援的數位簽章，請參閱「數位簽章指南」。

建議最佳做法

為提升安全性，並避免未經授權的使用行為產生相關費用，請遵循下方所有 Google 地圖平台 API、SDK 或服務適用的 API 安全性最佳做法：

限制 API 金鑰

針對各個應用程式使用不同的 API 金鑰

刪除未使用的 API 金鑰

查看 API 金鑰使用情形

輪替 API 金鑰時請務必謹慎

將用戶端和伺服器端用量拆分為不同的專案

停用未使用的服務

用戶端應用程式的其他建議

使用用戶端 SDK

安全的用戶端網路服務呼叫

使用 Static Web API 的網站或用戶端應用程式 - 其他建議

保護 Static Web API 用量

使用網路服務的伺服器端應用程式 - 其他建議

保護網路服務 API 金鑰

為伺服器端應用程式使用 OAuth

限制或輪替目前使用中的 API 金鑰

  • 變更 API 金鑰前，請先查看 API 金鑰使用情形。如果您要為已在正式版應用程式中使用的金鑰新增限制，這個步驟就格外重要。

  • 變更金鑰後，請視需要更新所有應用程式的 API 金鑰。

  • 如果您的 API 金鑰並未遭駭，且目前沒有濫用情形，您可以依自己的步調，將應用程式改為採用多個新的 API 金鑰。原本的 API 金鑰可維持不變，直到只剩一種流量類型時，再為該類型的 API 金鑰套用應用程式限制，且不會造成服務中斷。

    詳情請參閱「改用多個 API 金鑰」一節。

    您可以持續監控使用情形，等到確認特定的 API、平台類型和網域已不再使用舊的 API 金鑰時，再選擇限制或刪除舊金鑰。詳情請參閱「報表與監控」和「指標」

  • 如果您的 API 金鑰遭駭，最好趕緊採取行動確保金鑰安全，並阻止濫用行為。以 Android 和 iOS 應用程式來說，要等到客戶更新應用程式，才能更換金鑰。在網頁或伺服器端應用程式中更新或替換金鑰則簡單許多，但這項操作可能還是需要審慎規劃及快速執行。

    詳情請參閱「處理未經授權使用 API 金鑰的問題」一節。

更多資訊

建議的應用程式和 API 限制

限制 API 金鑰

建議您一律為 API 金鑰設定一種應用程式限制和一或多項 API 限制。如要依照 API、SDK 或 JavaScript 服務查看相關建議限制，請參閱下方「建議的應用程式和 API 限制」一節。

  • 應用程式限制：您可以將 API 金鑰的使用範圍限制在下列其中一個特定平台：Android 或 iOS 應用程式、特定網站 (用戶端應用程式)，或是特定 IP 位址或 CIDR 子網路 (發出網路服務 REST API 呼叫的伺服器端應用程式)。

    限制金鑰時，您可以按照想要授權的類型，新增一或多項應用程式限制。一旦套用限制，就只有這些來源可提出要求。

  • API 限制：您可以限制 API 金鑰只能用於哪些 Google 地圖平台 API、SDK 或服務。設定 API 限制後，就只能對您指定的 API 和 SDK 送出要求。您可以視需要對任一 API 金鑰指定多項 API 限制。可用 API 清單會列出專案中已啟用的所有 API。

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

  1. 開啟 Google Cloud 控制台的 Google 地圖平台憑證 頁面。

  2. 選取要設定限制的 API 金鑰。

  3. 在「編輯 API 金鑰」頁面的「金鑰限制」下方，選取「設定應用程式限制」。

    「編輯 API 金鑰」頁面

  4. 請選取其中一個限制類型，然後按照限制清單中的說明提供必要資訊。

    限制類型 說明
    網站 指定一或多個參照網址網站。
    • https 和 http 是業界普遍支援的參照網址 URI 配置。其他配置方案無法保證正常運作，因為現代網頁瀏覽器會基於隱私權考量，不會在傳出要求中傳送「Referer」標頭。
    • 請一律提供完整的參照網址字串，包括通訊協定配置、主機名稱及選用的連接埠 (例如 https://r7ovno6fgj.proxynodejs.usequeue.com/)。
    • 您可以使用萬用字元授權所有子網域。舉例來說，https://*.google.com 接受結尾為 .google.com 的所有網站。
    • 授權完整路徑的參照網址 (例如 https://r7ovno6fgj.proxynodejs.usequeue.com//some/path) 時，請務必特別留意，因為大多數的網路瀏覽器會基於隱私權考量，從跨來源要求中去除路徑。
    IP 位址 您可以指定一或多個 IPv4 或 IPv6 位址，或是採 CIDR 標記法的子網路。IP 位址必須與 Google 地圖平台伺服器監控的來源位址相符。如果您使用網路位址轉譯 (NAT)，這個位址通常會對應到電腦的「公開」IP 位址。
    Android 應用程式 對於要授權的 Android 應用程式，請加入其 Android 套件名稱 (取自 AndroidManifest.xml 檔案) 和 SHA-1 簽署憑證指紋。如果您使用 Play 應用程式簽署功能擷取簽署憑證指紋，請參閱「與 API 供應商合作」一文。如果您管理自己的簽署金鑰，請參閱「自行簽署應用程式」一文，或是參考您建構環境適用的操作說明。
    iOS 應用程式 對於要授權的 iOS 應用程式，請加入其軟體包 ID。

    如需應用程式限制的相關建議，請參閱「建議的應用程式限制」一節。

  5. 選取「儲存」。

設定 API 金鑰的 API 限制

  1. 開啟 Google Cloud 控制台的 Google 地圖平台憑證 頁面。

  2. 選取要設定限制的 API 金鑰。

  3. 在「編輯 API 金鑰」頁面的「API 限制」下方：

    • 選取「限制金鑰」。

    • 開啟「選取 API」，然後選取您要讓應用程式利用 API 金鑰存取的 API 或 SDK。

    如果選單內沒有您要的 API 或 SDK，則需自行啟用。詳情請參閱「啟用一或多個 API 或 SDK」。

    在「編輯 API 金鑰」頁面限制 API

  4. 選取「儲存」。

    這個步驟完成後，設定的限制就會成為 API 金鑰定義的一部分。請確認提供的詳細資料正確無誤，並選取「Save」(儲存) 來儲存 API 金鑰限制。如需進一步說明，請根據您想要瞭解的 API 或 SDK，參閱對應說明文件中的「取得 API 金鑰」指南。

如要查看建議的 API 限制，請參閱「建議的 API 限制」一節。

查看 API 金鑰使用情形

如要對已建立的 API 金鑰套用限制，或是想查看金鑰目前採用何種 API，以便加上限制，不妨查看 API 金鑰使用情形。您可以按照下列步驟操作，瞭解 API 金鑰目前用於哪些服務和 API 方法。如果您發現金鑰不只用於 Google 地圖平台服務，請進行調查並判斷是否需要加入更多限制，避免不必要的使用行為。您可以運用 Google 地圖平台 Cloud 控制台的 Metrics Explorer，判斷要對 API 金鑰套用哪些 API 和應用程式限制：

找出目前使用 API 金鑰的 API

以下指標報表有助您找出目前已採用 API 金鑰的 API。使用這類報表可以：

  • 瞭解 API 金鑰的使用情形
  • 找出非預期的使用情形
  • 確認是否可以放心刪除未使用的金鑰。如需刪除 API 金鑰的相關說明，請參閱「刪除未使用的 API 金鑰」一節。

套用 API 限制時，可根據這些報表建立清單 (列出要授權的 API)，或是驗證系統自動產生的 API 金鑰限制建議。如要進一步瞭解建議的限制，請參閱「套用建議的限制」一節。如要進一步瞭解如何使用 Metrics Explorer，請參閱「使用 Metrics Explorer 建立圖表」一文。

  1. 前往 Google Cloud 控制台的 Metrics Explorer

  2. 登入並選取您要查看哪個專案的 API 金鑰。

  3. 前往「Metrics Explorer」頁面找出您的 API 類型：

    • 如果 API 金鑰使用的「不是」Maps Embed API：請前往 Metrics Explorer 頁面。

    • 如果 API 金鑰使用的是 Maps Embed API：請前往 Metrics Explorer。

  4. 檢查每個 API 金鑰：

    1. 選取「ADD FILTER」(新增篩選器)。

    2. 選取標籤 credential_id。

    3. 選取您要檢查哪個值的金鑰。

    4. 查看這個 API 金鑰目前用於哪些 API，並檢查使用情形是否正常。

    5. 完成後，請在使用中的篩選器該行結尾處，選取「移除篩選器」，刪除額外的篩選器。

  5. 對於其餘金鑰，請重複執行以上操作。

  6. 限制 API 金鑰只能用於目前使用的 API。

  7. 如果發現未經授權的使用行為，請參閱「處理未經授權使用 API 金鑰的問題」一節。

使用 Metrics Explorer 選擇適當類型的應用程式限制

完成驗證並採取所有必要行動，確保 API 金鑰僅用於目前使用的 Google 地圖平台服務後，請一併確認 API 金鑰已套用正確的應用程式限制。

如有建議的 API 金鑰限制，請加以套用。詳情請參閱「套用建議的 API 金鑰限制」一節。

如果沒有建議的 API 金鑰限制，請使用 Metrics Explorer，根據回報的 platform_type 決定要套用的應用程式限制類型：

  1. 前往 Google Cloud 控制台的 Metrics Explorer

  2. 登入並選取您要查看哪個專案的 API。

  3. 前往以下 Metrics Explorer 頁面：Metrics Explorer。

  4. 檢查每個 API 金鑰：

    1. 選取「ADD FILTER」(新增篩選器)。

    2. 選取標籤 credential_id。

    3. 選取您要檢查哪個值的金鑰。

    4. 完成後，請在使用中的篩選器該行結尾處，選取「移除篩選器」，刪除額外的篩選器。

  5. 對於其餘金鑰，請重複執行以上操作。

  6. 找到 API 金鑰適用的平台類型後，請對該 platform_type 套用應用程式限制：

    PLATFORM_TYPE_JS：對金鑰套用網站限制。

    PLATFORM_TYPE_ANDROID：對金鑰套用 Android 應用程式限制。

    PLATFORM_TYPE_IOS：對金鑰套用 iOS 應用程式限制。

    PLATFORM_TYPE_WEBSERVICE：您可能需要對金鑰套用 IP 位址限制，才能正確限制金鑰。

    如需 Maps Static API 和 Street View Static API 的建議，請參閱「保護 Static Web API 用量」。

    如需 Maps Embed API 最佳化建議，請參閱「使用 Maps Embed API 的網站」一節。

    我的 API 金鑰使用多種平台類型：只使用一個 API 金鑰，不足以妥善保護流量，請務必改用多個 API 金鑰。詳情請參閱「改用多個 API 金鑰」一節。

針對各個應用程式使用不同的 API 金鑰

這個做法可限制每個金鑰的範圍，要是其中一個 API 金鑰遭駭，您可以直接刪除或輪替受影響的金鑰，無須更新其他 API 金鑰。每個專案最多可建立 300 個 API 金鑰。詳情請參閱「API 金鑰限制」。

雖然基於安全起見，一個應用程式使用一個 API 金鑰是理想的做法，但也可以讓多個應用程式共用受限金鑰，前提是這些金鑰使用同一種應用程式限制類型。

套用建議的 API 金鑰限制

對於部分專案擁有者、編輯者和 API 金鑰管理員，Google Cloud 控制台會根據未受限 API 金鑰在 Google 地圖平台上的使用情形和活動，建議對這些 API 金鑰施加特定的 API 金鑰限制。

如果有可用的建議，Google 地圖平台的「憑證」頁面會預先填入這些選項。

自動化推薦功能支援的 Google 地圖平台 API 和 SDK

  • Maps JavaScript API，包括 Directions Service (舊版)、Distance Matrix Service (舊版)、Elevation Service、Geocoding Service、Place 類別、Place Autocomplete Widget (新版)、Place Autocomplete Data API、Places Library、Places Service 和 Place Autocomplete Widget

  • Maps Static API 和 Street View Static API

  • Maps Embed API

  • Maps SDK for Android、Places SDK for Android 和 Navigation SDK for Android

  • Maps SDK for iOS、Places SDK for iOS、Places Swift SDK for iOS 和 Navigation SDK for iOS

看不到建議或建議不完整的可能原因

看不到建議的原因

  • 您同時將 API 金鑰用於 Google 地圖平台以外的服務，或是尚未支援自動建議的 Google 地圖平台服務。

    如果您發現其他服務使用 API 金鑰的情況，請務必先完成下列操作，再套用建議：

    1. 確認 Google Cloud 控制台 Metrics Explorer 中顯示的 API 用量是否合理。

    2. 在待授權 API 的清單中，手動加入缺少的服務。

    3. 為已加進 API 清單的服務，手動加入所有缺少的應用程式限制。如果另外加入的服務需要其他類型的應用程式限制，請參閱「改用多個 API 金鑰」一節。

  • 您的 API 金鑰未用於用戶端 SDK 或 API。

  • 您將 API 金鑰用於最近 60 天內沒有人使用的低流量應用程式或網站。

  • 您是不久之前才建立新金鑰，或是不久之前才在新的應用程式中部署現有金鑰。如果是這樣，請再多等幾天，讓系統更新建議。

  • 您將 API 金鑰用於應用程式限制類型會相互衝突的多個應用程式，或是將同一個 API 金鑰用於太多不同的應用程式或網站。不論是哪一種情況，我們都建議您改用多個金鑰。詳情請參閱「改用多個 API 金鑰」一節。

看到不完整建議的原因

  • 您將 API 金鑰用於最近 60 天內沒有人使用的低流量應用程式或網站。

  • 您最近才開始在新的 API 或服務上使用現有金鑰，而自動 API 金鑰限制建議管道尚未處理更新的使用量指標。使用量指標的傳播作業可能需要幾天時間。

    如果您發現其他服務使用 API 金鑰的情況，請務必先完成下列操作，再套用建議：

    1. 確認 Google Cloud 控制台 Metrics Explorer 中顯示的 API 用量是否合理。

    2. 在待授權 API 的清單中，手動加入缺少的服務。

    3. 為已加進 API 清單的服務，手動加入所有缺少的應用程式限制。如果另外加入的服務需要其他類型的應用程式限制，請參閱「改用多個 API 金鑰」一節。

    4. 除非您急需限制金鑰 (例如因未經授權的使用行為)，否則可能需要等待一兩天，才能取得建議。

看到的建議未顯示於圖表中的可能原因

  • 您的應用程式或網站只傳送極短時間內遽增的流量。在這種情況下，請將「圖表」檢視切換為「資料表」或「兩者」，因為圖例中仍會顯示用量。詳情請參閱「切換圖表的完整圖例」。

  • 您的流量來自 Maps Embed API。如需相關操作說明，請參閱「判斷哪些 API 正在使用 API 金鑰」一節。

  • 應用程式或網站帶來的流量，超出 Google Cloud 控制台 Metrics Explorer 所提供的日期範圍。

  1. 開啟 Google Cloud 控制台的 Google 地圖平台憑證 頁面。

  2. 如果可以，請選取「套用建議的限制」。

    套用建議的限制

  3. 選取「查看 API 用量」，確認哪些服務正在使用 API 金鑰。如果看到 Google 地圖平台以外的服務，請先暫停操作，然後根據上述建議步驟進行手動檢查。請查看「套用建議的 API 金鑰限制」一節開頭的疑難排解步驟。

  4. 請仔細確認預先填入的限制，是否與要使用 API 金鑰的網站和應用程式相符。

    最佳做法：記錄並移除與您服務無關的所有應用程式或 API 限制。如果某項功能因非預期的依附元件而無法運作，您可以加回必要的應用程式或 API。

    • 如果您發現建議明顯遺漏某個應用程式、網站或 API，請手動加入，或是等待幾天的時間讓系統更新建議。

    • 如果還需要進一步的建議相關協助，請與支援團隊聯絡。

  5. 選取「套用」。

應用程式套用建議後遭拒時的處理方式

如果您發現應用程式或網站在套用限制後遭拒，請在 API 回應錯誤訊息中找出要加入的應用程式限制。

用戶端 SDK 和 API

以瀏覽器和 WebView 為基礎的應用程式

基於隱私權考量，現代瀏覽器通常會在跨來源要求中遮蓋 Referer 標頭，通常會將其簡化為 Origin。不過，具體行為取決於代管網站所套用的 referrer-policy，也可能因使用者的瀏覽器和版本而異。

使用不透明或本機 URI 配置載入內容的網頁應用程式，通常會讓轉譯瀏覽器或 WebView 從任何傳出呼叫中完全遮蓋 Referer 標頭，這可能會導致使用含有網站限制的 API 金鑰時，要求失敗。

如需進一步指引，請參閱「在伺服器上代管瀏覽器應用程式」。

適用於瀏覽器和 WebView 應用程式的疑難排解操作說明：

  • 如要瞭解如何授權應用程式，請參閱 Maps JavaScript API 的瀏覽器偵錯控制台。

    系統僅部分支援特殊 URI 配置。如果應用程式的部分內容無法使用特殊的 URI 配置，即使授權所需的參照來源，您可能還是需要在伺服器上遠端代管應用程式，並透過 HTTPS (或 HTTP) 載入應用程式。

    如需特殊 URI 配置的協助，請與支援團隊聯絡。

  • 其他 Google 地圖平台 API 通常會在 API 錯誤回應中傳回需要授權的參照來源，前提是用戶端已透過遭拒絕的要求傳送這項資訊。

    不支援特殊 URI 配置。

Android 應用程式

使用 Android Debug Bridge (ADB) 或 Logcat

iOS 應用程式

請參閱「查看記錄訊息」

直接呼叫網路服務的應用程式

如果應用程式未使用用戶端 Google 地圖平台 SDK，直接呼叫 Google 地圖平台 HTTPS REST API 或 gRPC 端點，請參閱以下說明：

Android 和 iOS 應用程式

如果您的 Android 或 iOS 應用程式直接呼叫 Maps 平台服務，但未使用任何可用的 Google 地圖平台用戶端 SDK，請參閱「Android 應用程式」和「iOS 應用程式」進一步瞭解疑難排解訣竅，以及「安全的用戶端端網路服務呼叫」，瞭解目前行動用途的最佳安全做法。

如果應用程式記錄 Google 地圖平台 API 錯誤回應，上述用戶端 SDK 操作說明也可能有助於排解驗證問題。

伺服器端應用程式

依賴 API 金鑰的伺服器端應用程式，最好透過 IP 位址限制來確保安全。如果您已為金鑰套用 IP 位址限制，且服務記錄了 Google 地圖平台 API 錯誤回應，請查看系統記錄以取得更多資訊。錯誤回應會包含您需要授權的伺服器 IP 位址。

以瀏覽器或 WebView 為基礎的應用程式

雖然 Maps Static API、Street View Static API 和較新的 Google 地圖平台 API 也支援參照來源限制，但請注意，網頁瀏覽器或 WebView 可能會將 Referer 標頭限制為跨來源要求的 Origin，並可能會完全不傳送參照來源，例如針對在本機存取的資源，或是透過 HTTP 或 HTTPS 以外的通訊協定提供的資源。

如果無法在應用程式中使用 Maps JavaScript API，且網站限制無法運作，請參閱「安全的用戶端網路服務呼叫」，瞭解如何在瀏覽器用戶端應用程式中安全地發出 Google 地圖平台網路服務呼叫。

檢查 API 限制

如要查看必要的 API 限制，請參閱「判斷哪些 API 正在使用 API 金鑰」一節。

如果無法決定要套用的限制，您可以：

  1. 記錄目前的限制供日後參考。
  2. 在調查問題期間暫時移除這些限制。如要查看一段時間內的用量，請按照「查看 API 金鑰使用情形」一節的步驟操作。
  3. 如有需要，請與支援團隊聯絡。

刪除未使用的 API 金鑰

請先確認 API 金鑰未用於正式環境，再刪除金鑰。只要沒有任何成功流量，刪除金鑰應該就不會有什麼問題。詳情請參閱「查看 API 金鑰使用情形」一節。

刪除 API 金鑰的做法如下：

  1. 開啟 Google Cloud 控制台的 Google 地圖平台憑證 頁面。

  2. 選取要刪除的 API 金鑰。

  3. 選取靠近頁面頂端的「刪除」按鈕。

  4. 在「刪除憑證」頁面上，選取「刪除」。

    刪除 API 金鑰需要幾分鐘的時間才會生效。作業完成後，凡是使用已刪除 API 金鑰的流量都會遭拒。

輪替 API 金鑰時請務必謹慎

輪替 API 金鑰時會建立一個新金鑰，當中包含舊金鑰的所有限制。在這段期間，系統會同時接受新舊金鑰，讓您有足夠的時間將應用程式改為使用新金鑰。

輪替 API 金鑰前：

  • 請先嘗試按照「限制 API 金鑰」一節的說明限制 API 金鑰。

  • 如果因為應用程式限制類型相互衝突，而無法限制 API 金鑰，請按照「改用多個 API 金鑰」一節的說明，改用多個新的 (受限) 金鑰。這樣一來，您就能自行掌控改用並推出多個新 API 金鑰的時程。

如果前述建議不可行，而您為了防止未經授權的使用行為，必須旋轉 API 金鑰，請按照下列步驟操作：

  1. 開啟 Google Cloud 控制台的 Google 地圖平台憑證 頁面。

  2. 開啟要輪替的 API 金鑰。

  3. 選取頁面頂端的「旋轉金鑰」。

  4. 您可以選擇變更 API 金鑰名稱。

  5. 選取「建立」。

  6. 更新應用程式以使用新金鑰。

更新應用程式以使用新金鑰後，請按一下新 API 金鑰頁面「Previous Key」部分下方的「Delete the previous key」按鈕，刪除舊金鑰。

改用多個 API 金鑰

如要從多個應用程式使用一個 API 金鑰的做法，改為每個應用程式只使用一個專屬 API 金鑰，請按照下列步驟操作：

  1. 確認哪些應用程式需要新金鑰：

    • 網頁應用程式最容易更新，因為所有程式碼都是由您控制。請規劃更新所有網路應用程式的金鑰。
    • 更新行動應用程式相對困難許多，因為必須等到客戶更新應用程式後才能使用新金鑰。

  2. 建立及限制新金鑰：新增應用程式限制，以及至少一項 API 限制。詳情請參閱「建議最佳做法」。

  3. 將新金鑰加到應用程式：如果是行動應用程式，必須等到所有使用者都更新至內含新 API 金鑰的最新版應用程式，這項程序才算完成，因此可能需要花費數個月的時間。

將用戶端和伺服器端用量拆分到個別專案

如果您需要同時從伺服器端應用程式和直接從執行使用者裝置的用戶端應用程式呼叫 Google 地圖平台服務，Google 建議您將用量分開至兩個專案。

您可以在用戶端專案中，針對大多數 Google 地圖平台服務套用適當的每分鐘、每位使用者配額限制，確保所有使用者都能公平分配整體專案配額，而不會互相影響。

不過，由於每位使用者配額限制會影響用戶端和伺服器端應用程式，因此如果您也需要為伺服器端工作設定高頻寬，請為此用途設定個別專案，並設定更高的每位使用者配額限制 (或不設定)。

停用未使用的服務

請勿在專案中啟用未使用的服務，因為這類做法容易遭到濫用，尤其是如果您未限制所有公開 API 金鑰。最佳做法是，只有在應用程式需要時，才在專案中啟用服務。

為金鑰新增 API 限制，可防止金鑰在未經授權的服務上使用，但 API 限制只會套用至該特定金鑰。在專案層級停用服務，以免有人未經授權，就使用與專案連結的任何金鑰存取服務。

使用用戶端 SDK

使用提供的用戶端 Google 地圖平台 SDK 時，您隨時可以為 API 金鑰套用適當的限制，確保服務用量安全無虞。

使用用戶端 SDK 還可讓您採用更進階的安全機制，例如在支援 Firebase App Check 的 Google 地圖平台 API 途徑中使用 Firebase App Check。詳情請參閱「使用 App Check 保護 API 金鑰」一文。

如果您的平台不支援用戶端 SDK，請參閱如何保護用戶端網頁服務呼叫。

如要瞭解不同平台的用戶端 Google 地圖平台 SDK 是否可用，請參閱「建議的應用程式和 API 限制」。

保護 Static Web API 用量

Static Web API (例如 Maps Static API 和 Street View Static API) 類似於網路服務 API 呼叫。

兩者都可以使用 HTTPS REST API 呼叫，且通常是在伺服器上產生 API 要求網址。不過，Static Web API 不會傳回 JSON 回應，而是產生圖片供您嵌入已產生的 HTML 程式碼。更重要的是，呼叫 Google 地圖平台服務的通常是使用者用戶端，而非伺服器。

使用數位簽章

建議您除了 API 金鑰，也應一律使用數位簽章。此外，請一併查看每天願意允許的未簽署要求數量，然後據此調整未簽署要求的配額。

如要進一步瞭解數位簽章，請參閱「數位簽章指南」。

保護簽署密鑰

為保護 Static Web API，請勿將 API 簽署密鑰直接內嵌在程式碼或原始碼樹狀結構，或是暴露在用戶端應用程式。請遵循下列最佳做法來保護簽署密鑰：

  • 在提供網頁或回應行動應用程式要求時，在伺服器端產生已簽署的 Maps Static API 和 Street View Static API 要求網址。

    如果是靜態網路內容，則可在 Cloud 控制台的 Google 地圖平台「憑證」頁面，使用「立即簽署網址」小工具。

    如要瞭解動態網頁內容，請參閱可用的網址要求簽署程式碼範例。

  • 將簽署密鑰儲存在應用程式原始碼和原始碼樹狀結構以外的位置。如果您先將簽署密鑰或任何其他私密資訊儲存在環境變數中，或是加入單獨儲存的檔案，然後才共用程式碼，共用檔案就不會包含簽署密鑰。如果您將簽署密鑰或任何其他私密資訊儲存在檔案中，請將這類檔案存放在應用程式原始碼樹狀結構外的位置，以免簽署密鑰出現在原始碼控管系統中。使用公開原始碼管理系統 (例如 GitHub) 時，請特別留意這點。

保護網路服務 API 金鑰

如要透過用戶端應用程式安全地使用 Google 地圖平台 API 和服務，請參閱「使用用戶端 SDK」和「安全的用戶端網路服務呼叫」。

將 API 金鑰儲存在應用程式原始碼或原始碼樹狀結構以外的位置。如果您先將 API 金鑰或任何其他資訊儲存在環境變數中，或是加入單獨儲存的檔案，然後才共用程式碼，共用檔案就不會包含 API 金鑰。使用公開原始碼管理系統 (例如 GitHub) 時，請特別留意這點。

為避免 Web 服務 API 金鑰遭到誤用，Google 建議您為用於 Google 地圖平台的任何金鑰套用 API 限制。此外，您也可以為網頁服務金鑰套用 IP 位址限制，防止其他來源 IP 位址未經授權使用金鑰，即使金鑰不小心外洩也不必擔心。

為伺服器端應用程式使用 OAuth

OAuth 2.0 是開放式存取權委派標準。

雖然 OAuth 2.0 通訊協定支援的用途包括讓使用者授權應用程式代表他們存取個人資料，但 Maps Platform 搭配 OAuth 2.0 的預期用途，是讓開發人員利用臨時存取權杖，授權應用程式代表其 Google Cloud 專案的服務帳戶使用服務帳戶的權限呼叫 API。

由於服務帳戶可能擁有非常廣泛的權限，因此建議您使用 OAuth 2.0 授權開發人員信任的伺服器端應用程式與 Google 地圖平台伺服器之間的伺服器對伺服器呼叫。

如果是執行在使用者裝置上的用戶端應用程式，建議使用其他驗證方法，例如 API 金鑰。

如果您想使用 OAuth 2.0 授權伺服器對伺服器流量，請在 API 說明文件中查找 OAuth 主題。

例如 Address Validation API 的 OAuth 主題。

安全的用戶端 Web 服務呼叫

如果無法使用用戶端 SDK，請參閱下方的建議。

使用 Proxy 伺服器

使用安全的 Proxy 伺服器可提供可靠來源，讓用戶端應用程式與 Google 地圖平台網路服務端點互動，而不會將 API 金鑰、簽署密鑰或 Google Cloud 服務帳戶洩漏給未經授權的使用者。

重點：

*   Construct your Google Maps Platform requests on the proxy server.
    **Don't** allow clients to relay arbitrary API calls using the proxy.

*   Post-process the Google Maps Platform responses on your proxy server.
Filter out data that the client doesn't need.

如要進一步瞭解如何使用 Proxy 伺服器，請參閱「Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries」(善用代理伺服器：搭配 Google Data API 用戶端程式庫使用 Proxy 伺服器) 一文。

安全的直接行動網頁服務呼叫

如果您無法為用戶端應用程式設定安全 Proxy 伺服器，請按照下列步驟保護應用程式：

  1. 使用 HTTP 標頭：

    • Android：使用 X-Android-Package 和 X-Android-Cert HTTP 標頭。

    • iOS：使用 X-Ios-Bundle-Identifier HTTP 標頭。

  2. 在 Android 或 iOS 金鑰中新增對應的應用程式限制。

  3. 在考慮直接從行動應用程式向 Google 地圖平台 REST API 網路服務發出呼叫之前，請先確認系統會拒絕含有錯誤 Android 或 iOS 應用程式 ID 的要求。

    如果測試端點不支援 Android 和 iOS 應用程式限制，Google 強烈建議您在行動用戶端和 Google 地圖平台網路服務端點之間使用安全的 Proxy 伺服器。

Android 應用程式提示：

  • 在將 Android 應用程式與 Google 地圖平台服務整合前，請先確認應用程式 ID (又稱為套件名稱) 的格式正確無誤。詳情請參閱 Android 說明文件中的「設定應用程式模組」。

  • 如要直接從應用程式傳遞 X-Android-Package，請使用 Context.getPackageName() 以程式輔助方式查詢。

  • 如要直接從應用程式傳遞 X-Android-Cert，請計算應用程式簽署憑證所需的 SHA-1 指紋，可透過 PackageInfo.signingInfo 存取。

  • 如果您使用 Google Cloud 控制台授權 Android 應用程式，請注意，使用者介面會將 SHA-1 指紋視為以冒號分隔的字串，例如00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33。不過，gcloud 工具和 API 金鑰 API 預期十六進制字串「不含」分隔符。

iOS 應用程式提示：

  • 在將 iOS 應用程式與 Google 地圖平台服務整合之前，請先確認 Bundle ID 格式正確。

  • 授權 iOS 應用程式時，您通常應一律在 X-Ios-Bundle-Identifier 標頭中傳遞主軟體包的軟體包 ID。

詳情請參閱「管理 API 金鑰」和「使用 API 金鑰存取 API」一文。

在伺服器上代管瀏覽器應用程式

您可以使用 Apache Cordova 等架構，輕鬆建立在 WebView 中執行的多平台混合型應用程式。不過，除非您透過 HTTP 或 HTTPS 從自己控制且已授權的網站載入網頁應用程式，否則無法保證 API 金鑰網站限制能正常運作。

在許多情況下，如果是從混合應用程式中本機載入，或是使用本機檔案網址存取的套件資源，就會導致以參照來源為依據的授權無法運作，因為為 Webview 提供動力的瀏覽器引擎會略過傳送 Referer 標頭。為避免這種情況，請在伺服器端而非用戶端代管網站應用程式。

針對行動應用程式，建議您使用可用的原生 Google 地圖平台 Android 和 iOS SDK，而非使用網路 SDK。

使用 App Check 保護 API 金鑰

您可以使用特定的 Maps SDK 和 API 整合 Firebase App Check。App Check 會封鎖來自合法應用程式以外來源的流量，為應用程式對 Google 地圖平台的呼叫提供保護。方法是檢查認證提供者提供的符記。將應用程式與 App Check 整合，有助於防範惡意要求，避免您因未經授權的 API 呼叫而遭到收費。

App Check 整合操作說明：

處理未經授權使用 API 金鑰的問題

如果發現未經授權的 API 金鑰使用行為，請採取以下行動解決問題：

  1. 限制金鑰：如果您在多個應用程式中使用同一個金鑰，請改用多個 API 金鑰，並針對各個應用程式使用不同的 API 金鑰。詳情請參閱：

  2. 如果您使用 Places SDK 或 Maps JavaScript API，也可以使用 App Check 保護 API 金鑰。

  3. 只有在下列情況下才替換或輪替金鑰：

    • 您偵測到無法限制或已受限制的金鑰有未經授權的使用情形，因此無法使用 App Check。

    • 您最好趕緊採取行動確保 API 金鑰安全，並阻止濫用行為，即使這可能會影響應用程式中的合法流量也一樣。

    繼續操作前，請先詳閱「輪替 API 金鑰時請務必謹慎」一節。

  4. 如果您還是有問題或需要協助，請與支援團隊聯絡。

建議的應用程式和 API 限制

以下幾節將針對各個 Google 地圖平台 API、SDK 或服務，建議適合採用的應用程式和 API 限制。

建議的 API 限制

下列 API 限制指南適用於所有 Google 地圖平台服務：

  • 限制 API 金鑰僅用於預計採用該金鑰的 API，以下情況除外：

    • 如果應用程式使用 Places SDK for Android 或 Places SDK for iOS，請根據您使用的 SDK 版本授權 Places API (新版) 或 Places API。1

    • 如果應用程式使用 Maps JavaScript API，請一律授權該 API 使用金鑰。

    • 如果您也使用下列任一 Maps JavaScript API 服務，建議您一併授權下列對應的 API：

      服務 API 限制
      路線規劃服務 (舊版) Directions API (舊版)
      距離矩陣服務 (舊版) Distance Matrix API (舊版)
      海拔高度服務 Elevation API
      地理編碼服務 Geocoding API
      Place 類別、Place Autocomplete 小工具 (新版) 和 Place Autocomplete Data API Places API (新版)2
      Places Library、Places 服務和 Place Autocomplete 小工具 Places API2

1 詳情請參閱 Places SDK for Android 和 Places SDK for iOS 說明文件。

2 如果不確定是否需要授權 Places API (新版) 或 Places API，請參閱 Maps JavaScript API 說明文件。

以下提供一些例子：

  • 您目前使用 Maps SDK for Android 和 Places SDK for Android，因此加入 Maps SDK for Android 和 Places API (新版) 這兩個 API 限制。

  • 您的網站使用 Maps JavaScript API Elevation Service 和 Maps Static API，因此您加入下列所有 API 的 API 限制：

    • Maps JavaScript API
    • Elevation API
    • Maps Static API

建議的應用程式限制

網站

如果網站使用 Maps JavaScript API 服務、Maps Static API 或 Street View Static API，或是直接透過 HTTPS REST API 或 gRPC 呼叫最新的 Google 地圖平台服務，請使用「網站」應用程式限制：

1 如果是行動應用程式，建議使用原生的 Maps SDK for Android 和 Maps SDK for iOS。

2 如果是行動應用程式，建議您使用原生的 Places SDK for Android 和 Places SDK for iOS。

3 另請參閱「保護 Static Web API 用量」一節。

使用 Maps Embed API 的網站

雖然使用 Maps Embed API 無須支付費用，但建議您還是要限制目前使用的 API 金鑰，防止金鑰在其他服務中遭到濫用。

最佳做法：另外建立 Maps Embed API 專屬的 API 金鑰，並限制該金鑰只能用於 Maps Embed API。這項限制可提供充分的保護，防止金鑰在未經授權的情況下用於任何其他 Google 服務。為全面控管 Maps Embed API 金鑰的使用位置，Google 建議您一併套用「網站」應用程式限制。

如果您無法將 Maps Embed API 用途分開至專用的 API 金鑰，請使用「網站」應用程式限制保護現有金鑰。

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

如果是來自信任的企業內部網路，且使用網路服務和 API 金鑰的伺服器和用戶端應用程式，請使用 IP addresses 應用程式限制。

適用於使用下列 API 的應用程式和伺服器：

4 針對行動應用程式，建議使用 Navigation SDK。

5 為確保行動裝置安全，請使用安全 Proxy 伺服器。

6 如果是用戶端應用程式，建議您使用平台提供的原生地理位置服務，例如適用於網頁瀏覽器的 W3C Geolocation、適用於 Android 的 LocationManager 或 Fused Location Provider API，或是適用於 iOS 的 Apple Core Location 架構。

7 針對行動應用程式，建議使用原生的 Places SDK for Android 和 Places SDK for iOS。

8 如要安全地在用戶端使用，請使用安全 Proxy 伺服器。

Android 應用程式

如果是 Android 應用程式，請使用 Android apps 應用程式限制。適用於使用下列 SDK 的應用程式：

。

此外，請使用 Secrets Gradle Plugin 從本機檔案插入 Secret，而非將 Secret 儲存在 Android 資訊清單中，以免 API 金鑰誤登入版本管控系統。

iOS 應用程式

如果是 iOS 應用程式，請使用 iOS apps 應用程式限制。適用於使用下列 SDK 的應用程式和伺服器：

。

延伸閱讀