使用 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 金鑰，或查看 Google Cloud 專案中已有的 API 金鑰，請前往「API 和服務」>「憑證」頁面，然後按照「建立 API 金鑰」一文中的步驟操作。

前往「憑證」

為 API Gateway 設定 API 金鑰驗證

設定 API Gateway 的 API 金鑰驗證，使用 API 金鑰保護閘道存取權，詳情請參閱下列章節。

為服務啟用 API 金鑰支援功能。
Google Cloud 控制台

請執行下列步驟：
1. 在 Google Cloud 控制台中，依序前往「APIs & Services」(API 與服務) >「Library」(程式庫)。
  前往「API 與服務程式庫」
2. 在搜尋列中輸入 API 的代管服務名稱。您可以在 API 登陸頁面的「Managed Service」(受管理服務) 欄中找到 API 的這個值。例如：
  my-api-123abc456def1.apigateway.my-project.cloud.goog
3. 按一下服務資訊卡，即可查看到達網頁。
4. 在服務的到達網頁上，按一下「啟用」。
  注意：建立 API 後，最多可能需要 30 分鐘或更久，API 才會顯示在程式庫中。
Google Cloud CLI

輸入下列指令，其中 MANAGED_SERVICE_NAME 指定部署 API 時建立的代管服務名稱。您可以使用 gcloud api-gateway apis describe 指令查看列出的 Managed Service 屬性。
gcloud services enable MANAGED_SERVICE_NAME
例如：
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog

修改用來建立 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:
  backends:
    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 金鑰。

使用下列指令，以修改後的 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

執行下列指令，以新的 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 限制，請按照下列步驟操作：

找出 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
...

在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務) >「Credentials」(憑證) 頁面。
前往「憑證」
選取要用於 API 的 API 金鑰名稱。
在 API 金鑰詳細資料頁面的「API 限制」部分，按一下「限制金鑰」。
從可用 API 的下拉式清單中，選取要使用 API 金鑰存取的 API。例如選取 My Example Config。
按一下 [儲存]。

限制應該會立即生效。