Maps SDK for Android：获取 API 密钥

注意：Google Maps Platform 高级计划不再适用于注册客户或新客户。

如需使用 Maps SDK for Android，您必须拥有一个 API 密钥。API 密钥是唯一标识符，用于对与您的项目相关联的请求进行身份验证，以便您使用相关产品和执行结算。

获取 API 密钥

您必须至少有一个与您的项目相关联的 API 密钥。

要获取 API 密钥，请执行以下操作：

  1. 访问 Google Cloud Platform Console。
  2. 点击项目下拉菜单，选择在您购买高级计划时系统为您创建的项目。项目名称以 Google Maps API for Business 或 Google Maps for Work 或 Google Maps 开头。

    3. 注意：如需拥有对计划中的功能的完整访问权限，高级计划客户应使用与其高级计划帐号相关联的项目。购买许可时，您会收到如下格式的高级计划资产名称：gme-[company] & proj-[number] ([type])。为确保您访问的是正确的项目，请通过 console.cloud.google.com/project/number（将 number 替换为您的项目编号）以项目所有者身份登录控制台。您可以在欢迎邮件中找到项目所有者。

  3. 点击菜单按钮 ，然后依次选择 API 和服务 > 凭据。
  4. 在凭据页面上，依次点击创建凭据 > API 密钥。
    已创建的 API 密钥对话框会显示您新创建的 API 密钥（一个加密字符串）。
  5. 点击关闭。
    新的 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 属性中，将 YOUR_API_KEY 替换为您的 API 密钥（加密字符串）。该元素会将密钥 com.google.android.geo.API_KEY 设置为您的 API 密钥的值。

  2. 保存 AndroidManifest.xml 并重新构建您的应用。

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

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

调试证书

显示调试证书指纹

  1. 找到您的调试密钥库文件。该文件的文件名为 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. 找到您的发布证书密钥库文件。发布密钥库没有默认位置或名称。如果您在构建要发布的应用时未指定其发布密钥库的位置或名称，则该版本会保持 .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 指南。