API 키 사용

이 페이지에서는 API 게이트웨이에서 API 키를 사용하는 방법을 설명합니다.

API 키는 할당량, 청구, 모니터링 목적으로Google Cloud 프로젝트를 식별하는 문자열입니다. 개발자는 Google Cloud 콘솔의 프로젝트에서 API 키를 생성합니다. 그런 다음 API에 대한 모든 호출에 이 키를 쿼리 매개변수로 또는 요청 헤더에 포함합니다.

API 구성에 API 키 요구사항을 지정하면 API 게이트웨이가 이 API 키를 사용해서 연결된 Google Cloud 프로젝트를 조회합니다. API 키가 Google Cloud 프로젝트에서 또는 API가 사용 설정된 다른Google Cloud 프로젝트 내에서 생성되지 않았으면 API 게이트웨이가 요청을 거부합니다.

API 키를 만들거나 Google Cloud 프로젝트 내에서 이미 제공된 API 키를 보려면 API 및 서비스 > 사용자 인증 정보 페이지로 이동합니다.

사용자 인증 정보로 이동

API 키 사용

할당량과 같은 API 게이트웨이 기능을 사용하려면 클라이언트 애플리케이션이 연결된 Google Cloud 프로젝트를 API 게이트웨이가 식별할 수 있도록 API 키를 전달할 수 있습니다.

API 게이트웨이의 API 키 인증 구성

API 키를 사용하여 게이트웨이에 대한 액세스를 보호하려면 다음 안내를 따르세요.

  1. 서비스에 대해 API 키 지원을 사용 설정합니다. 다음 명령어를 입력합니다. 각 항목의 의미는 다음과 같습니다.
    • MANAGED_SERVICE_NAME은 API를 배포할 때 만든 관리형 서비스의 이름을 지정합니다. gcloud api-gateway apis describe 명령어를 사용해서 나열된 관리형 서비스 속성에서 확인할 수 있습니다.
    • 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 키 검증 보안 정책을 적용하도록 API 구성을 만드는 데 사용된 OpenAPI 사양을 수정합니다. 다음과 같이 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은 사양에 정의된 모든 경로에 액세스를 요청할 때 key라는 쿼리 매개변수로 API 키가 전달되도록 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은 사양에 정의된 모든 경로에 액세스를 요청할 때 key라는 이름의 쿼리 매개변수로 API 키가 전달되도록 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 콘솔에서 API 및 서비스 > 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보로 이동

  3. API에 사용할 API 키의 이름을 선택합니다.

  4. API 키 세부정보 페이지의 API 제한사항 섹션에서 키 제한을 클릭합니다.

  5. 사용 가능한 API의 드롭다운 목록에서 API 키를 사용하여 액세스할 API를 선택합니다. 예를 들어 My Example Config을 선택합니다.

  6. 저장을 클릭합니다.

일시적으로 제한사항이 적용됩니다.