API Gateway에서 메서드 요청 설정

메서드 요청을 설정하는 작업에는 RestApi 리소스 생성 후 다음과 같은 작업이 수반됩니다.

다음 메서드를 사용하여 이 작업을 수행할 수 있습니다.

API 리소스 설정

API Gateway API에서 계층 꼭대기에 있는 루트 리소스(/)와 함께 주소 지정 가능 리소스를 API 리소스 엔터티의 트리로 노출합니다. 루트 리소스는 API 엔드포인트 및 단계 이름으로 구성된 API의 기본 URL에 상대적입니다. API Gateway 콘솔에서 이 기본 URI는 URI 호출(Invoke URI)로 참조되고 API가 배포된 후에 API의 단계 편집기에 표시됩니다.

API 엔드포인트는 기본 호스트 이름 또는 사용자 지정 도메인 이름일 수 있습니다. 기본 호스트 이름은 다음 형식으로 되어 있습니다.

{api-id}.execute-api.{region}.amazonaws.com

이 형식에서 {api-id}는 API Gateway가 생성하는 API 식별자를 나타냅니다. {region} 변수는 API를 생성할 때 선택한 AWS 리전(예: us-east-1)을 나타냅니다. 사용자 지정 도메인 이름은 유효한 인터넷 도메인에 속한, 사용자에게 친숙한 이름입니다. 예를 들어 example.com의 인터넷 도메인을 등록하였다면 모든 *.example.com은 유효한 사용자 지정 도메인 이름입니다. 자세한 내용은 사용자 지정 도메인 이름 생성 단원을 참조하십시오.

PetStore 샘플 API의 경우, 루트 리소스(/)는 해당 반려 동물 스토어를 공개합니다. /pets 리소스는 반려 동물 스토어에서 사용 가능한 반려 동물 모음을 나타냅니다. /pets/{petId}는 특정 식별자(petId)의 개별 반려 동물을 공개합니다. {petId}의 경로 파라미터는 요청 파라미터의 일부입니다.

API 리소스를 설정하려면 기존 리소스를 상위 리소스로 선택한 후 이 상위 리소스 아래에 하위 리소스를 생성합니다. 상위 리소스인 루트 리소스로 시작하여 이 상위 리소스에 리소스를 추가하고 이 하위 리소스에 또 다른 리소스를 새로운 상위 리소스로 추가하는 등의 작업을 상위 식별자에 이르기까지 수행합니다. 그 다음에 이름이 지정된 리소스를 상위 리소스에 추가합니다.

다음 get-resources 명령은 API의 모든 리소스를 검색합니다.

aws apigateway get-resources --rest-api-id apiId

PetStore 샘플 API의 경우 출력은 다음과 같습니다.

{
    "items": [
        {
            "path": "/pets", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "6sxz2j", 
            "pathPart": "pets", 
            "parentId": "svzr2028x8"
        }, 
        {
            "path": "/pets/{petId}", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "rjkmth", 
            "pathPart": "{petId}", 
            "parentId": "6sxz2j"
        }, 
        {
            "path": "/", 
            "id": "svzr2028x8"
        }
    ]
}

각 항목은 리소스의 식별자(id)와 루트 리소스를 제외한 바로 위에 있는 상위 리소스(parentId)뿐 아니라 리소스 이름(pathPart)도 나열합니다. 루트 리소스는 상위 리소스가 없다는 점에서 특별합니다. 리소스를 상위 리소스로 선택한 후에 다음 명령을 사용하여 하위 리소스를 추가합니다.

aws apigateway create-resource --rest-api-id apiId \
    --parent-id parentId \
    --path-part resourceName

예를 들어 PetStore 웹 사이트에서 판매할 반려동물 식품을 추가하려면 다음 명령을 사용합니다.

aws apigateway create-resource --rest-api-id a1b2c3 \
    --parent-id svzr2028x8 \
    --path-part food

출력은 다음과 같습니다.

{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}

프록시 리소스를 사용하여 API 설정 간소화

비즈니스가 성장함에 딸 PetStore 소유주는 판매용으로 음식, 장난감, 기타 반려 동물 관련 항목을 추가하기로 결정할 수 있습니다. 이를 지원하기 위해 루트 리소스 아래에 /food, /toys 및 기타 리소스를 추가할 수 있습니다. 각 판매 범주에 /food/{type}/{item}, /toys/{type}/{item} 등 더 많은 리소스를 추가하고 싶을 수도 있습니다. 이는 번거로운 일일 수 있습니다. 리소스 경로에 중간 계층 {subtype}을 추가하여 경로 계층을 /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item} 등으로 변경하기로 한 경우, 그러한 변경으로 인해 기존 API 설정이 손상됩니다. 이를 방지하기 위해 API Gateway 프록시 리소스를 사용하여 한꺼번에 일련의 API 리소스를 공개할 수 있습니다.

API Gateway는 프록시 리소스를 해당 요청을 제출할 때 지정할 리소스의 자리 표시자로 정의합니다. 프록시 리소스는 복잡한 경로 파라미터로 자주 참조되는 {proxy+}의 특별 경로 파라미터로 표시됩니다. + 기호는 어떤 하위 리소스이든지 거기에 추가된 것을 나타냅니다. /parent/{proxy+} 자리 표시자는 /parent/*의 경로 패턴과 일치하는 모든 리소스를 나타냅니다. 최적의 경로 파라미터 이름에 어떤 문자열이든 사용할 수 있습니다.

다음 create-resource 명령은 루트(/{proxy+}) 아래에 프록시 리소스를 생성합니다.

aws apigateway create-resource --rest-api-id apiId \
    --parent-id rootResourceId \
    --path-part {proxy+}

출력은 다음과 같습니다.

{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}

PetStore API의 예를 들면, /{proxy+}를 사용하여 /pets 및 /pets/{petId}를 모두 나타낼 수 있습니다. 이 프록시 리소스는 /food/{type}/{item}, /toys/{type}/{item}, 또는 /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item} 등 다른(기존 또는 추가될) 리소스를 참조할 수도 있습니다. 백엔드 개발자는 리소스 계층을 결정하고 클라이언트 개발자는 이를 이해할 책임이 있습니다. API Gateway는 클라이언트가 제출한 것은 무엇이든 백엔드에 전달할 뿐입니다.

API에는 프록시 리소스가 둘 이상 있을 수 있습니다. 예를 들어, /parent/{proxy+}가 /parent/{child}/{proxy+}와 동일한 상위 항목이 아니라고 가정할 때 API 내에서 다음 프록시 리소스가 허용됩니다.

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

프록시 리소스에 비 프록시 형제 리소스가 있는 경우 형제 리소스는 프록시 리소스의 표시에서 제외됩니다. 앞 예제의 경우, /{proxy+}는 /parent[/*] 리소스를 제외한 루트 리소스 아래의 모든 리소스를 가리킵니다. 즉 동일한 리소스 계층 수준에서는 특정 리소스에 대한 메서드 요청이 일반 리소스에 대한 메서드 요청에 우선합니다.

다음 표는 API Gateway가 API prod 스테이지에 대한 요청을 다음 리소스로 라우팅하는 방법을 보여줍니다.

ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog

프록시 리소스에는 하위 리소스가 전혀 없을 수 있습니다. {proxy+} 뒤의 모든 API 리소스는 중복되며 의미가 명확하지 않습니다. 다음 프록시 리소스는 API 내에서 허용되지 않습니다.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

HTTP 메서드 설정

API 메서드 요청은 API Gateway Method 리소스로 캡슐화됩니다. 메서드 요청을 설정하려면 먼저 Method 리소스를 인스턴스화하여 HTTP 메서드를 최소 한 개 설정하고 그 메서드에 권한 부여 유형을 설정해야 합니다.

프록시 리소스와 긴밀히 연결된 API Gateway는 ANY의 HTTP 메서드를 지원합니다. 이 ANY 메서드는 실행 시간에 제공될 모든 HTTP 메서드를 나타냅니다. 이를 통해 DELETE, GET, HEAD, OPTIONS, PATCH, POST 및 PUT의 모든 지원되는 HTTP 메서드에 대해 단일 API 메서드 설정을 사용할 수 있습니다.

비 프록시 리소스에서도 ANY 메서드를 설정할 수 있습니다. ANY 메서드를 프록시 리소스와 결합하여 API의 모든 리소스에 대해 지원되는 모든 HTTP 메서드에 대한 단일 API 메서드 설정을 가져옵니다. 뿐만 아니라 백엔드는 기존 API 설정을 손상하지 않고도 발전할 수 있습니다.

API 메서드를 설정하기 전에 누가 메서드를 호출할 수 있는지 고려합니다. 계획에 따라 권한 부여 유형을 설정합니다. 오픈 액세스의 경우 그 유형을 NONE으로 설정합니다. IAM 권한을 사용하려면 권한 부여 유형을 AWS_IAM으로 설정합니다. Lambda 권한 부여자 함수를 사용하려면 이 속성을 CUSTOM으로 설정합니다. Amazon Cognito 사용자 풀을 사용하려면 권한 부여 유형을 COGNITO_USER_POOLS로 설정합니다.

다음 put-method 명령은 IAM 권한을 사용하여 ANY 구문에 대한 메서드 요청을 생성하여 액세스를 제어합니다.

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method ANY \
    --authorization-type AWS_IAM

다른 권한 부여 유영으로 API 메서드 요청을 생성하려면 메서드 요청 권한 부여 설정을 참조하십시오.

메서드 요청 파라미터 설정

메서드 요청 파라미터는 클라이언트가 메서드 요청을 완료하는 데 필요한 입력 데이터 또는 실행 컨텍스트를 제공하는 방식입니다. 메서드 파라미터는 경로 파라미터, 헤더 또는 쿼리 문자열 파라미터일 수 있습니다. 메서드 요청을 설정하는 과정에서 필수 요청 파라미터를 선언하여 클라이언트가 사용할 수 있게 해야 합니다. 비 프록시 통합의 경우 이러한 요청 파라미터를 백엔드 요구 사항과 호환되는 형식으로 변환할 수 있습니다.

예를 들어 GET /pets/{petId} 메서드 요청의 경우 {petId} 경로 변수는 필수 요청 파라미터입니다. AWS CLI의 put-method 명령을 호출할 때 이 경로 파라미터를 선언할 수 있습니다. 다음 put-method 명령은 필수 경로 파라미터가 있는 메서드를 생성합니다.

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id rjkmth \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.path.petId=true

파라미터가 필요하지 않은 경우 false에서 request-parameters로 설정할 수 있습니다. 예를 들어 GET /pets 메서드가 type의 선택적 쿼리 문자열 파라미터와 age의 선택적 헤더 파라미터를 사용하는 경우 다음과 같은 put-method 명령을 사용하여 두 파라미터를 선언할 수 있습니다.

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.querystring.type=false,method.request.header.age=false

이처럼 축약된 형식 대신에 다음과 같이 JSON 문자열을 사용하여 request-parameters 값을 설정할 수 있습니다.

'{"method.request.querystring.type":false,"method.request.header.age":false}'

클라이언트는 이 설정을 사용하여 반려 동물을 유형별로 쿼리할 수 있습니다.

GET /pets?type=dog

클라이언트는 다음과 같이 puppy인 dog를 쿼리할 수 있습니다.

GET /pets?type=dog
age:puppy

메서드 요청 파리미터를 통합 요청 파라미터로 매핑하는 방법에 대한 자세한 내용은 API Gateway에서 REST API 통합를 참조하십시오.

메서드 요청 모델 설정

페이로드로 입력 데이터를 받아들일 수 있는 API 메서드의 경우에는 모델을 사용할 수 있습니다. 모델은 JSON 스키마 draft 4로 표시되고 요청 본문의 데이터 구조를 설명합니다. 클라이언트는 모델을 통해 메서드 요청 페이로드를 입력으로 구성하는 방법을 결정할 수 있습니다. 더 중요한 것은 API Gateway가 모델을 사용하여 요청의 유효성을 검증하고 SDK를 생성하며 API Gateway 콘솔에서 통합을 설정하기 위한 매핑 템플릿을 초기화한다는 것입니다. 모델을 만드는 방법에 대한 자세한 내용은 데이터 모델 이해를 참조하세요.

콘텐츠 유형에 따라 메서드 페이로드에는 다양한 형식이 있을 수 있습니다. 모델은 적용된 페이로드의 미디어 유형에 대해 인덱싱됩니다. API Gateway는 Content-Type 요청 헤더를 사용하여 콘텐츠 유형을 결정합니다. 메서드 요청 모델을 설정하려면 AWS CLIput-method 명령을 호출할 때 "media-type":"model-name" 형식의 키 값 페어를 requestModels 맵에 추가합니다.

콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 $default을(를) 키로 지정합니다.

예를 들어 PetStore 예시 API의 POST /pets 메서드 요청의 JSON 페이로드에 모델을 설정하려면 다음 put-method 명령을 사용할 수 있습니다.

aws apigateway put-method \
    --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method POST \
    --authorization-type "NONE" \
    --request-models '{"application/json":"petModel"}'

여기에서 petModel은 반려 동물을 설명하는 name 리소스의 Model 속성 값입니다. 실제 스키마 정의는 schema 리소스의 Model 속성의 JSON 문자열 값으로 표시됩니다.

API의 Java 또는 기타 강력한 형식의 SDK에서 입력 데이터는 스키마 정의에서 파생된 petModel 클래스로 캐스팅됩니다. 요청 모델을 사용하는 경우, 생성된 SDK 내 입력 데이터는 기본 Empty 모델에서 파생된 Empty 클래스로 캐스팅됩니다. 이 경우 클라이언트는 필수 입력을 제공하기 위해 정확한 데이터 클래스를 인스턴스화할 수는 없습니다.

메서드 요청 권한 부여 설정

API 메서드를 호출할 수 있는 사용자를 관리하기 위해 메서드에서 권한 부여 유형을 구성할 수 있습니다. 이 유형을 사용하여 IAM 역할과 정책(AWS_IAM), Amazon Cognito 사용자 풀(COGNITO_USER_POOLS) 또는 Lambda 권한 부여자(CUSTOM) 등 지원되는 권한 부여자 중 하나를 적용할 수 있습니다.

IAM 권한을 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 AWS_IAM에 authorization-type 입력 속성을 설정합니다. 이 옵션이 설정되면 API Gateway는 호출자의 보안 인증 정보를 바탕으로 요청에 대한 호출자의 서명을 확인합니다. 확인된 사용자에게 메서드를 호출할 수 있는 권한이 있는 경우 그 요청은 수락됩니다. 그렇지 않다면 요청은 거부되고 호출자는 인증되지 않은 오류 응답을 받습니다. 호출자에게 API 메서드를 호출할 권한이 없는 한 메서드 호출은 성공하지 못합니다. 다음 IAM 정책은 호출자에게 동일한 AWS 계정에서 생성된 모든 API 메서드를 호출할 수 있는 권한을 부여합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

자세한 내용은 IAM 권한을 사용하여 REST API에 대한 액세스 제어 단원을 참조하십시오.

현재는 API 소유자 AWS 계정 내의 사용자, 그룹 및 역할에만 이 정책을 부여할 수 있습니다. 다른 AWS 계정의 사용자는 execute-api:Invoke 작업을 호출하는 데 필요한 권한이 있는 역할을 API 소유자의 AWS 계정 내에서 수임하도록 허용된 경우에만 API 메서드를 호출할 수 있습니다. 교차 계정 권한에 대한 자세한 내용은 IAM 역할 사용 단원을 참조하세요.

AWS CLI, AWS SDK 또는 Signature Version 4(SigV4) 서명을 구현하는 Postman과 같은 REST API 클라이언트를 사용할 수 있습니다.

Lambda 권한 부여자를 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 CUSTOM에 authorization-type 입력 속성을 설정하고 이미 존재하는 Lambda 권한 부여자의 id 속성 값에 authorizer-id 입력 속성을 설정합니다. 참조된 Lambda 권한 부여자는 TOKEN 또는 REQUEST 유형일 수 있습니다. Lambda 권한 부여자를 생성하는 방법은 API Gateway Lambda 권한 부여자 사용 단원을 참조하세요.

Amazon Cognito 사용자 풀을 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 COGNITO_USER_POOLS에 authorization-type 입력 속성을 설정하고 이미 생성된 COGNITO_USER_POOLS 권한 부여자의 id 속성 값에 authorizer-id 입력 속성을 설정합니다. Amazon Cognito 사용자 풀 권한 부여자 생성에 대한 자세한 내용은 Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어 단원을 참조하세요.

메서드 요청 검증 설정

API 메서드 요청을 설정할 때 요청 검증을 활성화할 수 있습니다. 먼저 다음과 같이 요청 검사기를 생성해야 합니다. 다음 create-request-validator 명령은 본문 전용 요청 검사기를 생성합니다.

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

출력은 다음과 같습니다.

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

이 요청 검사기를 통해 요청 검증을 메서드 요청 설정의 일부로 사용할 수 있습니다. 다음 put-method 명령은 수신 요청 본문이 PetModel과 일치해야 하는 메서드 요청을 생성하고 필요하지 않은 요청 파라미터가 두 개 있습니다.

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl \
    --resource-id xdsvhp \
    --http-method PUT \
    --authorization-type "NONE" \
    --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ 
    --request-models '{"application/json":"petModel"}' \
    --request-validator-id jgpyy6

요청 검증에 요청 파라미터를 포함하려면 요청 검사기에 대해 validateRequestParameters를 true로 설정하고 put-method 명령에서 특정 요청 파라미터를 true로 설정해야 합니다.