新增 API 金鑰限制

API 金鑰會向 Google Cloud識別您的應用程式或網站。API 金鑰限制可確保只有您的應用程式和網站可以使用金鑰。基於安全考量，建議您新增限制，指定：

如果用戶端使用受限的 API 金鑰發出要求，但要求不符合 API 金鑰限制，要求就會失敗。舉例來說，如果 API 金鑰要求 HTTP 請求必須從特定網域發出，但系統收到來自其他網域的 HTTP 請求，就會拒絕該請求並傳回錯誤。

使用 CreateKey 方法建立 API 金鑰時，可以新增限制，也可以使用 UpdateKey 方法在金鑰建立後新增限制。本頁說明可新增至 API 金鑰的限制，以及如何新增這些限制。

事前準備

這個頁面會使用 curl 和 Google Cloud CLI，將要求傳送至 API 金鑰 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，其中含有限制。

以下範例說明如何建立新的 API 金鑰，只允許來自特定網址清單的 HTTP 要求。

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 位址，例如網頁伺服器或 Cron 工作，允許這類呼叫端使用您的 API 金鑰。您可以透過下列任一格式指定 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

以下範例說明如何使用指紋和套件名稱，在 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 金鑰呼叫的 API。 Google Cloud 建議您為所有 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"
  }'

後續步驟