API 키로 API 액세스 제한

API 키를 사용하여 특정 API 메서드 또는 API의 모든 메서드에 대한 액세스를 제한할 수 있습니다. 이 페이지에서는 API 키가 있는 클라이언트로 API 액세스를 제한하는 방법과 API 키를 만드는 방법을 설명합니다.

API에 API 키 요구사항을 설정하면 보호되는 메서드, 클래스 또는 API에 대한 요청은 내 프로젝트나 내가 API 사용 설정 권한을 부여한 개발자가 소유한 다른 프로젝트에서 생성된 키가 포함된 경우를 제외하고는 모두 거부됩니다. API 키가 생성된 프로젝트는 로깅되지 않으며 요청 헤더에 추가되지 않습니다. 하지만 특정 소비자 프로젝트용 필터의 설명대로 Endpoints 서비스 페이지에서 클라이언트와 연결된 Google Cloud 프로젝트를 확인할 수 있습니다.

API 키를 만들어야 하는 Google Cloud 프로젝트에 대한 자세한 내용은 API 키로 보호되는 API 공유를 참조하세요.

모든 API 메서드에 대한 액세스 제한

API에 대한 모든 호출에 API 키가 필요하도록 만들려면 apiKeyRequired = AnnotationBoolean.TRUE을 @Api 주석에 추가합니다. 예를 들면 다음과 같습니다.

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

특정 API 메서드에 대한 액세스 제한

특정 API 메서드에 대한 모든 호출에 API 키가 필요하도록 만들려면 apiKeyRequired = AnnotationBoolean.TRUE를 @ApiMethod 주석에 추가합니다. 예를 들면 다음과 같습니다.

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

특정 API 클래스에 대한 모든 호출에 API 키가 필요하도록 만들려면 apiKeyRequired = AnnotationBoolean.TRUE을 @ApiClass 주석에 추가합니다.

메서드의 API 키 제한 삭제

API 또는 API 메서드의 API 키 검증을 비활성화하려면 api_key_required=True(Python) 또는 apiKeyRequired = AnnotationBoolean.TRUE(자바)를 API, 메서드 데코레이터 또는 주석에서 삭제합니다. 그런 다음 다시 컴파일하고 재배포합니다.

API 키를 사용하여 API 호출

API 또는 API 메서드에 API 키가 필요한 경우 다음의 cURL 예시와 같이 쿼리 매개변수 key를 사용하여 키를 제공합니다.

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 키가 필요하도록 결정했다면 API 키가 생성되는 Google Cloud 프로젝트는 다음 질문에 대한 답에 따라 달라집니다.

할당량과 같은 Endpoints 기능을 사용할 수 있도록 API 호출자를 구별해야 하나요?
모든 API 호출자에게 자체 Google Cloud 프로젝트가 있나요?
API 키 제한을 다양하게 설정해야 하나요?

다음과 같은 결정 트리를 참조하여 API 키를 만들 Google Cloud 프로젝트를 결정할 수 있습니다.

API를 사용 설정하도록 권한 부여

API 호출자를 구분하고 각 호출자에게 자체 Google Cloud 프로젝트가 있도록 해야 한다면 주 구성원에게 자체 Google Cloud 프로젝트에서 API를 사용 설정할 수 있는 권한을 부여하면 됩니다. 이렇게 하면 API 사용자는 API에서 사용할 자체 API 키를 만들 수 있습니다.

예를 들어 팀에서 회사의 다양한 클라이언트 프로그램에서 내부적으로 사용할 API를 만들었고 각 클라이언트 프로그램에 자체 Google Cloud 프로젝트가 있다고 가정해 보겠습니다. API 호출자를 구분하기 위해 각 호출자의 API 키는 서로 다른 Google Cloud 프로젝트에서 생성되어야 합니다. 동료에게 클라이언트 프로그램이 연결된 Google Cloud 프로젝트에서 API를 사용 설정할 수 있는 권한을 부여할 수 있습니다.

사용자가 자체 API 키를 만들도록 허용하려면 다음 안내를 따르세요.

API가 구성된 Google Cloud 프로젝트에서 각 사용자에게 API 사용 설정 권한을 부여합니다.
사용자에게 자체 Google Cloud 프로젝트에서 API를 사용 설정하고 API 키를 만들 수 있음을 알립니다.

각 호출자별로 별도의 Google Cloud 프로젝트 만들기

API 호출자를 구분해야 하고 호출자 중에 Google Cloud 프로젝트가 없는 경우가 있으면 각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들 수 있습니다. 프로젝트를 만들기 전에 프로젝트와 연결된 호출자를 손쉽게 식별할 수 있도록 프로젝트 이름을 생각해 둡니다.

예를 들어 외부 API 고객이 있고, API를 호출하는 클라이언트 프로그램이 어떻게 만들어졌는지 모르는 경우를 가정해 보겠습니다. Google Cloud 서비스를 사용하고 Google Cloud 프로젝트가 있는 클라이언트도 있고 그렇지 않은 클라이언트도 있습니다. 호출자를 구분하려면 각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들어야 합니다.

각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들려면 다음 안내를 따르세요.

각 호출자별로 별도의 프로젝트를 만듭니다.
각 프로젝트에서 API를 사용 설정하고 API 키를 만듭니다.
각 호출자에게 API 키를 제공합니다.

각 호출자별 API 키 만들기

API 호출자를 구분할 필요가 없지만 API 키 제한사항을 추가하려는 경우, 동일 프로젝트에서 각 호출자에 대해 별도의 API 키를 만들 수 있습니다.

동일한 프로젝트 내 각 호출자별로 API 키를 만들려면 다음 안내를 따르세요.

API가 구성된 프로젝트 또는 API가 사용 설정된 프로젝트에서 필요한 API 키 제한이 있는 각 고객의 API 키를 만듭니다.
각 호출자에게 API 키를 제공합니다.

모든 호출자를 위한 하나의 API 키 만들기

API 호출자를 구분할 필요가 없고 API 제한사항을 추가할 필요가 없지만 API 키가 여전히 필요한 경우(예: 익명 액세스 방지), 모든 호출자가 사용할 하나의 API 키를 만들 수 있습니다.

모든 호출자를 위한 하나의 API 키를 만들려면 다음 안내를 따르세요.

API가 구성된 프로젝트 또는 API가 사용 설정된 프로젝트에서 모든 호출자를 위한 API 키를 만듭니다.
모든 호출자에게 동일한 API 키를 제공합니다.

다음 단계

API 키 보호