对于使用 Google Maps Platform API 和 SDK 的应用和项目而言,API 密钥是必需的。本文档介绍了 API 密钥的预期用途、如何像保护其他凭据一样保护这些密钥,以及哪些限制适用于您的项目。
什么是 API 密钥?
API 密钥是以项目为中心的凭据,具有以下两种用途:
- 项目识别。
识别调用相关 API 或 SDK 的应用或项目。 - 项目授权。
检查调用方应用是否具有调用相关 API 或 SDK 的权限,并在项目中启用了相关 API 或 SDK。
创建 API 密钥后,该密钥即与项目相关联。通过识别调用方项目,API 密钥可将使用情况信息与该项目相关联,还可协助确保系统拒绝来自其他项目的调用。
保护 API 密钥
针对您应用所使用的所有 Google Maps Platform 产品,您应该确保您应用中的API 密钥的安全。想要确保 API 密钥的安全,您可以指定限制以及实施适合您的应用所用 Google Maps Platform API 的最佳做法。公开泄露未受妥善保护的凭据可能导致意外使用,进而可能使您的帐号产生预料之外的费用。
以下做法介绍了有助于保护 API 密钥的策略。API 密钥限制和最佳做法部分列出了适合各个 Google Maps Platform 产品(如 Maps JavaScript API)的做法。
-
限制您的 API 密钥。为了最有效地保护 API 密钥,您可以将其使用范围限制为特定 IP 地址、引荐来源网址或移动应用以及特定 API,因为这样做可以显著降低密钥泄露产生的影响。
您可以通过以下方法在控制台中为密钥设置指定的应用和 API 限制:打开“凭据”页面,然后使用所需设置创建新的 API 密钥,或修改 API 密钥的设置。如需了解完整详情,请参阅限制 API 密钥。
- 为不同的应用使用独立的 API 密钥。这可限制每个密钥的使用范围。如果 API 密钥泄露,您可以删除并撤消受影响的密钥,而无需更新其他 API 密钥。
- 删除不需要的 API 密钥。
如需删除 API 密钥,请执行以下操作:
- 访问“凭据”面板。
- 选择要删除的 API 密钥。
- 点击页面顶部附近的删除按钮。
- 在出现删除凭据弹出式窗口时,点击删除。
-
重新生成 API 密钥时要小心谨慎。如果您的应用从使用旧 API 密钥改为使用重新生成的新 API 密钥所需的时间超过 24 小时,则未更新的应用实例将会出现异常,因为它们引用的是旧密钥,而这些旧密钥将在重新生成密钥 24 小时后销毁。
重新生成 API 密钥后,会出现以下情况:
- 通过重新生成流程得到新的密钥。
- 新密钥会沿袭旧密钥的所有限制。
- 开始计时,旧密钥会在 24 小时候之后销毁。
-
监控 API 的使用是否存在异常。如果您发现未经授权的使用,请轮替密钥并通知 Google。
在轮替密钥之前,请将与该密钥关联的限制复制到一个文件中以保留这些限制。
-
对于使用地图网络服务 API 或静态网络 API 的应用,请采用以下方法保护应用和 API 密钥:
- 不要直接在代码中嵌入 API 密钥或签名密钥。不要直接在应用的代码中嵌入 API 密钥或任何其他隐私信息,而应将它们放在环境变量或包含文件中,这些文件与大部分代码分开存储在应用源代码库以外的位置。然后,如果您共享代码,API 密钥或签名密钥将不会包含在共享文件中。
- 不要将 API 密钥或签名密钥存储在应用源代码树内的文件中。如果您将 API 密钥或任何其他隐私信息存储在文件中,请将文件存放在应用的源代码树之外,这有助于确保密钥或其他隐私信息不会进入源代码控制系统。如果您使用公共源代码管理系统(如 GitHub),这种做法尤为重要。
- 检查代码之后再公开发布。确保您的代码不包含 API 密钥、签名密钥或任何其他隐私信息,然后再公开代码。
-
对于使用网络服务 API 或静态网络 API 的移动应用,请考虑采用以下一种或多种方法进一步保护 API 密钥或签名密钥:
-
使用代理服务器。通过代理服务器与适当的 Google Maps Platform API 互动非常可靠。如需详细了解如何使用代理服务器,请参阅代理体验:将代理服务器与 Google 数据 API 客户端库配合使用。
- 混淆或加密 API 密钥或签名密钥。这样一来,直接从应用抓取 API 密钥和其他隐私数据就会变得比较复杂。
-
限制 API 密钥
API 密钥是凭据,应谨慎管理。请至少遵循下列建议来保证密钥的安全,并确保设置适当的限制来降低 API 密钥泄露产生的影响。
您可以通过指定应用限制或者一项或多项 API 限制来限制 API 密钥。
应用限制:将 API 密钥的使用范围限制为特定网站(IP 地址和网站)或特定平台(Android 和 iOS)。您最多可以从该类别中选择一项限制(请参阅 Google Maps Platform API(按平台))。
API 限制:将 API 密钥的使用范围限制为一个或多个 Google Maps Platform API 或 SDK。系统会处理针对与 API 密钥关联的 API 或 SDK 发出的使用请求。针对未与 API 密钥关联的 API 或 SDK 发出的使用请求将会失败。对于一个 API 密钥,您可以根据需要指定任意数量的 API 限制。请确保与 API 密钥关联的 API 或 SDK 支持为该 API 密钥设置的应用限制。
为 API 密钥设置应用限制
- 访问“凭据”面板。
- 选择您要设置限制的 API 密钥。系统随即会显示 API 密钥属性页面。
- 在“密钥限制”下,选择应用限制。
选择一种限制类型,并按照限制列表提供所需信息。限制类型 说明 HTTP 引荐来源 接受来自您提供的一系列网站的请求。
在类型下方,指定一个或多个引荐来源网站。可以使用通配符来命名类似的网站。例如,指定
*.google.com
表示接受所有以google.com
结尾的网站,例如https://developers.google.com
。IP 地址 接受来自您提供的一系列网络服务器 IP 地址的请求。
在类型下方,指定一个 IPv4 或 IPv6 地址,或采用 CIDR 表示法的子网(例如 192.168.0.0/22)。如果您需要输入其他条目,在您添加完上一个条目后,系统会显示一个新框。
Android 应用 添加您的软件包名称和 SHA-1 签名证书指纹,以将 API 的使用范围限制为您的 Android 应用。
在类型下方,添加 SHA-1 签名证书指纹和 AndroidManifest.xml 文件中的 Android 软件包名称。
iOS 应用 接受来自 iOS 应用(具有您提供的软件包标识符)的请求。
在类型下方,从列表中选择相应的 iOS 软件包标识符。
- 点击保存。
完成此步骤后,所设限制将成为 API 密钥定义的一部分。如果您没有提供适当的详细信息或没有点击“保存”,系统将不会限制 API 密钥(如需了解详情,请参阅您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南)。
为 API 密钥设置 API 限制
- 转到“凭据”面板。
- 选择您要设置限制的 API 密钥。
系统会显示“限制和重命名 API 密钥”页面。 - 在“API 限制”下:
- 点击限制密钥。
- 点击选择 API 下拉列表,然后选择您想要应用通过该 API 密钥访问的 API 或 SDK(如果其中未列出某个 API 或 SDK,您需要启用它)。
- 点击保存。
完成此步骤后,所设限制将成为 API 密钥定义的一部分。如果您没有提供适当的详细信息或没有点击“保存”,系统将不会限制 API 密钥(如需了解详情,请参阅您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南)。
API 密钥限制和最佳做法
下面的表格列出了适合每个 Google Maps Platform API、SDK 或服务的 API 密钥限制和最佳做法。
使用 Maps JavaScript API、Maps Embed API 或 Maps Static API 的网站
API/SDK/服务 | 应用限制(1) | API 限制(1) | 最佳做法 |
---|---|---|---|
Maps JavaScript API(2) | “HTTP 引荐来源”限制 | Maps JavaScript API | |
路线服务、Maps JavaScript API | “HTTP 引荐来源”限制 | Directions API、Maps JavaScript API | |
距离矩阵服务、Maps JavaScript API | “HTTP 引荐来源”限制 | Distance Matrix API、Maps JavaScript API | |
海拔服务、Maps JavaScript API | “HTTP 引荐来源”限制 | Elevation API、Maps JavaScript API | |
地理编码服务、Maps JavaScript API | “HTTP 引荐来源”限制 | Geocoding API、Maps JavaScript API | |
Places Library、Maps JavaScript API | “HTTP 引荐来源”限制 | Places API、Maps JavaScript API | |
Maps Embed API | “HTTP 引荐来源”限制 | Maps Embed API | |
Maps Static API | “HTTP 引荐来源”限制 | Maps Static API | |
Street View Static API | “HTTP 引荐来源”限制 | Street View Static API |
使用网络服务的应用和服务器
API/SDK/服务 | 应用限制(1) | API 限制(1) | 最佳做法 |
---|---|---|---|
Directions API | “IP 地址”限制(4) | Directions API | |
Distance Matrix API | “IP 地址”限制(4) | Distance Matrix API | |
Elevation API | “IP 地址”限制(4) | Elevation API | |
Geocoding API | “IP 地址”限制(4) | Geocoding API | |
Geolocation API | “IP 地址”限制(4) | Geolocation API | |
Places API(5) | “IP 地址”限制(4) | Places API | |
Roads API | “IP 地址”限制(4) | Roads API | |
Time Zone API | “IP 地址”限制(4) | Time Zone API |
Android 应用
API/SDK/服务 | 应用限制(1) | API 限制(1) | 最佳做法 |
---|---|---|---|
Maps SDK for Android | “Android”限制 | Maps SDK for Android | |
Places SDK for Android | “Android”限制 | Places API |
iOS 应用
API/SDK/服务 | 应用限制(1) | API 限制(1) | 最佳做法 |
---|---|---|---|
Maps SDK for iOS | “iOS”限制 | Maps SDK for iOS | |
Places SDK for iOS | “iOS”限制 | Places API |
1 您可以将不受限制的 API 密钥与任何 Google Maps Platform API 或 SDK 搭配使用。但是,我们强烈建议您限制 API 密钥,尤其是在以下情况下:
- 测试环境将要或已经对外公开。
- 使用 API 密钥的应用已准备好在生产环境中使用。
2 对于移动应用,请考虑使用原生的 Maps SDK for Android 和 Maps SDK for iOS。
3 对于 Maps Static API 和 Street View Static API,除了 API 密钥之外,您还需要提供数字签名才能超过每日配额(2.5 万次地图加载)。
注意:用于签名的共享密钥至少需要与地图网络服务 API 所用的 API 密钥具有相同的安全级别。
如果您需要为图片请求进行动态签名,请在服务器端进行。如果您的应用依靠客户端输入来生成静态图片,请采用以下一种或多种方法保护应用:
如果您要对请求进行签名,还要检查您希望每天允许的未签名请求数量,并相应地调整未签名请求的配额。
4 设置 IP 限制可能不切实际,例如在依赖动态 IP 地址的移动应用和云环境中。在这些情况下使用地图网络服务 API 时,请采用以下一种或多种方法保护您的应用:
5 对于移动应用,请考虑使用原生的 Places SDK for Android 和 Places SDK for iOS。