为 API 密钥添加限制

API 密钥向 Google Cloud 标识应用或网站。API 密钥限制可确保只有您的应用和网站可以使用您的密钥。出于安全原因，我们建议您添加的限制如下：

哪些客户端或网站可以使用您的 API 密钥。
您的应用可以使用您的 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”列表中设置两个网址。域名的网址，不带子域名，以及路径的通配符。例如： `example.com/` 包含子网域通配符和路径通配符的第二个网址。例如： `.example.com/*`
允许特定的网址	添加具有确切路径的网址。例如： `www.example.com/path` `www.example.com/path/path`
允许单个子网域或裸网域中的任何网址	您必须在“allowedReferers”列表中设置两个网址，才能允许整个网域。域名，不带斜杠。例如： `www.example.com` `sub.example.com` `example.com` 包含路径通配符的第二个网址。例如： `www.example.com/` `sub.example.com/` `example.com/*`

添加服务器限制

您可以指定调用方可以使用一个或多个 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"
  }'