透過 API 金鑰限制 API 存取權

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

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

如要進一步瞭解應該在哪個 GCP 專案中建立 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}"

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

共用受 API 金鑰保護的 API

API 金鑰與此金鑰原生的 Google Cloud Platform (GCP) 專案相關聯。如果您決定要有 API 金鑰才能存取您的 API,要在哪一個 GCP 專案建立 API 金鑰則取決於以下問題:

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

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

API 金鑰決策樹狀圖

授予 API 啟用權限

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

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

若要讓使用者建立自己的 API 金鑰:

  1. 在設定 API 的 GCP 專案中,將啟用 API 的權限授予每位使用者。
  2. 與使用者聯絡,讓他們知道可以在自己的 GCP 專案中啟用您的 API建立 API 金鑰

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

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

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

若要為每個呼叫端分別建立一個 GCP 專案和 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 金鑰分配給每一個呼叫端。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁