使用 API 金鑰

本頁面說明如何在 API Gateway 中使用 API 金鑰。

API 金鑰是一組字串，用於識別Google Cloud 專案的配額、帳單及監控等功能。開發人員會在 Google Cloud 控制台的專案中產生 API 金鑰。然後將該金鑰以查詢參數或要求標頭的形式，嵌入在對 API 發出的每一個呼叫中。

如果您在 API 設定中指定 API 金鑰需求，API Gateway 會使用該 API 金鑰查詢相關聯的 Google Cloud 專案。除非 API 金鑰是在 Google Cloud 專案中或在已啟用您 API 的其他Google Cloud 專案中產生，否則 API Gateway 會拒絕要求。

如要建立 API 金鑰，或查看專案中已有的 API 金鑰，請前往「API 和服務」>「憑證」頁面。 Google Cloud

前往「憑證」

使用 API 金鑰

如要使用 API Gateway 功能 (例如配額)，可以傳入 API 金鑰，讓 API Gateway 識別與用戶端應用程式相關聯的 Google Cloud 專案。

為 API Gateway 設定 API 金鑰驗證

如要使用 API 金鑰確保閘道存取安全，請按照下列步驟操作：

  1. 為服務啟用 API 金鑰支援功能。輸入下列指令，其中：
    • MANAGED_SERVICE_NAME 是指您部署 API 時建立的代管服務名稱。您可以使用 gcloud api-gateway apis describe 指令查看列出的 Managed Service 屬性。
    • PROJECT_ID 指定 Google Cloud 專案的名稱。
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     舉例來說： 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. 修改用來建立 API 設定的 OpenAPI 規格，加入對所有流量強制執行 API 金鑰驗證安全性政策的指令。新增 security 類型和 securityDefinitions 或 securitySchemes，如下所示：

    OpenAPI 2.0

      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

    當要求存取規格中定義的所有路徑時，securityDefinition 會將您的 API 設定為要求以名為 key 的查詢參數形式傳遞 API 金鑰。

    OpenAPI 3.x

    # openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

    當要求存取規格中定義的所有路徑時，securitySchemes 會將您的 API 設定為要求以名為 key 的查詢參數形式傳遞 API 金鑰。
  3. 使用下列指令，以修改後的 OpenAPI 說明建立新的 API 設定： 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     舉例來說： 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. 執行下列指令，以新的 API 設定更新現有閘道： 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GATEWAY_LOCATION --project=PROJECT_ID
     舉例來說： 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

限制 API 金鑰

根據預設，API 金鑰不受限制，因此容易遭到未經授權的使用。盡可能新增 API 限制。API 限制指定了 API 金鑰可以呼叫哪些 API。正式版應用程式使用的所有 API 金鑰都應設有 API 限制。

如要新增 API 限制，請按照下列步驟操作：

  1. 找出 API 設定中註明的 API 標題。在以下範例中，API 標題為 My Example Config：

    OpenAPI 2.0

    # openapi.yaml
swagger: '2.0'
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

    OpenAPI 3.x

    # openapi.yaml
openapi: 3.0.4
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

  2. 在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務) >「Credentials」(憑證) 頁面。

    前往「憑證」

  3. 選取要用於 API 的 API 金鑰名稱。

  4. 在 API 金鑰詳細資料頁面的「API 限制」部分，按一下「限制金鑰」。

  5. 從可用 API 的下拉式清單中，選取要使用 API 金鑰存取的 API。例如選取 My Example Config。

  6. 按一下 [儲存]。

限制應該會立即生效。