使用 API 密钥

本主题介绍了如何为 Maps SDK for Android 创建 API 密钥、如何将其添加到您的应用,以及如何通过限制密钥来保护应用。您必须向使用 SDK 的任何应用添加 API 密钥。

准备工作

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

创建 API 密钥

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

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

  1. 依次转到 Google Maps Platform > 凭据页面。

    转到“凭据”页面

  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 文件,并将以下代码添加到 buildscript 下的 dependencies 元素中。
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:1.3.0"
        }
    }
        
  2. 接下来,打开应用级 build.gradle 文件,并将以下代码添加到 plugins 元素中。
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 保存文件并将项目与 Gradle 同步
  4. 在项目级目录中打开 local.properties,然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 保存文件并将项目与 Gradle 同步。
  6. 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 密钥时,必须提供用于为应用签名的签名密钥的 SHA-1 证书指纹。证书有两种:

  • 调试证书:此类证书只能用于要测试的应用和其他非生产代码。请勿尝试发布使用调试证书签名的应用。Android SDK 工具会在您运行调试 build 时自动生成此证书。
  • 发布证书:如果您已准备好将应用发布到应用商店,请使用此证书。Android SDK 工具会在您运行发布 build 时生成此证书。

如需详细了解数字证书,请参阅为应用签名指南。

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

  1. 依次转到 Google Maps Platform > 凭据页面。

    转到“凭据”页面

  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
        如需了解如何获取证书指纹,请参阅对客户端进行身份验证。如果您使用的是 Play 应用签名,则必须转到 Play 管理中心的“应用签名”页面才能获取证书指纹。
    • API 限制:
      1. 点击限制密钥
      2. 选择 API 下拉列表中选择 Maps SDK for Android。如果 Maps SDK for Android 未列出,您需要启用它。
  4. 点击保存以完成更改。