使用 API 密钥

准备工作

在开始使用 Maps SDK for Android 之前,您的项目需要与结算帐号相关联,且启用了 Maps SDK for Android。有关详情,请参阅在 Cloud Console 中设置项目

创建 API 密钥

API 密钥是唯一标识符,用于对与您的项目相关联的请求进行身份验证,以便您使用相关产品和执行结算。您必须至少有一个与您的项目相关联的 API 密钥。

如需创建 API 密钥,请执行以下操作:

  1. 依次转到 API 和服务 > 凭据页面。

    转到“凭据”页面

  2. 凭据页面上,依次点击创建凭据 > API 密钥
    已创建的 API 密钥对话框会显示您新创建的 API 密钥。
  3. 点击关闭
    新的 API 密钥位于凭据页面的 API 密钥下。
    (请务必在实际使用之前限制 API 密钥。)

向您的应用添加 API 密钥

本部分介绍了如何存储 API 密钥,以便您的应用可以更加安全地引用该密钥。您不应将 API 密钥签入版本控制系统,因此我们建议将其存储在项目根目录下的 local.properties 文件中。如需详细了解 local.properties 文件,请参阅 Gradle 属性文件

为了简化此任务,您可以使用 Android 版 Secrets Gradle 插件

如需安装此插件并存储您的 API 密钥,请执行以下操作:

  1. 在 Android Studio 中,打开应用级 build.gradle 文件,并将以下代码添加到 plugins 元素中。
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. 保存文件并将项目与 Gradle 同步
  3. 在项目级目录中打开 local.properties,然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。
    MAPS_API_KEY=YOUR_API_KEY
        
  4. 保存文件并将项目与 Gradle 同步。
  5. 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}" />
        

注意:如上所示,建议使用 com.google.android.geo.API_KEY 作为 API 密钥的元数据名称。可使用具有该名称的密钥向 Android 平台上的多个基于 Google 地图的 API(包括 Maps SDK for Android)进行身份验证。为了实现向后兼容性,该 API 还支持名称 com.google.android.maps.v2.API_KEY。该旧有名称只允许向 Android Maps API v2 进行身份验证。应用只能指定其中一个 API 密钥元数据名称。如果两个都指定,API 会抛出异常。

限制 API 密钥

通过限制 API 密钥,您可以确保只能使用您的 API 密钥发出已授权的请求,从而提高应用安全性。我们强烈建议您按照相关说明为您的 API 密钥设置限制。如需了解详情,请参阅 API 密钥最佳做法

如需限制 API 密钥,请执行以下操作:

  1. 依次转到 API 和服务 > 凭据页面。

    转到“凭据”页面

  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
        (如需了解详情,请参阅如何获取您的应用的 SHA-1 指纹。)
    • API 限制:
      1. 点击限制密钥
      2. 选择 API 下拉列表中选择 Maps SDK for Android
        (如果 Maps SDK for Android 未列出,您需要启用它。)
  4. 点击保存以完成更改。

如何获取您的应用的 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 工具会在您执行调试 build 时自动生成此证书。此证书只能用于要测试的应用。请勿尝试发布使用调试证书签名的应用。Android 开发者文档中的在调试模式下签名部分详细介绍了调试证书。
  • 发布证书:Android SDK 工具会在您执行发布 build 时自动生成此证书。您也可以使用 keytool 程序生成此证书。如果您已准备好公开发布应用,请使用此证书。

按照下面的步骤,结合使用 keytool 程序与 -v 参数来显示证书的 SHA-1 指纹。如需详细了解 Keytool,请参阅 Oracle 文档

调试证书

显示调试证书指纹

  1. 找到您的调试密钥库文件。该文件的文件名为 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. 找到您的发布证书密钥库文件。发布密钥库没有默认位置或名称。如果您在构建要发布的应用时未指定其发布密钥库的位置或名称,则该版本会保持 .apk 处于未签名状态,您需要先为其签名,然后才能发布该版本。对于发布证书,您还需要证书的别名以及密钥库和证书的密码。您可以通过输入以下内容来列出密钥库中所有密钥的别名:

    keytool -list -keystore your_keystore_name

    your_keystore_name 替换为密钥库的完全限定路径和名称,包括 .keystore 扩展名。系统将提示您输入密钥库的密码。然后,keytool 会显示密钥库中所有密钥的别名。

  2. 在终端或命令提示符中输入以下内容:

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    your_keystore_name 替换为密钥库的完全限定路径和名称,包括 .keystore 扩展名。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 指南。