Google Maps Platform 推出 15 周年 - 查看最新资讯和公告

获取 API 密钥

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

获取 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 属性中,将 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 密钥的使用范围限制为网站(通过 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 应用并按照说明操作。
      • 点击 + 添加软件包名称和指纹
      • 输入您的软件包名称和 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,您需要启用它。)
    • 点击保存

如何获取您的应用的 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 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 指南。

高级计划客户和已迁移的客户

如果是高级计划客户或从高级计划迁移到 Google Maps Platform 随用随付定价模式的客户,可以使用 API 密钥或客户端 ID 对请求进行身份验证。如需了解详情,请参阅高级计划文档中的获取 API 密钥概览