데코레이터

Python용 Cloud Endpoints Frameworks 데코레이터는 API 구성, 메서드, 매개변수, Endpoints의 속성과 동작을 정의하는 기타 중요한 세부정보를 설명합니다.

이 페이지에서는 사용 가능한 데코레이터를 자세히 설명합니다. 데코레이터를 사용하여 API를 만드는 방법에 대한 자세한 내용은 다음을 참조하세요.

• API 만들기
• 여러 클래스로 구현된 API 만들기

API 정의하기(@endpoints.api)

API를 정의하기 위해 @endpoints.api에 여러 인수를 제공할 수 있습니다. 사용 가능한 인수는 다음 표와 같습니다.

limit_definitions

API의 할당량을 정의하려면 선택사항인 limit_definitions 인수를 @endpoints.api에 지정합니다. 할당량을 구성하려면 다음을 수행해야 합니다.

• 버전 2.4.5 이상의 Endpoints Frameworks 라이브러리를 설치합니다.
• 할당량을 적용하고자 하는 각 메서드의 메서드 데코레이터에 metric_costs 인수를 추가합니다.

할당량 설정에 필요한 모든 단계는 할당량 구성을 참조하세요.

하나 이상의 LimitDefinition 인스턴스 목록을 다음과 같이 지정합니다.

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

각 LimitDefinition 인스턴스에는 다음 값이 필요합니다.

예

quota_limits = [
  endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),
  endpoints.LimitDefinition('list-requests', 'List Requests', 100),
  endpoints.LimitDefinition('write-requests', 'Write Requests', 50)
]

@endpoints.api(name='bookstore',
               version='v1',
               limit_definitions=quota_limits)

허용되는 클라이언트 ID 및 대상

OAuth2 인증의 경우 특정 클라이언트 ID에 OAuth2 토큰이 발급되어, 이 클라이언트 ID를 통해 API에 대한 액세스를 제한할 수 있습니다. Google Cloud 콘솔에서 Android 애플리케이션을 등록할 때 이에 대한 클라이언트 ID를 만듭니다. 이 클라이언트 ID가 인증을 위해 Google로부터 OAuth2 토큰을 요청하는 ID입니다. 백엔드 API가 인증으로 보호되면 OAuth2 액세스 토큰이 전송되어 App Engine용 Cloud Endpoints Frameworks에서 열리고, 토큰에서 클라이언트 ID가 추출된 다음 백엔드의 선언된 허용 가능 클라이언트 ID 목록(allowed_client_ids 목록)과 비교됩니다.

allowed_client_ids 목록은 웹, Android, 기타 클라이언트 앱에 대해 Google Cloud 콘솔을 통해 얻은 모든 클라이언트 ID로 구성됩니다. 즉, API 빌드 시 클라이언트가 알려져 있어야 합니다. 빈 목록을 지정하면 클라이언트가 절대 API에 액세스할 수 없습니다.

올바른 인증을 확인하고자 하는 각 API 메서드에서 endpoints.get_current_user()를 호출해야 합니다. 자세한 내용은 사용자 인증을 참조하세요.

allowed_client_ids 인수를 사용하며, API 탐색기를 사용하여 API에 대한 인증된 호출을 테스트하려는 경우에는 상수 endpoints.API_EXPLORER_CLIENT_ID를 지정하여 allowed_client_ids 목록으로 클라이언트 ID를 제공해야 합니다. allowed_client_ids에 endpoints.API_EXPLORER_CLIENT_ID만 포함된 경우 API를 배포하면 API를 공개적으로 검색할 수 있으며 API 탐색기에서 공개적으로 액세스할 수 있습니다.

대상 정보

allowed_client_ids 목록은 승인되지 않은 클라이언트로부터 백엔드 API를 보호합니다. 그러나 원하는 백엔드 API에만 인증 토큰이 작동하도록 클라이언트를 보호하기 위해서는 추가적인 보호 조치가 필요합니다. Android 클라이언트의 경우 이 메커니즘은 audiences 인수로, 여기에서 백엔드 API의 클라이언트 ID를 지정합니다.

Google Cloud 콘솔 프로젝트를 만들 때 기본 클라이언트 ID가 자동으로 생성되고 프로젝트에서 사용할 수 있도록 이름이 지정됩니다. App Engine에 백엔드 API를 업로드하면 해당 클라이언트 ID가 사용됩니다. 이는 API 인증에 언급된 웹 클라이언트 ID입니다.

제3자 인증 토큰 발급기관

Google ID 토큰이 아닌 제3자 발급기관에서 발급한 인증 토큰을 애플리케이션에서 허용하는 경우에는 @endpoints.api에서 audiences와 issuers 인수를 제3자 발급기관에 대한 정보를 제공할 수 있도록 설정해야 합니다. 예를 들면 다음과 같습니다.

@endpoints.api(
        audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
        issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
                                           'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):

API 메서드 정의하기(@endpoints.method)

전체 API의 경우 @endpoints.api를, 메서드의 경우 @endpoints.method를 사용하여 audiences, scopes, allowed_client_ids 설정을 지정할 수 있습니다. API와 메서드 레벨 모두에 이러한 설정을 지정하는 경우 메서드 설정이 우선합니다.

API에서 메서드를 만들려면 해당 Python 메서드를 @endpoints.method로 데코레이션하여 메서드의 사용을 구성하는 인수를 제공합니다. 예를 들어 사용할 요청 및 응답 Message 클래스를 지정합니다.

사용 가능한 인수는 다음 표와 같습니다.

경로 또는 쿼리 문자열 인수에 ResourceContainer 사용

요청에 경로 또는 쿼리 문자열 인수가 포함된 경우에는 API 작성에 설명된 간단한 Message 클래스를 사용할 수 없습니다. 대신 다음과 같이 ResourceContainer 클래스를 사용해야 합니다.

1. 요청 본문을 통해 전달되는 모든 인수가 들어 있는 Message 클래스를 정의합니다. 요청 본문에 인수가 없는 경우에는 Message 클래스를 정의할 필요 없이 그냥 message_types.VoidMessage을 사용하면 됩니다. 예를 들면 다음과 같습니다.

   class Greeting(messages.Message):
       """Greeting that stores a message."""
   
       message = messages.StringField(1)

2. ResourceContainer을, 이전 단계에서 첫 번째 매개변수로 정의한 Message 클래스로 정의합니다. 다음 매개변수에서 경로 및 쿼리 문자열 인수를 지정합니다. 예를 들면 다음과 같습니다.

   MULTIPLY_RESOURCE = endpoints.ResourceContainer(
       Greeting,
       times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),

   여기서 첫 번째 인수는 요청 본문의 데이터에 대한 Message 클래스이고, times는 요청에 수반되는 경로 또는 쿼리 문자열에 예상되는 숫자입니다.

3. 해당 위치에 제공되었을 요청 Message 클래스를 대체하는 첫 번째 매개변수에서, 요청을 처리하는 메서드에 ResourceContainer를 제공합니다. 다음 스니펫에서 ResourceContainer와 endpoints.method를 둘 다 확인할 수 있습니다.

   # This ResourceContainer is similar to the one used for get_greeting, but
   # this one also contains a request body in the form of a Greeting message.
   MULTIPLY_RESOURCE = endpoints.ResourceContainer(
       Greeting,
       times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
   )
   
   @endpoints.method(
       # This method accepts a request body containing a Greeting message
       # and a URL parameter specifying how many times to multiply the
       # message.
       MULTIPLY_RESOURCE,
       # This method returns a Greeting message.
       Greeting,
       path="greetings/multiply/{times}",
       http_method="POST",
       name="greetings.multiply",
   )
   def multiply_greeting(self, request):
       return Greeting(message=request.message * request.times)
   

4. 표시된 것과 같이 path 매개변수를 추가하여 API를 포함시킵니다.

5. ResourceContainer에 필수 인수가 있으면, 클라이언트 요청의 쿼리 문자열(예: yourApi?times=2) 또는 URL 경로(예: yourApi/2)에 이 인수가 포함되어 있어야 합니다. 하지만 API가 URL 경로를 사용하여 인수 값을 수신하려면 path='yourApi/{times}의 {times} 인수에 대해 표시된 대로 API 경로에 인수 이름을 또한 추가해야 합니다.

다음 단계

• API 만들기
• 여러 클래스로 구현된 API 만들기