使用 API 金鑰

本主題將說明如何為 Maps SDK for Android 建立 API 金鑰、怎麼將金鑰加進應用程式,以及限制金鑰來保護應用程式安全的做法。您必須在採用該 SDK 的所有應用程式中加進 API 金鑰。

事前準備

您的專案必須連結了帳單帳戶並啟用 Maps SDK for Android,才能開始使用 Maps SDK for Android。請參閱這篇文章,進一步瞭解如何在 Cloud Console 中進行設定。

建立 API 金鑰

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

建立 API 金鑰的方法如下:

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

    前往「憑證」頁面

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

在應用程式中加入 API 金鑰

本節將說明如何儲存 API 金鑰,讓應用程式以更安全的方式參照金鑰。金鑰不應該登錄在版本管控系統中,因此我們建議您將 API 金鑰儲存在位於專案根目錄的 local.properties 檔案內。如要進一步瞭解 local.properties 檔案,請參閱「Gradle 屬性檔案」一文。

您可以使用 Secrets Gradle Plugin Android 版來簡化這項工作。

安裝外掛程式並儲存 API 金鑰的操作步驟如下:

  1. 在 Android Studio 中開啟根層級的 build.gradle 檔案,然後將下列程式碼加進 buildscript 下方的 dependencies 元素。
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:1.3.0"
        }
    }
        
  2. 接著,開啟應用程式層級的 build.gradle 檔案,然後將下列程式碼加進 plugins 元素。
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 儲存檔案,然後使用 Gradle 同步處理專案
  4. 在專案層級目錄中開啟 local.properties 並新增下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 儲存檔案,並使用 Gradle 同步處理專案。
  6. 在您的 AndroidManifest.xml 檔案中,前往 com.google.android.geo.API_KEY 並按照以下方式更新 android:value attribute
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

注意事項:如上所示,API 金鑰的建議中繼資料名稱為 com.google.android.geo.API_KEY。具備這個名稱的金鑰可用來驗證 Android 平台上的多個 Google 地圖相關 API,包括 Maps SDK for Android。為了兼顧回溯相容性,API 也支援 com.google.android.maps.v2.API_KEY 這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個;如果同時指定兩者,API 就會擲回例外狀況。

限制 API 金鑰

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

當您限制 API 金鑰時,必須提供用於簽署應用程式的簽署金鑰 SHA-1 憑證指紋。憑證類型分為兩種:

  • 偵錯憑證:請僅將這個憑證類型用於您要測試的應用程式和其他非實際執行的程式碼。請勿嘗試發布以偵錯憑證簽署的應用程式。執行偵錯版本時,Android SDK 工具會自動產生這個憑證。
  • 發布憑證:準備將應用程式發布到應用程式商店時,請使用這個憑證。執行發布子版本時,Android SDK 工具會產生這個憑證。

如想進一步瞭解數位憑證,請參閱簽署應用程式指南。

限制 API 金鑰的方法如下:

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

    前往「憑證」頁面

  2. 選取您要設定限制的 API 金鑰。畫面隨即顯示 API 金鑰屬性頁面。
  3. 在「金鑰限制」下方,設定下列限制:
    • 應用程式限制:
      1. 選取 [Android 應用程式]
      2. 按一下 [+ 新增套件名稱和指紋]
      3. 輸入您的套件名稱和 SHA-1 憑證指紋,例如:
        com.example.android.mapexample
        BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
        如要瞭解如何取得憑證指紋,請參閱驗證用戶端。 如果您改為使用 Play 應用程式簽署功能,則必須前往 Play 管理中心的應用程式簽署頁面取得憑證指紋。
    • API 限制:
      1. 按一下 [限制金鑰]
      2. 從「選取 API」下拉式選單中點選 [Maps SDK for Android]。如果畫面上未列出 Maps SDK for Android,表示您需要啟用該 SDK。
  4. 如要完成變更,請按一下 [儲存]