자습서: API Gateway에서 REST API를 Amazon S3 프록시로 생성

API Gateway에서 REST API를 사용하여 Amazon S3를 프록시하는 과정을 보여주는 이 예제 단원에서는 REST API를 생성하여 다음 Amazon S3 작업을 노출하도록 구성하는 방법을 설명합니다.

• API의 루트 리소스에서 GET을 노출하여 호출자의 모든 Amazon S3 버킷을 나열합니다.

• 폴더 리소스에서 GET을 노출하여 Amazon S3 버킷의 모든 객체 목록을 봅니다.

• 폴더/항목 리소스에서 GET을 노출하여 Amazon S3 버킷에서 객체를 보거나 다운로드합니다.

Amazon S3 프록시로 샘플 API의 OpenAPI 정의에 표시된 대로 샘플 API를 Amazon S3 프록시로 가져올 수 있습니다. 이 샘플에는 노출된 메서드가 더 많이 포함되어 있습니다. OpenAPI 정의를 사용하여 API를 가져오는 방법에 대한 지침은 OpenAPI를 사용하여 REST API 구성 단원을 참조하십시오.

참고

API Gateway API를 Amazon S3와 통합하려면 API Gateway와 Amazon S3 서비스를 모두 사용할 수 있는 리전을 선택해야 합니다. 리전 사용 가능성은 Amazon API Gateway 엔드포인트 및 할당량 단원을 참조하십시오.

주제

• API에서 Amazon S3 작업을 호출하도록 허용하는 IAM 권한 설정
• API 리소스를 생성하여 Amazon S3 리소스 표시
• API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열
• API 메서드를 노출하여 Amazon S3 버킷 액세스
• API 메서드를 노출하여 버킷에서 Amazon S3 객체 액세스
• Amazon S3 프록시로 샘플 API의 OpenAPI 정의
• REST API 클라이언트를 사용하여 API 호출

API에서 Amazon S3 작업을 호출하도록 허용하는 IAM 권한 설정

API에서 Amazon S3 작업을 간접적으로 호출하도록 허용하려면 적절한 IAM 정책을 IAM 역할에 연결해야 합니다.

AWS 서비스 프록시 실행 역할을 생성하려면

1. AWS Management Console에 로그인하고 https://console.aws.amazon.com/iam/에서 IAM 콘솔을 엽니다.

2. [Roles]를 선택합니다.

3. 역할 생성을 선택합니다.

4. 신뢰할 수 있는 유형의 엔터티 선택에서 AWS 서비스를 선택한 다음 API Gateway를 선택하고 API Gateway가 로그를 CloudWatch Logs로 푸시하도록 허용을 선택합니다.

5. 다음을 선택한 후 다시 다음을 선택합니다.

6. 역할 이름에 APIGatewayS3ProxyPolicy를 입력한 다음 역할 생성을 선택합니다.

7. 역할 목록에서 방금 생성한 역할을 선택합니다. 스크롤하거나 검색 창을 사용하여 역할을 찾을 수 있습니다.

8. 선택한 역할에 대해 권한 추가 탭을 선택합니다.

9. 드롭다운 목록에서 정책 연결을 선택합니다.

10. 검색 창에 AmazonS3FullAccess를 입력하고 권한 추가를 선택합니다.

    참고

    이 자습서에서는 단순화를 위해 관리형 정책을 사용합니다. 가장 좋은 방법은 필요한 최소 권한을 부여하는 자체 IAM 정책을 생성하는 것입니다.

11. 새로 생성된 역할 ARN은 나중에 사용할 수 있도록 기록해 둡니다.

API 리소스를 생성하여 Amazon S3 리소스 표시

API의 루트(/) 리소스를 인증된 호출자의 Amazon S3 버킷 컨테이너로 사용합니다. 또한 Folder 및 Item 리소스를 생성하여 각각 특정 Amazon S3 버킷과 특정 Amazon S3 객체를 표시합니다. 호출자는 요청 URL의 일부로 폴더 이름과 객체 키를 경로 파라미터 형식으로 지정합니다.

참고

객체 키가 /나 다른 특수 문자를 포함하는 객체나에 액세스할 때 문자는 URL로 인코딩되어야 합니다. 예를 들어 test/test.txt는 test%2Ftest.txt으로 인코딩되어야 합니다.

Amazon S3 서비스 기능을 표시하는 API 리소스를 생성하려면

1. Amazon S3 버킷을 생성한 AWS 리전에서 MyS3라는 API를 생성합니다. 이 API의 루트 리소스 /는 Amazon S3 서비스를 가리킵니다. 이 단계에서는/{folder}와 /{item}이라는 두 개의 추가 리소스를 생성합니다.

2. API의 루트 리소스를 선택한 다음 리소스 생성을 선택합니다.

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

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

5. 리소스 이름에 {folder}을 입력합니다.

6. 오리진 간 리소스 공유(CORS)를 선택 취소된 상태로 둡니다.

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

8. /{folder} 리소스를 선택한 다음 리소스 생성을 선택합니다.

9. 이전 단계를 사용하여 이름이 {item}인 하위 리소스 /{folder}를 생성합니다.

   최종 API는 다음과 같아야 합니다.

   

API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열

호출자의 Amazon S3 버킷 목록을 가져오는 중에 Amazon S3에서 GET Service 작업을 호출합니다. API의 루트 리소스(/)에서 GET 메서드를 생성합니다. 다음과 같이 Amazon S3와 통합하도록 GET 메서드를 구성합니다.

API의 GET / 메서드를 생성하고 초기화하는 방법

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

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

3. 통합 유형에서 AWS 서비스를 선택합니다.

4. AWS 리전에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.

5. AWS 서비스에서 Amazon Simple Storage Service를 선택합니다.

6. AWS 하위 도메인은 비워 둡니다.

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

8. 작업 유형에서 경로 재정의 사용을 선택합니다. 경로 재정의를 사용하면 API Gateway가 클라이언트 요청을 해당하는 Amazon S3 REST API path-style request로 Amazon S3로 전달합니다. 여기에서 Amazon S3 리소스가 s3-host-name/bucket/key 패턴의 리소스 경로에 의해 표현됩니다. API Gateway는 s3-host-name을 설정하고 클라이언트가 지정한 bucket 및 key를 클라이언트에서 Amazon S3로 전달합니다.

9. 경로 재정의에서 /를 입력합니다.

10. 실행 역할에 APIGatewayS3ProxyPolicy의 ARN을 입력합니다.

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

이 설정은 프런트 엔드 GET https://your-api-host/stage/ 요청을 백엔드 GET https://your-s3-host/와 통합합니다.

참고

초기 설정 후 메서드의 통합 요청(Integration Request) 페이지에서 이러한 설정을 수정할 수 있습니다.

API의 이 메서드를 호출할 수 있는 사람을 제어하려면 메서드 권한 부여 플래그를 켜고 AWS_IAM으로 설정합니다.

IAM을 활성화하여 GET / 메서드에 대한 액세스를 제어하는 방법

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

2. 권한 부여의 드롭다운 메뉴에서 AWS_IAM을 선택합니다.

   

3. 저장을 선택합니다.

API에서 성공적인 응답과 예외를 호출자에게 적절히 반환하도록 메서드 응답(Method Response)에서 200, 400 및 500 응답을 선언하겠습니다. 여기에 선언되지 않은 상태 코드의 백엔드 응답은 호출자에게 200 응답으로 반환되도록 200 응답에 대한 기본 매핑을 사용합니다.

GET / 메서드에 대한 응답 유형을 선언하려면

1. 메서드 응답 탭의 응답 200에서 편집을 선택합니다.

2. 헤더 추가를 선택하고 다음을 수행합니다.

   1. 헤더 이름에 Content-Type을 입력합니다.

   2. 헤더 추가(Add header)를 선택합니다.

   이 단계를 반복하여 Timestamp 헤더와 Content-Length 헤더를 생성합니다.

3. 저장을 선택합니다.

4. 메서드 응답 탭의 메서드 응답에서 응답 생성을 선택합니다.

5. HTTP 상태 코드에 400을 입력합니다.

   이 응답에는 헤더를 설정하지 않습니다.

6. 저장을 선택합니다.

7. 다음 단계를 반복하여 500 응답을 생성합니다.

   이 응답에는 헤더를 설정하지 않습니다.

Amazon S3의 통합 응답이 버킷 목록을 XML 페이로드로 반환하고 API Gateway의 기본 메서드 응답이 JSON 페이로드를 반환하므로, 백엔드 Content-Type 헤더 파라미터 값을 해당 프런트엔드 값에 매핑해야 합니다. 그렇지 않으면, 응답 본문이 실제로 XML 문자열일 경우 클라이언트는 콘텐츠 유형에 대한 application/json을 수신하게 됩니다. 다음 절차에서는 이렇게 설정하는 방법을 보여줍니다. 또한 클라이언트에게 다른 헤더 파라미터(예: Date 및 Content-Length)를 표시하고자 합니다.

GET / 메서드에 대한 응답 헤더 매핑 설정 방법

1. 통합 응답 탭의 기본값 - 응답에서 편집을 선택합니다.

2. Content-Length 헤더에서 매핑 값으로 integration.response.header.Content-Length를 입력합니다.

3. Content-Type 헤더에서 매핑 값으로 integration.response.header.Content-Type을 입력합니다.

4. Timestamp 헤더에서 매핑 값으로 integration.response.header.Date를 입력합니다.

5. 저장을 선택합니다. 결과는 다음과 같습니다.

   

6. 통합 응답 탭의 통합 응답에서 응답 생성을 선택합니다.

7. HTTP 상태 regex에 4\d{2}를 입력합니다. 이렇게 하면 모든 4xx HTTP 응답 상태 코드가 메서드 응답에 매핑됩니다.

8. 메서드 응답 상태 코드에서 400을 선택합니다.

9. 생성을 선택합니다.

10. 다음 단계를 반복하여 500 메서드 응답의 통합 응답을 생성합니다. HTTP 상태 regex에 5\d{2}를 입력합니다.

지금까지 구성한 API를 테스트해 보겠습니다.

GET / 메서드를 테스트하는 방법

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

2. 테스트를 선택합니다. 결과는 다음 이미지와 같아야 합니다.

   

API 메서드를 노출하여 Amazon S3 버킷 액세스

Amazon S3 버킷을 사용하려면 /{folder} 리소스에서 GET 메서드를 노출하여 버킷의 객체를 나열합니다. 지침은 API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열 단원에 설명한 지침과 비슷합니다. 더 많은 메서드를 보려면 Amazon S3 프록시로 샘플 API의 OpenAPI 정의에서 샘플 API를 가져올 수 있습니다.

폴더 리소스에 GET 메서드를 노출하려면

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

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

3. 통합 유형에서 AWS 서비스를 선택합니다.

4. AWS 리전에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.

5. AWS 서비스에서 Amazon Simple Storage Service를 선택합니다.

6. AWS 하위 도메인은 비워 둡니다.

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

8. 작업 유형에서 경로 재정의 사용을 선택합니다.

9. 경로 재정의에서 {bucket}를 입력합니다.

10. 실행 역할에 APIGatewayS3ProxyPolicy의 ARN을 입력합니다.

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

Amazon S3 엔드포인트 URL에 {folder} 경로 파라미터를 설정합니다. 메서드 요청의 {folder} 경로 파라미터를 통합 요청의 {bucket} 경로 파라미터에 매핑해야 합니다.

{folder}를 {bucket}에 매핑하려면

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

2. URL 경로 파라미터를 선택한 다음 경로 파라미터 추가를 선택합니다.

3. 이름에 bucket를 입력합니다.

4. 다음에서 매핑됨에 method.request.path.folder을 입력합니다. 구성은 다음과 비슷해야 합니다.

   

5. 저장을 선택합니다.

이제 API를 테스트합니다.

/{folder} GET 메서드를 테스트하려면

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

2. 경로의 folder에서 버킷 이름을 입력합니다.

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

   테스트 결과에는 버킷의 객체 목록이 포함됩니다.

   

API 메서드를 노출하여 버킷에서 Amazon S3 객체 액세스

Amazon S3에서는 지정된 버킷에서 객체를 액세스 및 관리하는 GET, DELETE, HEAD, OPTIONS, POST 및 PUT 작업을 지원합니다. 이 자습서에서는 {folder}/{item} 리소스에 GET 메서드를 노출하여 버킷에서 이미지를 가져옵니다. {folder}/{item} 리소스의 더 많은 적용 사례는 샘플 API를 참조하세요. Amazon S3 프록시로 샘플 API의 OpenAPI 정의

아이템 리소스에 GET 메서드 노출

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

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

3. 통합 유형에서 AWS 서비스를 선택합니다.

4. AWS 리전에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.

5. AWS 서비스에서 Amazon Simple Storage Service를 선택합니다.

6. AWS 하위 도메인은 비워 둡니다.

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

8. 작업 유형에서 경로 재정의 사용을 선택합니다.

9. 경로 재정의에 {bucket}/{object}를 입력합니다.

10. 실행 역할에 APIGatewayS3ProxyPolicy의 ARN을 입력합니다.

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

Amazon S3 엔드포인트 URL에 {folder} 및 {item} 경로 파라미터를 설정합니다. 메서드 요청의 경로 파라미터를 통합 요청의 경로 파라미터에 매핑해야 합니다.

이 단계에서는 다음 작업을 수행합니다.

• 메서드 요청의 {folder} 경로 파라미터를 통합 요청의 {bucket} 경로 파라미터에 매핑합니다.

• 메서드 요청의 {item} 경로 파라미터를 통합 요청의 {object} 경로 파라미터에 매핑합니다.

{folder}를 {bucket}에 매핑하고 {item}을 {object}에 매핑하려면

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

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

3. 경로 파라미터 추가를 선택합니다.

4. 이름에 bucket를 입력합니다.

5. 다음에서 매핑됨에 method.request.path.folder을 입력합니다.

6. 경로 파라미터 추가를 선택합니다.

7. 이름에 object를 입력합니다.

8. 다음에서 매핑됨에 method.request.path.item을 입력합니다.

9. 저장을 선택합니다.

/{folder}/{object} GET 메서드를 테스트하려면

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

2. 경로의 folder에서 버킷 이름을 입력합니다.

3. 경로의 item에서 항목 이름을 입력합니다.

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

   응답 본문에는 항목의 콘텐츠가 포함됩니다.

   

   이 요청은 (“Hello world”)의 일반 텍스트를 해당 Amazon S3 버킷(DOC-EXAMPLE-BUCKET)에 지정된 파일(test.txt)의 콘텐츠로 올바르게 반환합니다.

API Gateway에서 utf-8 인코딩된 JSON 콘텐츠 이외의 것으로 간주되는 이진 파일을 다운로드 또는 업로드하려면 추가 API 설정이 필요합니다. 개략적으로 설명하면 다음과 같습니다.

S3에서 이진 파일을 다운로드 또는 업로드하려면

1. 해당 파일의 미디어 유형을 API의 binaryMediaTypes에 등록합니다. 이 작업은 콘솔에서 다음과 같이 수행할 수 있습니다.

   1. API에 대한 API 설정을 선택합니다.

   2. 이진 미디어 형식에서 미디어 형식 관리를 선택합니다.

   3. 이진 미디어 형식 추가를 선택한 다음 필요한 미디어 형식(예: image/png)을 입력합니다.

   4. 변경 사항 저장을 선택하여 설정을 저장합니다.

2. Content-Type(업로드하는 경우) 및/또는 Accept(다운로드하는 경우) 헤더를 메서드 요청에 추가하여 클라이언트에게 필요한 이진 미디어 유형을 지정하고 통합 유형에 매핑하도록 요청합니다.

3. 통합 요청(업로드하는 경우) 및 통합 응답(다운로드하는 경우)에서 콘텐츠 처리(Content Handling)를 Passthrough로 설정합니다. 해당 콘텐츠 유형에 어떤 매핑 템플릿도 정의되어 있지 않은지 확인하십시오. 자세한 내용은 통합 패스스루 동작 및 VTL 매핑 템플릿 선택 단원을 참조하십시오.

페이로드 크기 제한은 10MB입니다. REST API 구성 및 실행에 대한 API Gateway 할당량을(를) 참조하세요.

Amazon S3에 저장된 파일에서 올바른 콘텐츠 유형이 파일의 메타데이터로 추가되어 있는지 확인하십시오. 스트리밍 가능한 미디어 콘텐츠의 경우, Content-Disposition:inline도 메타데이터에 추가되어야 할 수 있습니다.

API Gateway에서의 이진 지원에 대한 자세한 내용은 API Gateway의 콘텐츠 유형 변환 단원을 참조하십시오.