为 API 密钥添加限制

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

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

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

添加客户端限制

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

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

添加浏览器限制

以下示例展示了如何调用 UpdateKey 方法，将 HTTP Referrer 限制为 www.example.com：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "restrictions" : {
            "browserKeyRestrictions": {
              "allowedReferrers": "www.example.com"
            }
          },
          "etag": "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions'

当 operations.get 的响应包含 "done": true 时，response 包含具有限制的更新后的 Key。

以下示例展示了如何创建仅允许来自特定网址列表的 HTTP 请求的新 API 密钥。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with browser restrictions",
          "restrictions" : {
            "browserKeyRestrictions": {
              "allowedReferrers": ["www.example.com", "www.example-2.com"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

下表展示了一些示例场景和浏览器限制：

使用场景 限制
允许网站中的任何网址 您必须在 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 密钥：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "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"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

添加 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 密钥：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "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"
                }
              ]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

添加 iOS 限制

您可以在创建或更新密钥时提供每个应用的软件包 ID，将 API 密钥的使用仅限于您的 iOS 应用。以下示例展示了如何在创建 API 密钥时设置 iosKeyRestrictions：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with iOS restrictions",
          "restrictions" : {
            "iosKeyRestrictions": {
              "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
            }
          }
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

添加 API 限制

借助 API 限制，您可以指定可以使用 API 密钥调用哪些 Google Cloud API。我们建议您为所有 API 密钥添加客户端限制和 API 限制。

您可以在 API 限制中指定一项或多项服务。以下示例展示了如何将新 API 密钥的使用范围限制为仅限服务 translate.googleapis.com 和 datastore.googleapis.com：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "API key with API restrictions",
          "restrictions": {
            "api_targets": [
              {
                "service": "translate.googleapis.com"
              },
              {
                "service" : "datastore.googleapis.com"
              }
            ]
          },
        }' \
        'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

如需获取Google Cloud 项目中的已启用服务列表，请使用 gcloud services list 命令。

除了限制 API 密钥只能用于特定服务之外，您还可以选择指定每个服务中的方法，以进一步限制 API 密钥。以下示例展示了如何将上一个密钥限制为仅允许 translate.googleapis.com 的方法：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "restrictions": {
            "api_targets": [
              {
                "service": "translate.googleapis.com",
                "methods": [
                  "Get*",
                  "DetectLanguage"
                ]
              },
              {
                "service" : "datastore.googleapis.com"
              }
            ]
          },
          "etag": "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions'

后续步骤