透過 API 金鑰限制 API 存取權

您可以使用 API 金鑰，限制特定 API 方法或 API 中所有方法的存取權。本頁面說明如何限制只有具 API 金鑰的用戶端可存取 API，並示範 API 金鑰的建立方式。

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

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

限制所有 API 方法的存取權

如要規定必須具備 API 金鑰才能對 API 發出呼叫，請新增 api_key_required=True 至您的 API 裝飾器。例如：

@endpoints.api(name='echo', version='v1', api_key_required=True)
class EchoApi(remote.Service):
#...

限制特定 API 方法的存取權

如要規定要有 API 金鑰才能對特定 API 方法發出呼叫，請將 api_key_required=True 新增到 API 方法裝飾器中。例如：

endpoints.method(
  # This method takes an Echo message.
  ECHO_RESOURCE,
  # This method returns an Echo message.
  EchoResponse,
  path='echo',
  http_method='POST',
  name='echo_api_key',
  api_key_required=True)
def echo_api_key(self, request):
  output_content = '\n'.join([request.content] * request.n)
  return EchoResponse(content=output_content)

移除方法的 API 金鑰限制

如要關閉 API 或 API 方法的 API 金鑰驗證，請從您的 API、方法裝飾器或註解中，移除 api_key_required=True (Python) 或 apiKeyRequired = AnnotationBoolean.TRUE (Java)。然後重新編譯及重新部署。

使用 API 金鑰呼叫 API

如果 API 或 API 方法要求提供 API 金鑰，請使用名為 key 的查詢參數提供金鑰，如此 cURL 範例所示：

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

其中 HOST 和 API_KEY 分別是內含您的 API 主機名稱和 API 金鑰的變數。將 echo 替換為您的 API 名稱，並將 v1 替換為您的 API 版本。

共用受 API 金鑰保護的 API

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

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

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

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 金鑰，且該金鑰應具有您需要的 API 金鑰限制。
  2. 將同一個 API 金鑰分配給每一個呼叫端。

後續步驟