取得 API 金鑰

如要使用 Maps SDK for Android，您必須擁有 API 金鑰。API 金鑰是一組專屬 ID，用於驗證與您專案有關的使用權限及帳單處理請求。

專案設定

您必須具備設有帳單帳戶的專案並啟用： Maps SDK for Android 。 如果您尚未設定和啟用專案，請參閱開始使用 Google 地圖平台取得完整操作說明；如果您第一次使用此平台，請點選下方按鈕。

取得 API 金鑰

您的專案必須有至少一個相關聯的 API 金鑰。

取得 API 金鑰的方法如下：

  1. 造訪 Google Cloud Platform Console。
  2. 按一下專案下拉式選單，然後選取或建立您要新增 API 金鑰的專案。
  3. 按一下選單按鈕 ，然後選取 [API 和服務] > [憑證]。
  4. 在「憑證」頁面上，按一下 [建立憑證] > [API 金鑰]。
    「建立的 API 金鑰」對話方塊會顯示您新建立的 API 金鑰。
  5. 按一下 [關閉]。
    新建立的 API 金鑰便會出現在「憑證」頁面的「API 金鑰」下方。
    (在實際工作環境使用新建金鑰前，記得要先限制 API 金鑰。)

在應用程式中加入 API 金鑰

請按照下列步驟將 API 金鑰加入您的應用程式資訊清單 (包含在 AndroidManifest.xml 檔案中)。

  1. 在 AndroidManifest.xml 中，在 </application> 結尾標記之前插入下列元素，即可將其新增為 <application> 元素的子項： 
        <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="YOUR_API_KEY"/>

    在 value 屬性中，以您的 API 金鑰 (加密字串) 取代 YOUR_API_KEY。 這個元素會將金鑰 com.google.android.geo.API_KEY 設定為您 API 金鑰的值。

  2. 儲存 AndroidManifest.xml 並重新建構應用程式。

注意：如上所示，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 金鑰用於網站 (HTTP 參照網址)、網路伺服器 (IP 位址) 或行動應用程式 (Android 應用程式或 iOS 應用程式) 三者之一。視 API 或 SDK 的平台而定，您在這個類別只能選取一項限制 (請參閱按平台分類的 GMP API)。

    注意：如果您需要從同一個 (用戶端) 應用程式呼叫網路、網路服務和/或行動 API，請建立並限制多個金鑰。

  • API 限制：限制將 API 金鑰用於一或多個 API 或 SDK。 系統會處理與 API 金鑰相關聯的 API 或 SDK 要求； 未與 API 金鑰相關聯的 API 或 SDK 要求將會失敗 (API 或 SDK 必須為已啟用狀態，且必須支援應用程式限制功能)。

限制 API 金鑰的方法如下：

  1. 前往 Google Cloud Platform Console。
  2. 按一下專案下拉式選單，然後選取您要限制的 API 金鑰所屬的專案。
  3. 按一下選單按鈕 ，然後選取 [API 和服務] > [憑證]。
  4. 在「憑證」頁面上，按一下您要保護的 API 金鑰名稱。
  5. 在「限制並重新命名 API 金鑰」頁面上設定限制：
    • 應用程式限制
      • 選取 [Android 應用程式] 並按照指示操作。
      • 按一下 [+ Add package name and fingerprint]。
      • 輸入您的套件名稱和 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 限制
      • 選取 [限制金鑰]。
      • 按一下 [選取 API]，然後選取 [Maps SDK for Android]。
        (如果畫面上未列出 Maps SDK for Android，您必須先啟用該 SDK。)
    • 按一下 [儲存]。

從哪裡取得應用程式 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 Platform Console，並透過網址參數將必要資訊提供給 Google Cloud Platform Console，因此可為您減少一些手動輸入工作。
    2. 按照操作說明在 Google Cloud Platform 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 7：C:\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 簽署應用程式指南。

付費方案客戶和移轉客戶

付費方案客戶，以及從付費方案移轉至 Google 地圖平台即付即用定價模式的客戶，都可選擇使用 API 金鑰或用戶端 ID 來驗證要求。 詳情請參閱付費方案說明文件的取得 API 金鑰總覽。