取得 API 金鑰

事前準備

開始使用 Maps SDK for Android 之前,您必須擁有具備帳單帳戶的專案,並啟用 Maps SDK for Android。詳情請參閱開始使用 Google 地圖平台

建立 API 金鑰

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

建立 API 金鑰的方法如下:

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

    前往專案選取器頁面

  2. 前往「API 和服務」>「憑證」頁面。

    前往憑證頁面

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

在應用程式中加入 API 金鑰

建議您將金鑰儲存至位於專案根目錄的 local.properties 檔案中,而不要在版本管控系統中登錄 API 金鑰。如要進一步瞭解 local.properties 檔案,請參閱 Gradle 屬性檔案一文。下列 Gradle 技巧說明如何將 API 金鑰儲存至 local.properties 檔案中,以供應用程式安全地參照。

新增 API 金鑰的方法如下:

  1. 開啟位於專案層級目錄的 local.properties,然後將下列程式碼加入檔案。將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY
      
  2. 將下列程式碼加入應用程式層級 build.gradle 檔案的 defaultConfig 元素中。這樣一來,Android Studio 就能在建構期間從 local.properties 檔案讀取 Maps API 金鑰,然後將 mapsApiKey 建構變數插入您的 Android 資訊清單。
    android {
        defaultConfig {
            // ...
            // Set the properties within `local.properties` into a `Properties` class so that values
            // within `local.properties` (e.g. Maps API key) are accessible in this file.
            Properties properties = new Properties()
            if (rootProject.file("local.properties").exists()) {
                properties.load(rootProject.file("local.properties").newDataInputStream())
            }
    
            // Inject the Maps API key into the manifest
            manifestPlaceholders = [ mapsApiKey : properties.getProperty("MAPS_API_KEY", "") ]
        }
    }
      
  3. AndroidManifest.xml 檔案中,將下列程式碼新增為 application 元素的子項。
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${mapsApiKey}" />
        
  4. 儲存檔案,並使用 Gradle 同步處理專案。

注意事項:如上所示,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 金鑰的方法如下:

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

    前往專案選取器頁面

  2. 前往「API 和服務」>「憑證」頁面。

    前往憑證頁面

  3. 選取您要設定限制的 API 金鑰。畫面隨即會顯示 API 金鑰屬性頁面。
  4. 在「金鑰限制」下方,設定下列限制:
    • 應用程式限制:
      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
        (詳情請參閱「從哪裡取得應用程式 SHA-1 指紋」一節。)
    • API 限制:
      1. 按一下 [限制金鑰]
      2. 從「選取 API」下拉式選單中選取 [Maps SDK for Android]
        (假如選單未列出 Maps SDK for Android,代表您必須先加以啟用。)
  5. 如要完成變更,請按一下 [儲存]

從哪裡取得應用程式 SHA-1 指紋

Android API 金鑰限制是以應用程式數位憑證的簡短形式為根據,這種形式稱為 SHA-1 指紋

從 Android Studio 取得憑證資訊

如果您按照 Maps SDK for Android 的入門指南操作,則 Android Studio 會使用您應用程式的憑證建立便利的 google_maps_api.xml 檔案。

請選用下列其中一種方式,從 Android Studio 取得 API 金鑰:

  • 快速簡便的方法:使用 Android Studio 為您建立的 google_maps_api.xml 檔案中提供的連結:
    1. 複製 google_maps_api.xml 檔案中提供的連結,然後貼到瀏覽器中。這個連結會將您導向 Google Cloud Console,並透過網址參數將必要資訊提供給 Cloud Console,因此可為您減少一些手動輸入工作。
    2. 按照操作說明在 Cloud Console 建立新專案,或選取現有的專案。
    3. 為您的專案建立 Android 限制的 API 金鑰。
    4. 複製產生的 API 金鑰,返回 Android Studio,然後將 API 金鑰貼到 google_maps_api.xml 檔案的 <string> 元素中。
  • 稍微慢一點的做法:使用 Android Studio 為您建立的 google_maps_api.xml 檔案中提供的憑證:
    1. 複製 google_maps_api.xml 檔案中提供的憑證。
    2. 前往 Google Cloud Platform Console
    3. 使用複製的憑證將應用程式新增至現有的 API 金鑰,或建立新的 API 金鑰。

自行取得憑證資訊

如果您在建立應用程式時並未按照入門指南操作,就必須自行取得憑證的 SHA-1 指紋。請先確認您使用的是正確的憑證。您可能會有以下兩種憑證:

  • 偵錯憑證:執行偵錯版本時,Android SDK 工具會自動產生這個憑證。請僅將這個憑證用於您正在測試的應用程式。 請勿嘗試發布以偵錯憑證簽署的應用程式。 如要進一步瞭解偵錯憑證,請參閱 Android 開發人員說明文件的登入偵錯模式
  • 發布憑證:Android SDK 工具會在您執行發布子版本時產生這個憑證。您也可以使用 keytool 程式產生這個憑證。當您準備好要將應用程式發布上架時,請使用這個憑證。

請按照下列步驟,使用 keytool 程式搭配 -v 參數,即可顯示憑證的 SHA-1 指紋。如要進一步瞭解 Keytool,請參閱 Oracle 說明文件

偵錯憑證

顯示偵錯憑證指紋

  1. 找出您的偵錯 KeyStore 檔案。檔案名稱為 debug.keystore,這是您第一次建立專案時建立的檔案。根據預設,檔案會儲存在與您的 Android 虛擬裝置 (AVD) 檔案相同的目錄中:

    • macOS 和 Linux~/.android/
    • Windows Vista 和 Windows 7C:\Users\your_user_name\.android\
  2. 列出 SHA-1 指紋:

    • 如果是 Linux 或 macOS,請開啟終端機視窗並輸入以下指令:

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • 如果是 Windows Vista 或 Windows 7,請執行:

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

您應該會看到如下的結果:

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
發布憑證

顯示發布憑證指紋

  1. 找出您的發布憑證 KeyStore 檔案。發布 KeyStore 檔案並沒有預設名稱或位置。如果您在建構要發布的應用程式時未加以指定,版本會將您的 .apk 保持為未簽署狀態,而您必須先簽署才能發布應用程式。如使用發布憑證,您還需要別名和密碼,才能使用 KeyStore 和憑證。在 KeyStore 中輸入以下內容,即可列出所有金鑰的別名:

    keytool -list -keystore your_keystore_name

    以完整的 KeyStore 路徑和名稱 (包括 .keystore 副檔名) 取代 your_keystore_name。系統會提示您輸入 KeyStore 密碼,然後 keytool 就會顯示 KeyStore 中的所有別名。

  2. 輸入以下終端機或命令提示字元:

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    以完整的 KeyStore 路徑和名稱 (包括 .keystore 副檔名) 取代 your_keystore_name。以 your_alias_name 取代您在建立憑證時為其指定的別名。

您應該會看到如下的結果:

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

開頭為 SHA1 的行包含憑證的 SHA-1 指紋。指紋為一系列 20 個雙位十六進位制數碼,以冒號分隔。

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