透過 API 金鑰限制 API 存取權

您可以使用 API 金鑰，限制 API 中特定 API 方法或所有方法的存取權。本頁說明如何限制擁有 API 金鑰的用戶端存取 API，以及說明如何建立 API 金鑰。

可擴充服務 Proxy (ESP) 使用 Service Control API 來驗證 API 金鑰，以及該金鑰與專案啟用的 API 之間的關聯。如果您將 API 設定成必須要有 API 金鑰才能存取，除非要求有在您專案中產生的金鑰，或在開發人員 (必須已獲您授予 API 啟用權限) 的其他專案中產生的金鑰，否則針對受保護的方法、類別或 API 提出的要求都會遭到拒絕。系統不會記錄建立該 API 金鑰的專案，也不會在要求標頭新增該專案。不過，您可以按照「篩選特定消費者專案」一節所述，依序點選「Endpoints」 >「Services」，查看與用戶端相關聯的 Google Cloud專案。

如要進一步瞭解應在哪個 Google Cloud 專案中建立 API 金鑰，請參閱「共用受 API 金鑰保護的 API」一節。

限制所有 API 方法的存取權

如想規定必須要有 API 金鑰才能存取 API 的所有方法：

  1. 在文字編輯器中開啟專案的 openapi.yaml 檔。

  2. 在 securityDefinitions: 下方，為 api_key: 新增 apiKey、key、query 值，如程式碼片段範例所示：

    securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"

    這樣會建立名為 api_key 的「安全性配置」，可用於保護 API。如需其他 api_key 定義選項，請參閱「API 金鑰定義限制」。

  3. 在檔案頂層 (非縮排或巢狀)，為 security 指令新增 api_key: []。您可能需要新增 security 指令；該指令也可能已經存在：

      security:
    - api_key: []

    這個指令會為檔案中的所有方法套用 api_key 安全性配置。請勿在方括號內填入任何字元。OpenAPI 規格需要空白清單，提供給不使用 OAuth 的安全性配置。

限制特定 API 方法的存取權

如想規定必須要有 API 金鑰才能存取特定方法：

  1. 在文字編輯器中開啟專案的 openapi.yaml 檔。

  2. 在檔案的頂層 (非縮排或巢狀) 新增空白的安全性指令，以便將它套用到整個 API：

    security: []

  3. 在 securityDefinitions: 下方，為 api_key: 新增 apiKey、key、query 值，如程式碼片段範例所示：

    securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"

    這樣會建立名為 api_key 的「安全性配置」，可用於保護 API。如需其他 api_key 定義選項，請參閱「API 金鑰定義限制」。

  4. 在方法的定義中，為 security 指令新增 api_key: []：

    ...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...

    這個指令會為該方法套用 api_key 安全性配置。請勿在方括號內填入任何字元。OpenAPI 規格需要空白清單，提供給不使用 OAuth 的安全性配置。

移除某個方法的 API 金鑰限制

若要關閉特定方法 API 金鑰驗證 (即使您限制了該 API 的 API 存取權)：

  1. 在文字編輯器中開啟專案的 openapi.yaml 檔。

  2. 在方法的定義中，新增空白的 security 指令：

    ...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

使用 API 金鑰呼叫 API

如果 API 或 API 方法需要 API 金鑰才能存取，請使用名為 key 的查詢參數來提供金鑰，如以下 curl 範例所示：

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

其中 ENDPOINTS_HOST 和 ENDPOINTS_KEY 是環境變數，分別包含 API 主機名稱和 API 金鑰。

共用受 API 金鑰保護的 API

API 金鑰與建立金鑰時所屬的 Google Cloud 專案相關聯。如果您決定要有 API 金鑰才能存取您的 API，要在哪一個 Google Cloud 專案建立 API 金鑰則取決於以下問題：

  • 您是否需要區別不同的 API 呼叫端，以利使用配額之類的 Endpoints 功能？
  • API 的所有呼叫端是否都有自己的 Google Cloud 專案？
  • 您是否需要設定不同的 API 金鑰限制？

您可以參考以下決策樹狀圖，決定應在哪一個 Google Cloud專案中建立 API 金鑰。

API 金鑰決策樹狀圖

授予 API 啟用權限

如果您需要區別 API 呼叫端，且每個呼叫端各自有其 Google Cloud 專案，您可以授予主要使用者權限，同意使用者在自己的 Google Cloud 專案中啟用您的 API。如此一來，您的 API 使用者就能自行建立 API 金鑰，以便與您的 API 一起使用。

例如，假設您的團隊已經建立可供公司內部不同用戶端程式使用的 API，且每個用戶端程式各自有其 Google Cloud專案。為區別 API 的呼叫端，必須在不同的 Google Cloud 專案中建立每個呼叫端的 API 金鑰。您可以將權限授予您的同事，讓對方能夠在與用戶端程式相關聯的 Google Cloud 專案中啟用您的 API。

如要讓使用者建立自己的 API 金鑰：

  1. 在設定 API 的 Google Cloud 專案中，將啟用 API 的權限授予每位使用者。
  2. 通知使用者，告知他們可以在自己的 Google Cloud專案啟用您的 API 及 建立 API 金鑰。

為每個呼叫端建立單獨的 Google Cloud 專案

如果您需要區別 API 呼叫端，但並非所有呼叫端都有 Google Cloud 專案，您可以分別為每個呼叫端建立一個 Google Cloud 專案以及 API 金鑰。建立專案之前請先斟酌專案名稱，以利辨別與專案相關聯的呼叫端。

舉例來說，假設您的 API 有外部客戶，且您不知道呼叫 API 的用戶端程式是如何建立的。也許有些用戶端使用 Google Cloud 服務且有 Google Cloud 專案，有些則並非如此。您必須分別為每個呼叫端建立一個 Google Cloud 專案和 API 金鑰，以利區別不同的呼叫端。

如要為每個呼叫端分別建立一個 Google Cloud 專案和 API 金鑰：

  1. 為每個呼叫端建立單獨的專案。
  2. 在每個專案啟用您的 API 並建立 API 金鑰。
  3. 將 API 金鑰分配給每個呼叫端。

為每個呼叫端建立一個 API 金鑰

若您不需要區別 API 呼叫端，但想要新增 API 金鑰限制，可以為同一個專案中的每個呼叫端分別建立一個 API 金鑰。

若要為同一個專案中的每個呼叫端建立一個 API 金鑰：

  1. 在已設定或已啟用 API 的專案中，為每個客戶建立 API 金鑰，且該金鑰應具有您需要的 API 金鑰限制。
  2. 將 API 金鑰分配給每個呼叫端。

建立一個所有呼叫端通用的 API 金鑰

若您不需要區別 API 呼叫端，也不需要新增 API 限制，但仍想要規定使用 API 金鑰 (例如為防止匿名存取)，可以建立一個可供所有呼叫端通用的 API 金鑰。

如要建立一個所有呼叫端通用的 API 金鑰：
  1. 在已設定或已啟用 API 的專案中，建立一個可供所有呼叫端通用的 API 金鑰。
  2. 將同一個 API 金鑰分配給每一個呼叫端。

最佳做法

如果您使用 API 金鑰保護 API 和使用者資料的存取權，請務必在設定可擴充服務 Proxy V2 (ESPv2) 啟動選項時，將 --service_control_network_fail_open 標記設為 close。標記的預設值為 open.

ESPv2 會呼叫 Service Control 來驗證 API 金鑰。如果連線至 Service Control 時發生網路錯誤，且 ESPv2 無法驗證 API 金鑰，系統就會拒絕任何可能使用詐欺金鑰向 API 提出的要求。

後續步驟