기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
API Gateway에서 메서드 요청 설정
메서드 요청을 설정하려면 RestApi리소스를 생성한 후 다음 작업을 수행해야 합니다.
다음 메서드를 사용하여 이 작업을 수행할 수 있습니다.
-
AWS CLI 명령 (리소스 생성 및 풋 메소드)
-
AWS SDK 함수 (예: Node.js, CreateResource 및 PutMethod)
-
API Gateway REST API(resource:create 및 method:put).
이러한 도구의 사용 예시는 API Gateway에서 REST API 설정 초기화를 참조하십시오.
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}us-east-1)을 나타냅니다. 사용자 지정 도메인 이름은 유효한 인터넷 도메인에 속한, 사용자에게 친숙한 이름입니다. 예를 들어 example.com의 인터넷 도메인을 등록하였다면 모든 *.example.com은 유효한 사용자 지정 도메인 이름입니다. 자세한 내용은 사용자 지정 도메인 이름 생성 단원을 참조하십시오.
PetStore 샘플 API의 경우 루트 리소스 (/) 는 펫 스토어를 노출합니다. /pets 리소스는 반려 동물 스토어에서 사용 가능한 반려 동물 모음을 나타냅니다. /pets/{petId}는 특정 식별자(petId)의 개별 반려 동물을 공개합니다. {petId}의 경로 파라미터는 요청 파라미터의 일부입니다.
API 리소스를 설정하려면 기존 리소스를 상위 리소스로 선택한 후 이 상위 리소스 아래에 하위 리소스를 생성합니다. 상위 리소스인 루트 리소스로 시작하여 이 상위 리소스에 리소스를 추가하고 이 하위 리소스에 또 다른 리소스를 새로운 상위 리소스로 추가하는 등의 작업을 상위 식별자에 이르기까지 수행합니다. 그 다음에 이름이 지정된 리소스를 상위 리소스에 추가합니다.
를 사용하면 get-resources 명령을 호출하여 API의 어떤 리소스를 사용할 수 있는지 확인할 수 있습니다. AWS CLI
aws apigateway get-resources --rest-api-id<apiId>\ --region<region>
그 결과 현재 사용 가능한 API 리소스의 목록을 얻을 수 있습니다. 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>\ --region<region>\ --parent-id<parentId>\ --path-part<resourceName>
예를 들어 PetStore 웹 사이트에 판매용 애완동물 사료를 추가하려면 food to와 parent-id to를 설정하여 루트 (/) path-part 에 food 리소스를 추가합니다svzr2028x8. 그 결과는 다음과 같습니다.
{ "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/*의 경로 패턴과 일치하는 모든 리소스를 나타냅니다. 복잡한 경로 변수 이름인 proxy는 일반 경로 파라미터 이름을 처리할 때와 같은 방식으로 다른 문자열로 대체할 수 있습니다.
를 사용하여 다음 AWS CLI명령을 호출하여 루트 () /{proxy+} 아래에 프록시 리소스를 설정합니다.
aws apigateway create-resource --rest-api-id<apiId>\ --region<region>\ --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}, 등과 같은 다른 (기존 또는 to-be-added/food/{type}/{subtype}/{item}) 리소스를 참조할 수도 있습니다. /toys/{type}/{subtype}/{item} 백엔드 개발자는 리소스 계층을 결정하고 클라이언트 개발자는 이를 이해할 책임이 있습니다. API Gateway는 클라이언트가 제출한 것은 무엇이든 백엔드에 전달할 뿐입니다.
API에는 프록시 리소스가 둘 이상 있을 수 있습니다. 예를 들어 다음 프록시 리소스는 API 내에서 허용됩니다.
/{proxy+} /parent/{proxy+} /parent/{child}/{proxy+}
프록시 리소스에 비 프록시 형제 리소스가 있는 경우 형제 리소스는 프록시 리소스의 표시에서 제외됩니다. 앞 예제의 경우, /{proxy+}는 /parent[/*] 리소스를 제외한 루트 리소스 아래의 모든 리소스를 가리킵니다. 즉 동일한 리소스 계층 수준에서는 특정 리소스에 대한 메서드 요청이 일반 리소스에 대한 메서드 요청에 우선합니다.
프록시 리소스에는 하위 리소스가 전혀 없을 수 있습니다. {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로 설정합니다.
다음 AWS CLI 명령은 IAM 권한을 사용하여 액세스를 제어하여 지정된 리소스 (6sxz2j) 에 대해 ANY 동사의 메서드 요청을 생성하는 방법을 보여줍니다.
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM \ --region us-west-2
다른 권한 부여 유영으로 API 메서드 요청을 생성하려면 메서드 요청 권한 부여 설정을 참조하십시오.
메서드 요청 파라미터 설정
메서드 요청 파라미터는 클라이언트가 메서드 요청을 완료하는 데 필요한 입력 데이터 또는 실행 컨텍스트를 제공하는 방식입니다. 메서드 파라미터는 경로 파라미터, 헤더 또는 쿼리 문자열 파라미터일 수 있습니다. 메서드 요청을 설정하는 과정에서 필수 요청 파라미터를 선언하여 클라이언트가 사용할 수 있게 해야 합니다. 비 프록시 통합의 경우 이러한 요청 파라미터를 백엔드 요구 사항과 호환되는 형식으로 변환할 수 있습니다.
예를 들어 GET /pets/{petId} 메서드 요청의 경우 {petId} 경로 변수는 필수 요청 파라미터입니다. AWS CLI의 put-method 명령을 호출할 때 이 경로 파라미터를 선언할 수 있습니다. 이를 코드로 나타내면 다음과 같습니다.
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --region us-west-2 \ --request-parameters method.request.path.petId=true
파라미터가 필요하지 않은 경우 false에서 request-parameters로 설정할 수 있습니다. 예를 들어 GET /pets 메서드가 type의 선택적 쿼리 문자열 파라미터와 breed의 선택적 헤더 파라미터를 사용하는 경우 /pets 리소스 id가 6sxz2j라는 가정 하에 다음과 같은 CLI 명령을 사용하여 두 파라미터를 선언할 수 있습니다.
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --region us-west-2 \ --request-parameters method.request.querystring.type=false,method.request.header.breed=false
이처럼 축약된 형식 대신에 다음과 같이 JSON 문자열을 사용하여 request-parameters 값을 설정할 수 있습니다.
'{"method.request.querystring.type":false,"method.request.header.breed":false}'
클라이언트는 이 설정을 사용하여 반려 동물을 유형별로 쿼리할 수 있습니다.
GET /pets?type=dog
또한 클라이언트는 다음과 같이 푸들 종의 개를 쿼리할 수 있습니다.
GET /pets?type=dog breed:poodle
메서드 요청 파리미터를 통합 요청 파라미터로 매핑하는 방법에 대한 자세한 내용은 REST API 통합 설정를 참조하십시오.
메서드 요청 모델 설정
페이로드로 입력 데이터를 받아들일 수 있는 API 메서드의 경우에는 모델을 사용할 수 있습니다. 모델은 JSON 스키마 draft 4
콘텐츠 유형에 따라 메서드 페이로드에는 다양한 형식이 있을 수 있습니다. 모델은 적용된 페이로드의 미디어 유형에 대해 인덱싱됩니다. API Gateway는 Content-Type 요청 헤더를 사용하여 콘텐츠 유형을 결정합니다. 메서드 요청 모델을 설정하려면 명령을 호출할 때 해당 " 형식의 키-값 쌍을 <media-type>":"<model-name>"requestModels 맵에 추가하십시오. AWS CLI put-method
콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 $default을(를) 키로 지정합니다.
예를 들어, PetStore 예제 API의 POST /pets 메서드 요청의 JSON 페이로드에 모델을 설정하려면 다음 명령을 호출하면 됩니다. AWS CLI
aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --region us-west-2 \ --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 권한을 사용하여 API에 대한 액세스 제어 섹션을 참조하세요.
현재는 API 소유자 AWS 계정내의 사용자, 그룹 및 역할에만 이 정책을 부여할 수 있습니다. 작업을 호출하는 데 필요한 권한을 AWS 계정 가진 API 소유자 내에서 역할을 맡을 AWS 계정 수 있는 경우에만 다른 사용자가 API 메서드를 호출할 수 있습니다. execute-api:Invoke 교차 계정 권한에 대한 자세한 내용은 IAM 역할 사용 단원을 참조하세요.
서명 버전 4 서명을 구현하는 Postman과
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 메서드 요청을 설정할 때 요청 검증을 활성화할 수 있습니다. 먼저 다음과 같이 요청 검사기를 생성해야 합니다.
aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters
이 CLI 명령은 본문 전용 요청 검사기를 생성합니다. 예제 출력 내용은 다음과 같습니다.
{ "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" }
이 요청 검사기를 통해 다음과 같이 요청 검증을 메서드 요청 설정의 일부로 활성화할 수 있습니다.
aws apigateway put-method \ --rest-api-id 7zw9uyk9kl --region us-west-2 --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
요청 파라미터는 요청 검증에 포함되려면 필수로 선언되어야 합니다. 해당 페이지에 대한 쿼리 문자열 파라미터가 요청 검증에 사용되는 경우 이전 예제의 request-parameters 맵은 '{"method.request.querystring.type": false,
"method.request.querystring.page":true}'로 지정되어야 합니다.
