# 자습서: Amazon Kinesis 프록시로 REST API 생성
API Gateway에서 REST API를 사용하여 Amazon S3를 프록시하는 과정을 보여주는 이 예제 단원에서는 REST API를 생성하여 다음 Amazon S3 작업을 노출하도록 구성하는 방법을 설명합니다.
+ API의 루트 리소스에서 GET을 노출하여 [호출자의 모든 Amazon S3 버킷을 나열합니다](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ 폴더 리소스에서 GET을 노출하여 [Amazon S3 버킷의 모든 객체 목록을 봅니다](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ 폴더/항목 리소스에서 GET을 노출하여 [Amazon S3 버킷에서 객체를 보거나 다운로드합니다](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
[Amazon S3 프록시로 샘플 API의 OpenAPI 정의](api-as-s3-proxy-export-swagger-with-extensions.md)에 표시된 대로 샘플 API를 Amazon S3 프록시로 가져올 수 있습니다. 이 샘플에는 노출된 메서드가 더 많이 포함되어 있습니다. OpenAPI 정의를 사용하여 API를 가져오는 방법에 대한 지침은 [API Gateway에서 OpenAPI를 사용하여 REST API 개발](api-gateway-import-api.md) 단원을 참조하십시오.
**참고**
API Gateway API를 Amazon S3와 통합하려면 API Gateway와 Amazon S3 서비스를 모두 사용할 수 있는 리전을 선택해야 합니다. 리전 사용 가능성은 [Amazon API Gateway 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/apigateway.html) 단원을 참조하십시오.
**Topics**
+ [API에서 Amazon S3 작업을 호출하도록 허용하는 IAM 권한 설정](#api-as-s3-proxy-iam-permissions)
+ [API 리소스를 생성하여 Amazon S3 리소스 표시](#api-as-s3-proxy-create-resources)
+ [API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열](#api-root-get-as-s3-get-service)
+ [API 메서드를 노출하여 Amazon S3 버킷 액세스](#api-folder-operations-as-s3-bucket-actions)
+ [API 메서드를 노출하여 버킷에서 Amazon S3 객체 액세스](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Amazon S3 프록시로 샘플 API의 OpenAPI 정의](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [REST API 클라이언트를 사용하여 API 호출](api-as-s3-proxy-test-using-postman.md)
## API에서 Amazon S3 작업을 호출하도록 허용하는 IAM 권한 설정
API에서 Amazon S3 작업을 간접적으로 호출하도록 허용하려면 적절한 IAM 정책을 IAM 역할에 연결해야 합니다. 이 단계에서는 새 IAM 역할을 생성합니다.
**AWS 서비스 프록시 실행 역할을 생성하려면**
1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)에서 IAM 콘솔을 엽니다.
1. **Roles**를 선택합니다.
1. **역할 생성**을 선택합니다.
1. **신뢰할 수 있는 유형의 엔터티 선택**에서 **AWS 서비스**를 선택한 다음 **API Gateway**를 선택하고 **API Gateway가 로그를 CloudWatch Logs로 푸시하도록 허용**을 선택합니다.
1. **다음**을 선택한 후 다시 **다음**을 선택합니다.
1. **역할 이름**에 **APIGatewayS3ProxyPolicy**를 입력한 다음 **역할 생성**을 선택합니다.
1. **역할** 목록에서 방금 생성한 역할을 선택합니다. 스크롤하거나 검색 창을 사용하여 역할을 찾을 수 있습니다.
1. 선택한 역할에 대해 **권한 추가** 탭을 선택합니다.
1. 드롭다운 목록에서 **정책 연결**을 선택합니다.
1. 검색 창에 **AmazonS3FullAccess**를 입력하고 **권한 추가**를 선택합니다.
**참고**
이 자습서에서는 단순화를 위해 관리형 정책을 사용합니다. 가장 좋은 방법은 필요한 최소 권한을 부여하는 자체 IAM 정책을 생성하는 것입니다.
1. 새로 생성된 **역할 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}**이라는 두 개의 추가 리소스를 생성합니다.
1. **리소스 생성**을 선택합니다.
1. **프록시 리소스**는 꺼진 상태로 둡니다.
1. **리소스 경로**에서 `/`를 선택합니다.
1. **리소스 이름**에 **{folder}**을 입력합니다.
1. **오리진 간 리소스 공유(CORS)**를 선택 취소된 상태로 둡니다.
1. **리소스 생성**을 선택합니다.
1. **/{folder}** 리소스를 선택한 다음 **리소스 생성**을 선택합니다.
1. 이전 단계를 사용하여 이름이 **{item}**인 하위 리소스 **/{folder}**를 생성합니다.
최종 API는 다음과 같아야 합니다.
## API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열
호출자의 Amazon S3 버킷 목록을 가져오는 중에 Amazon S3에서 [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) 작업을 호출합니다. API의 루트 리소스(**/**)에서 GET 메서드를 생성합니다. 다음과 같이 Amazon S3와 통합하도록 GET 메서드를 구성합니다.
**API의 `GET /` 메서드를 생성하고 초기화하는 방법**
1. **/** 리소스를 선택한 다음 **메서드 생성**을 선택합니다.
1. 메서드 유형에서 **GET**을 선택합니다.
1. **통합 유형**에서 **AWS 서비스**를 선택합니다.
1. **AWS 리전**에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.
1. **AWS 서비스**에서 **Amazon Simple Storage Service**를 선택합니다.
1. **AWS 하위 도메인**은 비워 둡니다.
1. **HTTP 메서드**에서 **GET**을 선택합니다.
1. **작업 유형**에서 **경로 재정의 사용**을 선택합니다.
경로 재정의를 사용하면 API Gateway가 클라이언트 요청을 해당하는 [Amazon S3 REST API path-style request](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html)로 Amazon S3로 전달합니다. 여기에서 Amazon S3 리소스가 `s3-host-name/bucket/key` 패턴의 리소스 경로에 의해 표현됩니다. API Gateway는 `s3-host-name`을 설정하고 클라이언트가 지정한 `bucket` 및 `key`를 클라이언트에서 Amazon S3로 전달합니다.
1. **경로 재정의**에서 **/**를 입력합니다.
1. **실행 역할**에 **APIGatewayS3ProxyPolicy**의 ARN을 입력합니다.
1. **메서드 요청 설정**을 선택합니다.
메서드 요청 설정을 사용하여 API의 이 메서드를 직접 호출할 수 있는 사용자를 제어할 수 있습니다.
1. **권한 부여**의 드롭다운 메뉴에서 `AWS_IAM`을 선택합니다.
1. **메서드 생성**을 선택합니다.
이 설정은 프런트 엔드 `GET https://{{your-api-host}}/{{stage}}/` 요청을 백엔드 `GET https://{{your-s3-host}}/`와 통합합니다.
API에서 성공적인 응답과 예외를 호출자에게 적절히 반환하도록 **메서드 응답**에서 200, 400 및 500 응답을 선언합니다. 여기에 선언되지 않은 상태 코드의 백엔드 응답은 호출자에게 200 응답으로 반환되도록 200 응답에 대한 기본 매핑을 사용합니다.
**`GET /` 메서드에 대한 응답 유형을 선언하려면**
1. **메서드 응답** 탭의 **응답 200**에서 **편집**을 선택합니다.
1. **헤더 추가**를 선택하고 다음을 수행합니다.
1. **헤더 이름**에 **Content-Type**을 입력합니다.
1. **헤더 추가(Add header)**를 선택합니다.
이 단계를 반복하여 **Timestamp** 헤더와 **Content-Length** 헤더를 생성합니다.
1. **저장**을 선택합니다.
1. **메서드 응답** 탭의 **메서드 응답**에서 **응답 생성**을 선택합니다.
1. **HTTP 상태 코드**에 **400**을 입력합니다.
이 응답에는 헤더를 설정하지 않습니다.
1. **저장**을 선택합니다.
1. 다음 단계를 반복하여 500 응답을 생성합니다.
이 응답에는 헤더를 설정하지 않습니다.
Amazon S3의 통합 응답이 버킷 목록을 XML 페이로드로 반환하고 API Gateway의 기본 메서드 응답이 JSON 페이로드를 반환하므로, 백엔드 Content-Type 헤더 파라미터 값을 해당 프런트엔드 값에 매핑해야 합니다. 그렇지 않으면, 응답 본문이 실제로 XML 문자열일 경우 클라이언트는 콘텐츠 유형에 대한 `application/json`을 수신하게 됩니다. 다음 절차에서는 이렇게 설정하는 방법을 보여줍니다. 또한 클라이언트에게 Date 및 Content-Length같은 다른 헤더 파라미터를 표시하고자 합니다.
**GET / 메서드에 대한 응답 헤더 매핑 설정 방법**
1. **통합 응답** 탭의 **기본값 - 응답**에서 **편집**을 선택합니다.
1. **Content-Length** 헤더에서 매핑 값으로 **integration.response.header.Content-Length**를 입력합니다.
1. **Content-Type** 헤더에서 매핑 값으로 **integration.response.header.Content-Type**을 입력합니다.
1. **Timestamp** 헤더에서 매핑 값으로 **integration.response.header.Date**를 입력합니다.
1. **저장**을 선택합니다. 결과는 다음과 같습니다.
1. **통합 응답** 탭의 **통합 응답**에서 **응답 생성**을 선택합니다.
1. **HTTP 상태 regex**에 **4\\d{2}**를 입력합니다. 이렇게 하면 모든 4xx HTTP 응답 상태 코드가 메서드 응답에 매핑됩니다.
1. **메서드 응답 상태 코드**에서 **400**을 선택합니다.
1. **생성(Create)**을 선택합니다.
1. 다음 단계를 반복하여 500 메서드 응답의 통합 응답을 생성합니다. **HTTP 상태 regex**에 **5\\d{2}**를 입력합니다.
지금까지 구성한 API를 테스트해 보는 것도 좋은 방법입니다.
**`GET /` 메서드를 테스트하는 방법**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **테스트**를 선택합니다. 결과는 다음 이미지와 같아야 합니다.
## API 메서드를 노출하여 Amazon S3 버킷 액세스
Amazon S3 버킷을 사용하려면 /{folder} 리소스에서 `GET` 메서드를 노출하여 버킷의 객체를 나열합니다. 지침은 [API 메서드를 노출하여 호출자의 Amazon S3 버킷 나열](#api-root-get-as-s3-get-service) 단원에 설명한 지침과 비슷합니다. 더 많은 메서드를 보려면 [Amazon S3 프록시로 샘플 API의 OpenAPI 정의](api-as-s3-proxy-export-swagger-with-extensions.md)에서 샘플 API를 가져올 수 있습니다.
**폴더 리소스에 GET 메서드를 노출하려면**
1. **/{folder}** 리소스를 선택한 다음 **메서드 생성**을 선택합니다.
1. 메서드 유형에서 **GET**을 선택합니다.
1. **통합 유형**에서 **AWS 서비스**를 선택합니다.
1. **AWS 리전**에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.
1. **AWS 서비스**에서 **Amazon Simple Storage Service**를 선택합니다.
1. **AWS 하위 도메인**은 비워 둡니다.
1. **HTTP 메서드**에서 **GET**을 선택합니다.
1. **작업 유형**에서 **경로 재정의 사용**을 선택합니다.
1. **경로 재정의**에서 **{bucket}**를 입력합니다.
1. **실행 역할**에 **APIGatewayS3ProxyPolicy**의 ARN을 입력합니다.
1. **메서드 생성**을 선택합니다.
Amazon S3 엔드포인트 URL에 `{folder}` 경로 파라미터를 설정합니다. 메서드 요청의 `{folder}` 경로 파라미터를 통합 요청의 `{bucket}` 경로 파라미터에 매핑해야 합니다.
**`{folder}`를 `{bucket}`에 매핑하려면**
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **URL 경로 파라미터**를 선택한 다음 **경로 파라미터 추가**를 선택합니다.
1. **이름**에 **bucket**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.path.folder**을 입력합니다.
1. **저장**을 선택합니다.
이제 API를 테스트합니다.
**`/{folder} GET` 메서드를 테스트하려면**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **경로**의 **folder**에서 버킷 이름을 입력합니다.
1. **테스트**를 선택합니다.
테스트 결과에는 버킷의 객체 목록이 포함됩니다.
## API 메서드를 노출하여 버킷에서 Amazon S3 객체 액세스
Amazon S3에서는 지정된 버킷에서 객체를 액세스 및 관리하는 GET, DELETE, HEAD, OPTIONS, POST 및 PUT 작업을 지원합니다. 이 자습서에서는 `{folder}/{item}` 리소스에 `GET` 메서드를 노출하여 버킷에서 이미지를 가져옵니다. `{folder}/{item}` 리소스의 더 많은 적용 사례는 샘플 API를 참조하세요. [Amazon S3 프록시로 샘플 API의 OpenAPI 정의](api-as-s3-proxy-export-swagger-with-extensions.md)
**아이템 리소스에 GET 메서드 노출**
1. **/{item}** 리소스를 선택한 다음 **메서드 생성**을 선택합니다.
1. 메서드 유형에서 **GET**을 선택합니다.
1. **통합 유형**에서 **AWS 서비스**를 선택합니다.
1. **AWS 리전**에서 Amazon S3 버킷을 생성한 AWS 리전을 선택합니다.
1. **AWS 서비스**에서 **Amazon Simple Storage Service**를 선택합니다.
1. **AWS 하위 도메인**은 비워 둡니다.
1. **HTTP 메서드**에서 **GET**을 선택합니다.
1. **작업 유형**에서 **경로 재정의 사용**을 선택합니다.
1. **경로 재정의**에 **{bucket}/{object}**를 입력합니다.
1. **실행 역할**에 **APIGatewayS3ProxyPolicy**의 ARN을 입력합니다.
1. **메서드 생성**을 선택합니다.
Amazon S3 엔드포인트 URL에 `{folder}` 및 `{item}` 경로 파라미터를 설정합니다. 메서드 요청의 경로 파라미터를 통합 요청의 경로 파라미터에 매핑해야 합니다.
이 단계에서는 다음 작업을 수행합니다.
+ 메서드 요청의 `{folder}` 경로 파라미터를 통합 요청의 `{bucket}` 경로 파라미터에 매핑합니다.
+ 메서드 요청의 `{item}` 경로 파라미터를 통합 요청의 `{object}` 경로 파라미터에 매핑합니다.
**`{folder}`를 `{bucket}`에 매핑하고 `{item}`을 `{object}`에 매핑하려면**
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **URL 경로 파라미터**를 선택합니다.
1. **경로 파라미터 추가**를 선택합니다.
1. **이름**에 **bucket**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.path.folder**을 입력합니다.
1. **경로 파라미터 추가**를 선택합니다.
1. **이름**에 **object**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.path.item**을 입력합니다.
1. **저장**을 선택합니다.
**`/{folder}/{object} GET` 메서드를 테스트하려면**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **경로**의 **folder**에서 버킷 이름을 입력합니다.
1. **경로**의 **item**에서 항목 이름을 입력합니다.
1. **테스트**를 선택합니다.
응답 본문에는 항목의 콘텐츠가 포함됩니다.
이 요청은 (“Hello world”)의 일반 텍스트를 해당 Amazon S3 버킷(amzn-s3-demo-bucket)에 지정된 파일(test.txt)의 콘텐츠로 올바르게 반환합니다.
API Gateway에서 utf-8 인코딩된 JSON 콘텐츠 이외의 것으로 간주되는 이진 파일을 다운로드 또는 업로드하려면 추가 API 설정이 필요합니다. 개략적으로 설명하면 다음과 같습니다.
**S3에서 이진 파일을 다운로드 또는 업로드하려면**
1. 해당 파일의 미디어 유형을 API의 binaryMediaTypes에 등록합니다. 이 작업은 콘솔에서 다음과 같이 수행할 수 있습니다.
1. API에 대한 **API 설정**을 선택합니다.
1. **이진 미디어 형식**에서 **미디어 형식 관리**를 선택합니다.
1. **이진 미디어 형식 추가**를 선택한 다음 필요한 미디어 형식(예: `image/png`)을 입력합니다.
1. **변경 사항 저장**을 선택하여 설정을 저장합니다.
1. `Content-Type`(업로드하는 경우) 및/또는 `Accept`(다운로드하는 경우) 헤더를 메서드 요청에 추가하여 클라이언트에게 필요한 이진 미디어 유형을 지정하고 통합 유형에 매핑하도록 요청합니다.
1. 통합 요청(업로드하는 경우) 및 통합 응답(다운로드하는 경우)에서 **콘텐츠 처리(Content Handling)**를 `Passthrough`로 설정합니다. 해당 콘텐츠 유형에 어떤 매핑 템플릿도 정의되어 있지 않은지 확인하십시오. 자세한 내용은 [API Gateway에서 REST API의 데이터 변환](rest-api-data-transformations.md) 섹션을 참조하세요.
페이로드 크기 제한은 10MB입니다. [REST API 구성 및 실행에 대한 API Gateway 할당량](api-gateway-execution-service-limits-table.md)을(를) 참조하세요.
Amazon S3에 저장된 파일에서 올바른 콘텐츠 유형이 파일의 메타데이터로 추가되어 있는지 확인하십시오. 스트리밍 가능한 미디어 콘텐츠의 경우, `Content-Disposition:inline`도 메타데이터에 추가되어야 할 수 있습니다.
API Gateway에서의 이진 지원에 대한 자세한 내용은 [API Gateway의 콘텐츠 유형 변환](api-gateway-payload-encodings-workflow.md) 단원을 참조하십시오.