为 API 密钥添加限制

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

如果客户端使用受限 API 密钥发出不满足 API 密钥限制的请求，则该请求会失败。例如，如果某个 API 密钥要求 HTTP 请求必须从特定网域发出，但系统收到的 HTTP 请求来自其他网域，则会拒绝该请求并显示错误。

您可以在使用 CreateKey 方法创建 API 密钥时添加限制，也可以在使用 UpdateKey 方法创建密钥后添加限制。本页面介绍了您可以向 API 密钥添加的限制，并演示了如何添加这些限制。

准备工作

此页面使用 curl 和 Google Cloud CLI 向 API 密钥 API 发送请求。如需详细了解如何设置 API 以进行实验，请参阅 API Keys 使用入门。

添加客户端限制

客户端限制用于指定哪些网站、IP 地址或应用可以使用 API 密钥。您可以根据调用 API 的客户端类型添加客户端限制。您可以指定以下类型的客户端限制之一：

  • browserKeyRestrictions：获准使用该密钥的 HTTP 引荐来源网址（网站）。
  • serverKeyRestrictions：允许使用相应密钥的调用者的 IP 地址。
  • androidKeyRestrictions：获准使用该密钥的 Android 应用。
  • iosKeyRestrictions：获准使用该密钥的 iOS 应用。

添加浏览器限制

以下示例展示了如何调用 UpdateKey 方法，将 HTTP Referrer 限制为 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 列表中设置两个网址。
  1. 网域的网址，没有子网域，其中包含路径通配符。例如：
    example.com/*
  2. 第二个网址，其中包含子网域通配符和路径通配符。例如：
    *.example.com/*
允许特定的网址 添加包含确切路径的网址。例如：
www.example.com/path
www.example.com/path/path
允许单个子网域或裸网域中的任何网址 您必须在“allowedReferers”列表中设置两个网址以允许整个网域。
  1. 网域的网址，不含尾随斜杠。例如：
    www.example.com
    sub.example.com
    example.com
  2. 网域的第二个网址，其中包含路径通配符。例如：
    www.example.com/*
    sub.example.com/*
    example.com/*

添加服务器限制

您可以指定调用方的一个或多个 IP 地址，例如可以使用 API 密钥的 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 限制

您可以限制只有您的 Android 应用可以使用 API 密钥。创建或更新 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

以下示例展示了如何使用指纹和软件包名称向 androidKeyRestrictions 创建 API 密钥：

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"
        }
      ]
    },
  }'

如需获取Google 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"
  }'

后续步骤