API 密钥向 Google Cloud 标识应用或网站。API 密钥限制可确保只有您的应用和网站可以使用您的密钥。出于安全原因,我们建议您添加的限制如下:
如果客户端使用受限 API 密钥发出不符合 API 密钥限制的请求,则请求会失败。例如,如果 API 密钥要求从特定网域发出 HTTP 请求,但从不同的网域收到 HTTP 请求,请求将被拒绝并报错。
您可以在使用 CreateKey
方法创建 API 密钥时添加限制,也可以在使用 UpdateKey
方法创建密钥后添加限制。本页面介绍了可添加到 API 密钥的限制,并且介绍如何添加这些限制。
准备工作
该页面将 curl
与 oauth2l 命令行工具结合使用,以向 API Keys 的 API 发送请求。如需详细了解如何开始使用 API,请参阅 API 密钥使用入门。
添加客户端限制
客户端限制用于指定哪些网站、IP 地址或应用可以使用 API 密钥。您可以根据调用 API 的客户端类型添加客户端限制。您可以指定以下某种类型的客户端限制:
browserKeyRestrictions
:可以使用该密钥的 HTTP 引荐来源网址(网站)。serverKeyRestrictions
:可以使用该密钥的调用方的 IP 地址。androidKeyRestrictions
:可使用该密钥的 Android 应用。iosKeyRestrictions
:可以使用该密钥的 iOS 应用。
添加浏览器限制
以下示例展示了如何调用 UpdateKey
方法将 HTTP 引荐来源网址限制为 www.example.com
:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \ --request PATCH \ --data '{ "restrictions" : { "browserKeyRestrictions": { "allowedReferrers": "www.example.com" } } "etag": "ETAG" }'
当来自 operations.get
的响应包含 "done": true
时,response
包含已更新的 Key
,但有限制的限制。
以下示例展示了如何创建仅允许来自特定网址列表的 HTTP 请求的新 API 密钥。
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with browser restrictions", "restrictions" : { "browserKeyRestrictions": { "allowedReferrers": ["www.example.com", "www.example-2.com"] } } }'
下表显示了一些场景和浏览器限制:
场景 | 限制 |
---|---|
允许网站中的任何网址 | 您必须在“allowedReferers”列表中设置两个网址。
|
允许特定的网址 | 添加具有确切路径的网址。例如:www.example.com/path www.example.com/path/path
|
允许单个子网域或裸网域中的任何网址 | 您必须在“allowedReferers”列表中设置两个网址,才能允许整个网域。
|
添加服务器限制
您可以指定调用方可以使用一个或多个 IP 地址,例如 Web 服务器或 Cron 作业。您可以使用以下任何格式指定 IP 地址:
- IPv4 (
198.51.100.1
) - IPv6 (
2001:db8::1
) - 使用 CIDR 表示法的子网(
198.51.100.0/24
、2001:db8::/64
)
以下示例演示了如何使用 allowedIps
列表创建 API 密钥:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR", "restrictions" : { "serverKeyRestrictions": { "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"] } } }'
添加 Android 限制
您可以将 API 密钥的使用范围限制为仅限您的 Android 应用。创建或更新 API 密钥时,请提供每个应用的软件包名称和 20 字节 SHA-1 指纹。
例如,假设您运行 keytool
实用程序,并创建了以下指纹:
Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09
以下示例展示了如何创建带有指纹和软件包名称的 API 密钥到 androidKeyRestrictions
:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with Android restrictions", "restrictions" : { "androidKeyRestrictions": { "allowedApplications": [ { "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09", "packageName": "com.example.my.app" } ] } } }'
添加 iOS 限制
在创建或更新密钥时,您可以通过提供每个应用的软件包 ID,将 API 密钥的使用范围限制为 iOS 应用。以下示例展示了如何在创建 API 密钥时设置 iosKeyRestrictions
:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with iOs restrictions", "restrictions" : { "iosKeyRestrictions": { "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"] } } }'
添加 API 限制
API 限制用于指定可以使用 API 密钥调用哪些 Google Cloud API。我们建议您将所有 API 密钥都同时添加客户端和 API 限制。
您可以在 API 限制中指定一项或多项服务。以下示例展示了如何将新的 API 密钥限制为 translate.googleapis.com
和 datastore.googleapis.com
服务:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "restrictions": { "api_targets": [ { "service": "translate.googleapis.com" }, { "service" : "datastore.googleapis.com" } ] }, }'
如需获取您的 Cloud 项目中已启用的服务的列表,请使用 gcloud services list
命令。
除了限制用于特定服务的 API 密钥之外,您还可以选择在每个服务中指定方法,以进一步限制 API 密钥。以下示例展示了如何将先前的密钥限制为允许使用的 translate.googleapis.com
方法:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \ --request PATCH \ --data '{ "restrictions": { "api_targets": [ { "service": "translate.googleapis.com" "methods": [ "Get*", "DetectLanguage" ] }, { "service" : "datastore.googleapis.com" } ] }, "etag": "ETAG" }'