자습서: HTTP 비 프록시 통합을 사용하여 REST API 빌드

이 자습서에서는 Amazon API Gateway 콘솔을 사용하여 API를 완전히 새로 생성합니다. 콘솔을 API 설계 스튜디오로 간주해 이를 사용하여 API 기능의 범위를 정하고, 동작을 시험하고, API를 구축하고, 단계별로 API를 배포합니다.

HTTP 사용자 지정 통합을 사용하여 API 만들기

이 단원에서는 리소스 생성, 리소스에서 메서드 노출, 원하는 API 동작을 위한 메서드 구성, API 테스트 및 배포 등을 단계별로 살펴봅니다.

이 단계에서는 빈 API를 생성합니다. 다음 단계에서는 비프록시 HTTP 통합을 사용하여 API를 http://petstore-demo-endpoint.execute-api.com/petstore/pets 엔드포인트에 연결하는 리소스와 메서드를 생성합니다.

API를 생성하는 방법

1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

2. API Gateway를 처음 사용하는 경우, 서비스의 기능을 소개하는 페이지가 나타납니다. REST API에서 빌드를 선택합니다. 예제 API 생성 팝업이 나타나면 확인을 선택합니다.

   API Gateway를 처음 사용하는 것이 아닌 경우 API 생성을 선택합니다. REST API에서 빌드를 선택합니다.

3. API 이름에서 HTTPNonProxyAPI을(를) 입력합니다.

4. (선택 사항) 설명에 설명을 입력합니다.

5. API 엔드포인트 유형 설정을 지역으로 유지합니다.

6. API 생성(Create API)을 선택합니다.

리소스 트리에 메서드 없는 루트 리소스(/)가 표시됩니다. 이 연습에서는 PetStore 웹 사이트 (petstore-demo-endpointhttp://.execute-api.com/petstore/pets) 의 HTTP 사용자 지정 통합을 사용하여 API를 구축할 것입니다. 설명을 위해 루트의 자식으로 리소스를 만들고 이 /pets 리소스에 GET 메서드를 노출시켜 클라이언트가 웹 사이트에서 사용 가능한 Pets 항목 목록을 검색할 수 있도록 하겠습니다. PetStore

/pets 리소스를 생성하려면

1. / 리소스를 선택한 다음 리소스 생성을 선택합니다.

2. 프록시 리소스는 꺼진 상태로 둡니다.

3. 리소스 경로를 /로 유지합니다.

4. 리소스 이름에 pets을 입력합니다.

5. 오리진 간 리소스 공유(CORS)를 꺼진 상태로 둡니다.

6. 리소스 생성을 선택합니다.

이 단계에서는 /pets 리소스의 GET 메서드를 생성합니다. GET 메서드는 http://petstore-demo-endpoint.execute-api.com/petstore/pets 웹 사이트와 통합되어 있습니다. API 메서드의 다른 옵션에는 다음이 포함됩니다.

• POST는 주로 하위 리소스를 생성하는 데 사용됩니다.

• PUT은 주로 기존 리소스를 업데이트하는 데 사용되며, 권장되지는 않지만 하위 리소스를 생성하는 데에도 사용될 수 있습니다.

• DELETE는 리소스를 삭제하는 데 사용됩니다.

• PATCH는 리소스를 업데이트하는 데 사용됩니다.

• HEAD는 주로 시나리오를 테스트하는 데 사용됩니다. GET와 동일하지만 리소스 표현을 반환하지 않습니다.

• OPTIONS는 호출자가 타겟 서비스에 사용 가능한 통신 옵션에 대한 정보를 가져오는 데 사용할 수 있습니다.

통합 요청의 HTTP 메서드(HTTP method)에 백엔드에서 지원하는 항목을 선택해야 합니다. HTTP 또는 Mock integration의 경우, 메서드 요청과 통합 요청이 동일한 HTTP 동사를 사용하는 것이 합리적입니다. 다른 통합 유형 및 메서드 요청의 경우, 통합 요청과 다른 HTTP 동사를 사용할 가능성이 높습니다. 예를 들어 Lambda 함수를 호출하기 위해 통합 요청은 POST를 이용해 함수를 호출해야 하는 반면, 메서드 요청은 Lambda 함수의 로직에 따라 임의의 HTTP 동사를 사용할 수 있습니다.

/pets 리소스에 GET 메서드를 생성하려면

1. /pets 리소스를 선택합니다.

2. 메서드 생성을 선택합니다.

3. 메서드 유형에서 GET을 선택합니다.

4. 통합 유형에서 HTTP 통합을 선택합니다.

5. HTTP 프록시 통합을 꺼진 상태로 둡니다.

6. HTTP 메서드에서 GET을 선택합니다.

7. 엔드포인트 URL에 http://petstore-demo-endpoint.execute-api.com/petstore/pets를 입력합니다.

8. 콘텐츠 처리에서 패스스루를 선택합니다.

9. 기본 제한 시간을 켜진 상태로 둡니다.

10. 메서드 생성을 선택합니다.

PetStore 웹사이트에서는 특정 페이지에서 애완동물 유형 (예: “개” 또는 “고양이”) 별로 Pet 항목 목록을 검색할 수 있습니다. 웹사이트는 type 및 page 쿼리 문자열 파라미터를 사용해 이러한 입력을 수락합니다. 이와 같이 메서드 요청에 쿼리 문자열 파라미터를 추가하고, 통합 요청의 해당 쿼리 문자열에 매핑해야 합니다.

쿼리 문자열 파라미터를 GET 메서드에 추가하려면

1. 메서드 요청 탭의 메서드 요청 설정에서 편집을 선택합니다.

2. URL 쿼리 문자열 파라미터를 선택하고 다음을 수행합니다.

   1. 쿼리 문자열 추가(Add query string)를 선택합니다.

   2. 이름에 type을 입력합니다.

   3. 필수 상태로 유지하고 캐싱을 해제합니다.

   이전 단계를 반복하여 이름이 page인 추가 쿼리 문자열을 생성합니다.

3. 저장을 선택합니다.

이제 클라이언트는 요청을 제출할 때 반려 동물 유형과 페이지 번호를 쿼리 문자열 파라미터로 제공할 수 있습니다. 입력 값을 백엔드의 당사 PetStore 웹 사이트에 전달하려면 이러한 입력 매개변수를 통합의 쿼리 문자열 매개변수에 매핑해야 합니다.

입력 파라미터를 통합 요청에 매핑하려면

1. 통합 요청 탭의 통합 요청 설정에서 편집을 선택합니다.

2. URL 쿼리 문자열 파라미터를 선택하고 다음을 수행합니다.

   1. 쿼리 문자열 파라미터 추가를 선택합니다.

   2. 이름에 type를 입력합니다.

   3. 다음에서 매핑됨에 method.request.querystring.type을 입력합니다.

   4. 캐싱을 꺼진 상태로 둡니다.

   5. 쿼리 문자열 파라미터 추가를 선택합니다.

   6. 이름에 page를 입력합니다.

   7. 다음에서 매핑됨에 method.request.querystring.page을 입력합니다.

   8. 캐싱을 꺼진 상태로 둡니다.

3. 저장을 선택합니다.

API를 테스트하려면

1. 테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

2. 쿼리 문자열에 type=Dog&page=2를 입력합니다.

3. 테스트를 선택합니다.

   그 결과는 다음과 비슷합니다.

   

   테스트에 성공했으므로, API를 배포해 공개적으로 사용 가능하도록 할 수 있습니다.

4. Deploy API(API 배포)를 선택합니다.

5. 스테이지에서 새 스테이지를 선택합니다.

6. 단계 이름에 Prod를 입력합니다.

7. (선택 사항) 설명에 설명을 입력합니다.

8. 배포를 선택합니다.

9. (선택 사항) 스테이지 세부 정보의 URL 호출에서 복사 아이콘을 선택하여 API의 호출 URL을 복사합니다. 이 URL을 Postman 및 cURL과 같은 도구에서 사용하여 API를 테스트할 수 있습니다.

SDK를 이용해 클라이언트를 생성하면 SDK가 공개한 메서드를 호출하여 요청을 보낼 수 있습니다. 구현 세부 정보는 선택한 AWS SDK를 참조하세요.

참고

API가 변경되면 API를 다시 배포하여 새 기능 또는 업데이트된 기능을 사용할 수 있도록 한 후 요청 URL을 다시 호출해야 합니다.

(선택 사항) 요청 파라미터 매핑

API Gateway API에 대한 요청 파라미터 매핑

이 자습서에서는 항목 ID를 지정하고, 이를 통합 요청 URL의 {petId} 경로 파라미터에 매핑하고, 요청을 HTTP 엔드포인트로 보내기 위해 API의 메서드 요청 URL에서 {id}의 경로 파라미터를 생성하는 방법을 보여줍니다.

참고

대문자 대신 소문자를 입력하거나 그 반대로 입력하면 연습 뒷부분에서 오류가 발생할 수 있습니다.

1단계: 리소스 생성

이 단계에서는 경로 파라미터 {petid}를 사용하여 리소스를 생성합니다.

{petId} 리소스를 생성하려면

1. /pets 리소스를 선택한 다음 리소스 생성을 선택합니다.

2. 프록시 리소스는 꺼진 상태로 둡니다.

3. 리소스 경로에서 /pets/를 선택합니다.

4. 리소스 이름에 {petId}을 입력합니다.

   /pets/{petId}가 표시되도록 petId에 중괄호({ })를 사용합니다.

5. 오리진 간 리소스 공유(CORS)를 꺼진 상태로 둡니다.

6. 리소스 생성을 선택합니다.

2단계: 메서드 생성 및 테스트

이 단계에서는 {petId} 경로 파라미터를 사용하여 GET 메서드를 생성합니다.

GET 메서드를 설정하려면

1. /{petId} 리소스를 선택한 다음 메서드 생성을 선택합니다.

2. 메서드 유형에서 GET을 선택합니다.

3. 통합 유형에서 HTTP 통합을 선택합니다.

4. HTTP 프록시 통합을 꺼진 상태로 둡니다.

5. HTTP 메서드에서 GET을 선택합니다.

6. 엔드포인트 URL에 http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}를 입력합니다.

7. 콘텐츠 처리에서 패스스루를 선택합니다.

8. 기본 제한 시간을 켜진 상태로 둡니다.

9. 메서드 생성을 선택합니다.

이제 {petId} 경로 파라미터를 HTTP 엔드포인트의 {id} 경로 파라미터에 매핑합니다.

{petId} 경로 파라미터를 매핑하려면

1. 통합 요청 탭의 통합 요청 설정에서 편집을 선택합니다.

2. URL 경로 파라미터를 선택합니다.

3. API Gateway는 통합 요청에 대해 petId라는 경로 파라미터를 생성합니다. 이는 백엔드에서는 작동하지 않습니다. HTTP 엔드포인트는 경로 파라미터로 {id}를 사용합니다. petId의 이름을 id로 변경합니다.

   그렇게 하면 petId의 메서드 요청 경로 파리미터가 id의 통합 요청 경로 파라미터로 매핑됩니다.

4. 저장을 선택합니다.

이제 메서드를 테스트합니다.

 메서드를 테스트하는 방법

1. 테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

2. petId의 경로에 4를 입력합니다.

3. 테스트를 선택합니다.

   올바르게 수행했다면 응답 본문에 다음이 표시됩니다.

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

3단계: API 배포

이 단계에서는 API를 API Gateway 콘솔 외부에서 호출을 시작할 수 있도록 배포합니다.

API를 배포하려면

1. Deploy API(API 배포)를 선택합니다.

2. 스테이지에서 Prod를 선택합니다.

3. (선택 사항) 설명에 설명을 입력합니다.

4. [Deploy]를 선택합니다.

4단계: API 테스트

이 단계에서는 API Gateway 콘솔 외부로 이동하고 API를 사용하여 HTTP 엔드포인트에 액세스합니다.

1. 기본 탐색 창에서 스테이지를 선택합니다.

2. 스테이지 세부 정보에서 복사 아이콘을 선택하여 API의 호출 URL을 복사합니다.

   다음과 같아야 합니다.

   https://my-api-id.execute-api.region-id.amazonaws.com/prod

3. 이 URL을 새 브라우저 탭의 주소 표시줄에 입력하고 URL에 /pets/4를 추가한 다음 요청을 제출합니다.

4. 브라우저에서 다음을 반환합니다.

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

다음 단계

요청 검사를 켜거나, 데이터를 변환하거나, 사용자 지정 게이트웨이 응답을 생성하여 API를 추가로 사용자 지정할 수 있습니다.

API를 사용자 지정하는 더 많은 방법은 다음 자습서를 참조하세요.

• 요청 검증에 대한 자세한 내용은 API Gateway의 기본 요청 확인 설정를 참조하십시오.

• 요청 및 응답 페이로드를 변환하는 방법에 대한 자세한 내용은 API Gateway에서 데이터 변환 설정 섹션을 참조하세요.

• 사용자 지정 게이트웨이 응답을 생성하는 방법에 대한 자세한 내용은 API Gateway 콘솔을 사용하여 REST API에 대한 게이트웨이 응답 설정 섹션을 참조하세요.