# API Gateway에서 HTTP API 개발
이 단원에서는 API Gateway API를 개발하는 동안 필요한 API Gateway 기능에 대해 자세히 설명합니다.
API Gateway API를 개발할 때 API의 여러 특성을 결정합니다. 이러한 특성은 API의 사용 사례에 따라 달라집니다. 예를 들어, 특정 클라이언트만 API를 호출하도록 허용하거나 모든 사용자가 API를 사용할 수 있도록 할 수 있습니다. API 호출로 Lambda 함수를 실행하거나, 데이터베이스 쿼리를 작성하거나, 애플리케이션을 호출할 수 있습니다.
**Topics**
+ [
## HTTP API 생성
](#http-api-examples)
+ [
# API Gateway에서 HTTP API에 대한 라우팅 생성
](http-api-develop-routes.md)
+ [
# API Gateway의 HTTP API에 대한 IP 주소 유형
](http-api-ip-address-type.md)
+ [
# API Gateway에서 HTTP API에 대한 액세스 제어 및 관리
](http-api-access-control.md)
+ [
# API Gateway에서 HTTP API 통합 생성
](http-api-develop-integrations.md)
+ [
# API Gateway에서 HTTP API CORS 구성
](http-api-cors.md)
+ [
# API Gateway에서 HTTP API에 대한 API 요청 및 응답 변환
](http-api-parameter-mapping.md)
+ [
# API Gateway에서 HTTP API에 대한 OpenAPI 정의 사용
](http-api-open-api.md)
## HTTP API 생성
함수 API를 만들려면 최소 하나 이상의 경로, 통합, 단계 및 배포가 있어야 합니다.
다음 예제에서는 AWS Lambda 또는 HTTP 통합, 경로, 변경 사항을 자동으로 배포하도록 구성된 기본 단계를 사용하여 API를 생성하는 방법을 보여 줍니다.
이 가이드에서는 API Gateway와 Lambda에 대해 잘 알고 있다고 가정합니다. 자세한 가이드는 [API Gateway 시작](getting-started.md) 단원을 참조하세요.
**Topics**
+ [
### 를 사용하여 HTTP API 생성AWS Management Console
](#apigateway-http-api-create.console)
+ [
### AWS CLI를 사용하여 HTTP API 생성
](#http-api-examples.cli.quick-create)
### 를 사용하여 HTTP API 생성AWS Management Console
1. [API Gateway 콘솔](https://console.aws.amazon.com/apigateway)을 엽니다.
1. **API 생성(Create API)**을 선택합니다.
1. **HTTP API**에서 **빌드**를 선택합니다.
1. **통합 추가**를 선택한 다음, AWS Lambda 함수를 선택하거나 HTTP 엔드포인트를 입력합니다.
1. **이름**에 API의 이름을 입력합니다.
1. [**Review and create**]를 선택합니다.
1. **Create**를 선택합니다.
이제 API를 호출할 준비가 되었습니다. 브라우저에서 호출 URL을 입력하거나 Curl을 사용하여 API를 테스트할 수 있습니다.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### AWS CLI를 사용하여 HTTP API 생성
빠른 생성을 사용하여 Lambda 또는 HTTP 통합, 기본 catch-all 경로, 변경 사항을 자동으로 배포하도록 구성된 기본 스테이지를 통해 API를 생성할 수 있습니다. 다음 [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) 명령은 빠른 생성을 사용하여 백엔드에서 Lambda 함수와 통합되는 API를 생성합니다.
**참고**
Lambda 통합을 호출하려면 API Gateway에 필요한 권한이 있어야 합니다. 리소스 기반 정책이나 IAM 역할을 사용하여 API Gateway 권한을 부여하여 Lambda 함수를 호출할 수 있습니다. 자세한 내용은 *AWS Lambda 개발자 안내서*의 [AWS Lambda 권한](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html)을 참조하세요.
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
이제 API를 호출할 준비가 되었습니다. 브라우저에서 호출 URL을 입력하거나 Curl을 사용하여 API를 테스트할 수 있습니다.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# API Gateway에서 HTTP API에 대한 라우팅 생성
수신 API 요청을 백엔드 리소스로 직접 라우팅합니다. 라우팅은 HTTP 메서드와 리소스 경로(예: `GET /pets`) 등 두 부분으로 구성됩니다. 라우팅에 대한 특정 HTTP 메서드를 정의할 수 있습니다. 또는 `ANY` 메서드를 사용하여 리소스에 대해 정의하지 않은 모든 메서드와 일치시킬 수 있습니다. 다른 경로와 일치하지 않는 요청에 대해 catch-all 역할을 하는 `$default` 경로를 생성할 수 있습니다.
**참고**
API Gateway는 URL 인코딩 요청 파라미터를 백엔드 통합에 전달하기 전에 디코딩합니다.
## 경로 변수 작업
HTTP API 라우팅에서 경로 변수를 사용할 수 있습니다.
예를 들어, `GET /pets/{petID}` 라우팅은 클라이언트가 `GET`에 제출하는 `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6` 요청을 포착합니다.
*복잡한 경로 변수*는 라우팅의 모든 하위 리소스를 포착합니다. 복잡한 경로 변수를 생성하려면 변수 이름에 `+`를 추가합니다(예: `{proxy+}`). 복잡한 경로 변수는 리소스 경로의 끝에 있어야 합니다.
## 쿼리 문자열 파라미터 작업
HTTP API에 대한 요청에 포함된 경우 API Gateway에서는 기본적으로 쿼리 문자열 파라미터를 백엔드 통합으로 보냅니다.
예를 들어, 클라이언트가 요청을 `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`에 보내는 경우 쿼리 문자열 파라미터 `?id=4&type=dog`가 통합에 전송됩니다.
## `$default` 라우팅 작업
`$default` 라우팅은 API의 다른 라우팅과 명시적으로 일치하지 않는 요청을 포착합니다.
`$default` 라우팅이 요청을 받는 경우 API Gateway에서 전체 요청 경로를 통합에 보냅니다. 예를 들어 `$default` 라우팅만 있는 API를 생성하여 `ANY` HTTP 엔드포인트가 있는 `https://petstore-demo-endpoint.execute-api.com` 메서드에 통합할 수 있습니다. 요청을 `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`에 보내는 경우 API Gateway에서 요청을 `https://petstore-demo-endpoint.execute-api.com/store/checkout`에 보냅니다.
HTTP 통합에 대한 자세한 내용은 [HTTP API에 대한 HTTP 프록시 통합 생성](http-api-develop-integrations-http.md) 단원을 참조하세요.
## API 요청 라우팅
클라이언트가 API 요청을 보내는 경우 API Gateway에서 먼저 요청을 라우팅할 [스테이지](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html)를 결정합니다. 요청이 스테이지와 명시적으로 일치하는 경우 API Gateway는 요청을 해당 스테이지로 보냅니다. 요청과 완전히 일치하는 스테이지가 없는 경우 API Gateway는 요청을 `$default` 스테이지로 보냅니다. `$default` 스테이지가 없는 경우 API에서 `{"message":"Not Found"}`가 반환되며 CloudWatch 로그가 생성되지 않습니다.
스테이지를 선택한 후 API Gateway는 라우팅을 선택합니다. API Gateway는 다음 우선 순위를 사용하여 가장 일치하는 라우팅을 선택합니다.
1. 라우팅 및 메서드에 완전히 일치시킵니다.
1. 복잡한 경로 변수(`{proxy+}`)가 있는 라우팅 및 메서드에 일치시킵니다.
1. `$default` 라우팅
요청과 일치하는 라우팅이 없으면 API Gateway에서 `{"message":"Not Found"}`를 클라이언트로 반환합니다.
예를 들어 `$default` 단계가 있는 API와 다음 예제 라우팅을 고려합니다.
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
다음 표에는 API Gateway에서 요청을 예제 라우팅으로 라우팅하는 방법이 요약되어 있습니다.
| 요청 | 선택한 라우팅 | 설명 |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | 요청이 이 정적 라우팅과 완전히 일치합니다. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | 요청이 이 라우팅과 완전히 일치합니다. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | 요청이 라우팅과 완전히 일치하지 않습니다. `GET` 메서드와 복잡한 경로 변수가 있는 라우팅은 이 요청을 포착합니다. |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | `ANY` 메서드는 라우팅에 대해 정의하지 않은 모든 메서드와 일치합니다. 복잡한 경로 변수가 있는 라우팅은 `$default` 라우팅보다 우선 순위가 높습니다. |
# API Gateway의 HTTP API에 대한 IP 주소 유형
API를 만들 때 API를 간접적으로 호출할 수 있는 IP 주소 유형을 지정합니다. IPv4를 선택하여 IPv4 주소가 API를 간접적으로 호출하도록 확인하거나, 듀얼 스택을 선택하여 IPv4 및 IPv6 주소가 모두 API를 간접적으로 호출하도록 허용할 수 있습니다. IP 공간 소진을 완화하기 위해 또는 보안 태세를 위해 IP 주소 유형을 듀얼 스택으로 설정하는 것이 좋습니다. 듀얼 스택 IP 주소 유형의 이점에 대한 자세한 내용은 [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)를 참조하세요.
## IP 주소 유형에 대한 고려 사항
다음 고려 사항은 IP 주소 유형 사용에 영향을 미칠 수 있습니다.
+ 모든 HTTP API의 기본 IP 주소 유형은 IPv4입니다.
+ 기존 API의 IP 주소 유형을 IPv4에서 듀얼 스택으로 변경하는 경우 API에 대한 액세스를 제어하는 정책이 IPv6 직접 호출을 설명하도록 업데이트되었는지 확인합니다. IP 주소 유형을 변경하면 변경 사항이 즉시 적용됩니다.
+ API는 API와 다른 IP 주소 유형의 사용자 지정 도메인 이름에 매핑할 수 있습니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
## HTTP API의 IP 주소 유형 변경
API의 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다. AWS Management Console, AWS CLI, CloudFormation 또는 AWS SDK를 사용하여 API의 구성을 업데이트할 수 있습니다. API의 IP 주소 유형을 변경하는 경우 변경 사항이 적용되려면 API를 재배포해서는 안 됩니다.
------
#### [ AWS Management Console ]
**HTTP API의 IP 주소 유형을 변경하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. **API 설정**에서 **편집**을 선택합니다.
1. IP 주소 유형에서 **IPv4** 또는 **듀얼 스택**을 선택합니다.
1. **저장**을 선택합니다.
API 구성에 대한 변경 사항은 즉시 적용됩니다.
------
#### [ AWS CLI ]
다음 [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) 명령은 IP 주소 유형이 듀얼 스택이 되도록 API를 업데이트합니다.
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
출력은 다음과 같습니다.
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# API Gateway에서 HTTP API에 대한 액세스 제어 및 관리
API Gateway는 HTTP API 액세스 제어 및 관리에 다중 메커니즘을 지원합니다.
+ **Lambda 권한 부여자**는 Lambda 함수를 사용하여 API에 대한 액세스를 제어합니다. 자세한 내용은 [AWS Lambda 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어](http-api-lambda-authorizer.md) 단원을 참조하세요.
+ **JWT 권한 부여자**는 JSON 웹 토큰을 사용하여 API에 대한 액세스를 제어합니다. 자세한 내용은 [API Gateway에서 JWT 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어](http-api-jwt-authorizer.md) 단원을 참조하세요.
+ **표준 AWS IAM 역할 및 정책**은 유연하고 강력한 액세스 제어를 제공합니다. IAM 역할 및 정책을 사용하여 API를 생성하고 관리할 수 있는 사용자와 API를 호출할 수 있는 사용자를 제어할 수 있습니다. 자세한 내용은 [API Gateway에서 IAM 권한 부여를 통해 HTTP API에 대한 액세스 제어](http-api-access-control-iam.md) 섹션을 참조하세요.
보안 태세를 개선하려면 HTTP API의 모든 라우팅에 대해 권한 부여자를 구성하는 것이 좋습니다. 다양한 규정 준수 프레임워크를 준수하기 위해 이 작업을 수행해야 할 수 있습니다. 자세한 내용은 *AWS Security Hub 사용 설명서*에서 [Amazon API Gateway 제어](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)를 참조하세요.
# AWS Lambda 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어
Lambda 권한 부여자를 사용하여 HTTP API에 대한 액세스를 제어하는 Lambda 함수를 사용합니다. 그런 다음 클라이언트가 API를 호출하면 API Gateway에서 Lambda 함수를 호출합니다. API Gateway는 Lambda 함수의 응답을 사용하여 클라이언트가 API에 액세스할 수 있는지 여부를 결정합니다.
## 페이로드 형식 버전
권한 부여자 페이로드 형식 버전은 API Gateway에서 Lambda 권한 부여자로 전송하는 데이터의 형식과 API Gateway에서 Lambda의 응답을 해석하는 방법을 지정합니다. 페이로드 형식 버전을 지정하지 않으면 AWS Management Console에서는 기본적으로 최신 버전을 사용합니다. AWS CLI, CloudFormation 또는 SDK를 사용하여 Lambda 권한 부여자를 생성하는 경우 `authorizerPayloadFormatVersion`을 지정해야 합니다. 지원되는 값은 `1.0` 및 `2.0`입니다.
REST API와의 호환성이 필요한 경우 `1.0` 버전을 사용합니다.
다음 예제에서는 각 페이로드 형식 버전의 구조를 보여 줍니다.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
------
## Lambda 권한 부여자 응답 형식
페이로드 형식 버전은 Lambda 함수에서 반환되어야 하는 응답 구조도 결정합니다.
### 형식 1.0에 대한 Lambda 함수 응답
`1.0` 형식 버전을 선택하는 경우 Lambda 권한 부여자는 API 라우팅에 대한 액세스를 허용하거나 거부하는 IAM 정책을 반환해야 합니다. 정책에서 표준 IAM 정책 구문을 사용할 수 있습니다. IAM 정책에 대한 예시는 [API 호출을 위한 액세스 제어](api-gateway-control-access-using-iam-policies-to-invoke-api.md) 단원을 참조하세요. `$context.authorizer.property`를 사용하여 컨텍스트 속성을 Lambda 통합 또는 액세스 로그에 전달할 수 있습니다. `context` 객체는 선택 사항이며 `claims`는 예약된 자리 표시자이므로 컨텍스트 객체로 사용할 수 없습니다. 자세한 내용은 [HTTP API 액세스 로그 사용자 정의](http-api-logging-variables.md)를 참조하세요.
**Example**
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
### 형식 2.0에 대한 Lambda 함수 응답
`2.0` 형식 버전을 선택하는 경우 Lambda 함수에서 부울 값 또는 표준 IAM 정책 구문을 사용하는 IAM 정책을 반환할 수 있습니다. 부울 값을 반환하려면 권한 부여자에 대한 간단한 응답을 활성화합니다. 다음 예제에서는 Lambda 함수에서 반환하도록 코딩해야 하는 형식을 보여줍니다. `context` 객체는 선택 사항입니다. `$context.authorizer.property`를 사용하여 컨텍스트 속성을 Lambda 통합 또는 액세스 로그에 전달할 수 있습니다. 자세한 내용은 [HTTP API 액세스 로그 사용자 정의](http-api-logging-variables.md) 단원을 참조하세요.
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
------
## Lambda 권한 부여자 함수의 예
다음 예제 Node.js Lamdba 함수는 `2.0` 페이로드 형식 버전의 경우 Lambda 함수에서 반환해야 하는 응답 형식을 보여줍니다.
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## 자격 증명 원본
선택적으로 Lambda 권한 부여자에 대한 자격 증명 원본을 지정할 수 있습니다. 자격 증명 원본은 요청에 권한을 부여하는 데 필요한 데이터의 위치를 지정합니다. 예를 들어 헤더 또는 쿼리 문자열 값을 자격 증명 원본으로 지정할 수 있습니다. 자격 증명 원본을 지정하는 경우 클라이언트에서 해당 소스를 요청에 포함해야 합니다. 클라이언트의 요청에 자격 증명 원본이 포함되어 있지 않은 경우 API Gateway는 Lambda 권한 부여자를 호출하지 않으며 클라이언트가 `401` 오류를 수신합니다.
다음 표에서는 Lambda 권한 부여자에 대해 지원되는 자격 증명 소스를 설명합니다.
| **Type** | **예제** | **참고** |
| --- | --- | --- |
| 헤더 값 | \$1request.header.name | 헤더 이름은 대/소문자를 구분하지 않습니다. |
| 쿼리 문자열 값 | \$1request.querystring.name | 쿼리 문자열 이름은 대/소문자를 구분합니다. |
| 컨텍스트 변수 | \$1context.variableName | 지원되는 [컨텍스트 변수](http-api-logging-variables.md)의 값입니다. |
| 단계 변수 | \$1stageVariables.variableName | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
Lambda 함수에서 직접 ` {"errorMessage" : "Unauthorized"}`를 반환하여 클라이언트에 `401` 오류를 반환할 수도 있습니다. Lambda 함수에서 클라이언트로 직접 `401` 오류를 반환하는 경우 Lambda 권한 부여자를 생성할 때 자격 증명 소스를 지정하지 마세요.
## 권한 부여자 응답 캐싱
[authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds)를 지정하여 Lambda 권한 부여자에 대한 캐싱을 활성화할 수 있습니다. 권한 부여자에 대해 캐싱이 활성화되면 API Gateway에서 권한 부여자의 자격 증명 원본을 캐시 키로 사용합니다. 클라이언트가 구성된 TTL 내의 자격 증명 원본에서 동일한 파라미터를 지정하는 경우 API Gateway에서 Lambda 함수를 호출하는 대신 캐싱된 권한 부여자 결과를 사용합니다.
캐싱을 활성화하려면 권한 부여자에게 자격 증명 원본이 하나 이상 있어야 합니다.
권한 부여자에 대해 간단한 응답을 활성화하면 권한 부여자의 응답이 캐싱된 자격 증명 원본 값과 일치하는 모든 API 요청을 완전히 허용하거나 거부합니다. 보다 세분화된 권한이 필요한 경우 간단한 응답을 비활성화하고 IAM 정책을 반환합니다. 권한 부여자에 따라 IAM 정책이 여러 리소스에 대한 액세스를 제어해야 할 수 있습니다.
기본적으로 API Gateway에서는 권한 부여자를 사용하는 API의 모든 라우팅에 캐싱된 권한 부여자 응답을 사용합니다. 라우팅별로 응답을 캐싱하려면 권한 부여자의 자격 증명 원본에 `$context.routeKey`를 추가합니다.
## Lambda 권한 부여자 만들기
Lambda 권한 부여자를 만들 때 API Gateway에 사용할 Lambda 함수를 지정합니다. 함수의 리소스 정책 또는 IAM 역할을 사용하여 Lambda 함수를 호출할 수 있는 권한을 API Gateway에 부여해야 합니다. 다음 [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) 명령은 Lambda 권한 부여자를 생성합니다.
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
다음 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령은 Lambda 함수의 리소스 정책을 업데이트하여 API Gateway에 함수를 호출할 수 있는 권한을 부여합니다. API Gateway에 함수를 호출할 수 있는 권한이 없으면 클라이언트가 `500 Internal Server Error`를 수신합니다.
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
권한 부여자를 생성하고 이를 호출할 수 있는 권한을 API Gateway에 부여한 후에는 권한 부여자를 사용하도록 라우팅을 업데이트합니다. 다음 [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) 명령은 Lambda 권한 부여자를 경로에 추가합니다. Lambda 권한 부여자가 정책 캐싱을 사용하는 경우 정책을 업데이트하여 추가 경로에 대한 액세스를 제어해야 합니다.
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Lambda 권한 부여자 문제 해결
API Gateway에서 Lambda 권한 부여자를 호출할 수 없거나 Lambda 권한 부여자가 잘못된 형식으로 응답을 반환하는 경우 클라이언트가 `500 Internal Server Error`를 수신합니다.
오류를 해결하려면 API 스테이지에 대한 [액세스 로깅을 활성화](http-api-logging.md)합니다. 로그 형식에 `$context.authorizer.error` 로깅 변수를 포함합니다.
로그에 API Gateway가 함수를 호출할 권한이 없다고 표시되면 함수의 리소스 정책을 업데이트하거나 권한 부여자를 호출할 수 있는 권한을 API Gateway에 부여하는 IAM 역할을 제공합니다.
로그에 Lambda 함수가 잘못된 응답을 반환한다고 표시되면 Lambda 함수가 [필요한 형식](#http-api-lambda-authorizer.payload-format-response)으로 응답을 반환하는지 확인합니다.
# API Gateway에서 JWT 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어
JWT(JSON Web Token)를 [OIDC(OpenID Connect)](https://openid.net/specs/openid-connect-core-1_0.html) 및 [OAuth 2.0](https://oauth.net/2/) 프레임워크의 일부로 사용하여 API에 대한 클라이언트 액세스를 제한할 수 있습니다.
API의 경로에 대해 JWT 권한 부여자를 구성하면 API Gateway는 클라이언트가 API 요청과 함께 제출하는 JWT를 검증합니다. API Gateway는 토큰 검증 및 선택적으로 토큰의 범위를 기반으로 요청을 허용하거나 거부합니다. 경로의 범위를 구성하는 경우 토큰에 경로의 범위 중 하나 이상이 포함되어야 합니다.
API의 각 경로에 대해 고유한 권한 부여자를 구성하거나, 여러 경로에 대해 동일한 권한 부여자를 사용할 수 있습니다.
**참고**
OpenID Connect ID 토큰과 같은 기타 유형의 JWT와 JWT 액세스 토큰을 구별하는 표준 메커니즘은 없습니다. API 인증에 ID 토큰이 필요하지 않은 경우 인증 범위가 필요하도록 경로를 구성하는 것이 좋습니다. 자격 증명 공급자가 JWT 액세스 토큰을 발급할 때만 사용하는 발급자 또는 대상 그룹이 필요하도록 JWT 권한 부여자를 구성할 수도 있습니다.
## JWT 권한 부여자를 통한 API 요청 승인
API Gateway는 다음과 같은 일반 워크플로우를 사용하여 JWT 권한 부여자를 사용하도록 구성된 라우팅에 대한 요청을 승인합니다.
1. 토큰에 대한 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource)를 확인합니다. `identitySource`에는 토큰만 포함하거나 `Bearer` 접두사가 붙은 토큰만 포함될 수 있습니다.
1. 토큰을 디코딩합니다.
1. 발행자의 `jwks_uri`에서 가져온 퍼블릭 키를 사용하여 토큰의 알고리즘과 서명을 확인합니다. 현재 RSA 기반 알고리즘만 지원됩니다. API Gateway는 퍼블릭 키를 2시간 동안 캐시할 수 있습니다. 가장 좋은 방법은 키를 교체할 때 이전 키와 새 키가 모두 유효한 유예 기간을 두는 것입니다.
1. 클레임을 검증합니다. API Gateway는 다음 토큰 클레임을 평가합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5) – 토큰에는 토큰에 서명한 `jwks_uri`의 키와 일치하는 헤더 클레임이 있어야 합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) – 권한 부여자에 대해 구성된 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)와 일치해야 합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) 또는 `client_id` – 권한 부여자에 대해 구성된 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) 항목 중 하나와 일치해야 합니다. API 게이트웨이는 `aud`가 없는 경우에만 `client_id`의 유효성을 검사합니다. `aud`와 `client_id`가 모두 있는 경우 API Gateway는 `aud`를 평가합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – 현재 시간(UTC 기준) 이후여야 합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – 현재 시간(UTC 기준) 이전이어야 합니다.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – 현재 시간(UTC 기준) 이전이어야 합니다.
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) 또는 `scp` – 토큰에 라우팅의 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) 범위 중 하나 이상이 포함되어야 합니다.
이러한 단계 중 하나가 실패하면 API Gateway는 API 요청을 거부합니다.
JWT를 검증한 후 API Gateway는 토큰의 클레임을 API 경로의 통합에 전달합니다. Lambda 함수와 같은 백엔드 리소스는 JWT 클레임에 액세스할 수 있습니다. 예를 들어, JWT에 자격 증명 클레임 `emailID`가 포함된 경우 `$event.requestContext.authorizer.jwt.claims.emailID`의 Lambda 통합에 해당 클레임을 사용할 수 있습니다. API Gateway가 Lambda 통합으로 보내는 페이로드에 대한 자세한 내용은 [API Gateway에서 HTTP API에 대한 AWS Lambda 프록시 통합 생성](http-api-develop-integrations-lambda.md) 단원을 참조하세요.
## JWT 권한 부여자 생성
JWT 권한 부여자를 생성하기 전에 클라이언트 애플리케이션을 자격 증명 공급자에 등록해야 합니다. 또한 HTTP API를 생성해야 합니다. HTTP API 생성 예제는 [HTTP API 생성](http-api-develop.md#http-api-examples) 단원을 참조하세요.
### 콘솔을 사용하여 JWT 권한 부여자를 생성하려는 경우
다음 단계는 콘솔을 사용하여 JWT 권한 부여자를 생성하는 방법을 보여줍니다.
**콘솔을 사용하여 JWT 권한 부여자를 생성하려는 경우**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. 기본 탐색 창에서 **권한 부여자**를 선택합니다.
1. **권한 부여자 관리** 탭을 선택합니다.
1. **생성(Create)**을 선택합니다.
1. **권한 부여자 유형**으로는 **JWT**를 선택합니다.
1. JWT 권한 부여자를 구성하고 토큰 소스를 정의하는 ID **소스**를 지정합니다.
1. **생성(Create)**을 선택합니다.
#### AWS CLI를 사용하여 사용자 지정 권한 부여자 생성
다음 [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) 명령은 JWT 권한 부여자를 생성합니다. `jwt-configuration`의 경우 ID 공급자에 대한 `Audience`와 `Issuer`를 지정합니다. Amazon Cognito를 ID 공급자로 사용하는 경우 `IssuerUrl`은 `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`입니다.
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### AWS CloudFormation을 사용하여 JWT 권한 부여자 생성
다음 CloudFormation 템플릿은 Amazon Cognito를 ID 공급자로 사용하는 JWT 권한 부여자를 사용하여 HTTP API를 만듭니다.
CloudFormation 템플릿의 출력은 Amazon Cognito 호스팅 UI의 URL로, 클라이언트가 가입하고 로그인하여 JWT를 받을 수 있습니다. 클라이언트가 로그인하면 URL에 액세스 토큰이 있는 HTTP API로 클라이언트가 리디렉션됩니다. 액세스 토큰으로 API를 간접 호출하려면 토큰을 쿼리 문자열 파라미터로 사용하도록 URL의 `#`를 `?`로 변경하세요.
##### 예제 CloudFormation 템플릿
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## CLI를 사용하여 JWT 권한 부여자를 사용하도록 경로 업데이트
콘솔, AWS CLI, 또는 AWS SDK를 사용하여 JWT 권한 부여자를 사용하도록 경로를 업데이트할 수 있습니다.
### 콘솔을 사용하여 JWT 권한 부여자를 사용하도록 경로 업데이트
다음 단계는 콘솔을 사용하여 JWT 권한 부여자를 사용하도록 경로를 업데이트하는 방법을 보여줍니다.
**콘솔을 사용하여 JWT 권한 부여자를 생성하는 경우**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. 기본 탐색 창에서 **권한 부여자**를 선택합니다.
1. 방법을 선택한 다음 드롭다운 메뉴에서 권한 부여자를 선택하고 **권한 부여자**을 선택합니다.
#### AWS CLI를 사용하여 JWT 권한 부여자를 사용하도록 경로 업데이트
다음 [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) 명령은 JWT 권한 부여자를 사용하도록 경로를 업데이트합니다.
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# API Gateway에서 IAM 권한 부여를 통해 HTTP API에 대한 액세스 제어
HTTP API 라우팅에 대해 IAM 권한 부여를 활성화할 수 있습니다. IAM 권한 부여가 활성화된 경우 클라이언트는 [Signature Version 4(SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)를 사용하여 AWS 자격 증명으로 요청에 서명해야 합니다. API Gateway는 클라이언트가 라우팅에 대한 `execute-api` 권한을 가진 경우에만 API 라우팅을 호출합니다.
HTTP API에 대한 IAM 권한 부여는 [REST API](api-gateway-control-access-using-iam-policies-to-invoke-api.md)에 대한 권한 부여와 유사합니다.
**참고**
리소스 정책은 현재 HTTP API에 대해 지원되지 않습니다.
클라이언트에 API 호출 권한을 부여하는 IAM 정책의 예는 [API 호출을 위한 액세스 제어](api-gateway-control-access-using-iam-policies-to-invoke-api.md) 단원을 참조하세요.
## 라우팅에 대한 IAM 권한 부여 활성화
다음 [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) 명령은 HTTP API 경로에 대한 IAM 권한 부여를 활성화합니다.
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# API Gateway에서 HTTP API 통합 생성
*통합*은 라우팅을 백엔드 리소스에 연결합니다. HTTP API는 Lambda 프록시, AWS 서비스 및 HTTP 프록시 통합을 지원합니다. 예를 들어, 가입 고객을 처리하는 Lambda 함수와 통합하도록 API의 `POST` 경로에 대한 `/signup` 요청을 구성할 수 있습니다.
**Topics**
+ [
# API Gateway에서 HTTP API에 대한 AWS Lambda 프록시 통합 생성
](http-api-develop-integrations-lambda.md)
+ [
# HTTP API에 대한 HTTP 프록시 통합 생성
](http-api-develop-integrations-http.md)
+ [
# API Gateway에서 HTTP API에 대한 AWS 서비스 통합 생성
](http-api-develop-integrations-aws-services.md)
+ [
# API Gateway에서 HTTP API에 대한 프라이빗 통합 생성
](http-api-develop-integrations-private.md)
# API Gateway에서 HTTP API에 대한 AWS Lambda 프록시 통합 생성
Lambda 프록시 통합을 사용하면 API 라우팅을 Lambda 함수와 통합할 수 있습니다. 클라이언트가 API를 호출하면 API Gateway는 Lambda 함수에 요청을 전송하고 함수의 응답을 클라이언트에 반환합니다. HTTP API 생성 예제는 [HTTP API 생성](http-api-develop.md#http-api-examples) 단원을 참조하세요.
## 페이로드 형식 버전
페이로드 형식 버전은 API Gateway에서 Lambda 통합으로 전송하는 이벤트의 형식과 API Gateway에서 Lambda의 응답을 해석하는 방법을 지정합니다. 페이로드 형식 버전을 지정하지 않으면 AWS Management Console에서는 기본적으로 최신 버전을 사용합니다. AWS CLI, CloudFormation 또는 SDK를 사용하여 Lambda 통합을 생성하는 경우 `payloadFormatVersion`을 지정해야 합니다. 지원되는 값은 `1.0` 및 `2.0`입니다.
`payloadFormatVersion`을 설정하는 방법에 대한 자세한 내용은 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html)을 참조합니다. 기존 통합의 `payloadFormatVersion`을 결정하는 방법에 대한 자세한 내용은 [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html)을 참조하세요.
### 페이로드 형식 차이
다음 목록은 페이로드 형식 버전 `1.0`과 `2.0` 간의 차이점을 보여줍니다.
+ 형식 `2.0`에는 `multiValueHeaders` 또는 `multiValueQueryStringParameters` 필드가 없습니다. 중복 헤더는 쉼표로 결합되어 `headers` 필드에 포함됩니다. 중복 쿼리 문자열은 쉼표로 결합되어 `queryStringParameters` 필드에 포함됩니다.
+ `2.0` 형식은 `rawPath`를 갖습니다. API 매핑을 사용하여 스테이지를 사용자 지정 도메인 이름에 연결하는 경우 `rawPath`에서 API 매핑 값을 제공하지 않습니다. `1.0` 및 `path` 형식을 사용하여 사용자 지정 도메인 이름의 API 매핑에 액세스할 수 있습니다.
+ 형식 `2.0`에는 새 `cookies` 필드가 포함됩니다. 요청의 모든 쿠키 헤더는 쉼표로 결합되어 `cookies` 필드에 추가됩니다. 클라이언트에 대한 응답에서 각 쿠키는 `set-cookie` 헤더가 됩니다.
### 페이로드 형식 구조
다음 예제에서는 각 페이로드 형식 버전의 구조를 보여 줍니다. 모든 헤더 이름은 소문자입니다.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "192.0.2.1",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
------
## Lambda 함수 응답 형식
페이로드 형식 버전은 Lambda 함수가 반환해야 하는 응답 구조를 결정합니다.
### 형식 1.0에 대한 Lambda 함수 응답
`1.0` 형식 버전에서는 Lambda 통합이 다음 JSON 형식으로 응답을 반환해야 합니다.
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### 형식 2.0에 대한 Lambda 함수 응답
`2.0` 형식 버전을 사용하면 API Gateway가 응답 형식을 추론할 수 있습니다. API Gateway는 Lambda 함수가 유효한 JSON을 반환하고 `statusCode`을 반환하지 않는 경우 다음과 같은 가정을 합니다.
+ `isBase64Encoded`은 `false`입니다.
+ `statusCode`은 `200`입니다.
+ `content-type`은 `application/json`입니다.
+ `body`은 함수의 응답입니다.
다음 예제는 Lambda 함수의 출력과 API Gateway의 해석을 보여 줍니다.
| Lambda 함수 출력 | API Gateway 해석 |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
응답을 사용자 지정하려면 Lambda 함수가 다음 형식의 응답을 반환해야 합니다.
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# HTTP API에 대한 HTTP 프록시 통합 생성
HTTP 프록시 통합을 사용하면 API 라우팅을 공개적으로 라우팅할 수 있는 HTTP 엔드포인트에 연결할 수 있습니다. 이 통합 유형에서는 API Gateway가 프런트 엔드와 백엔드 사이에 전체 요청 및 응답을 전달합니다.
HTTP 통합을 생성하려면 공개적으로 라우팅할 수 있는 HTTP 엔드포인트의 URL을 제공합니다.
## 경로 변수와의 HTTP 프록시 통합
HTTP API 라우팅에서 경로 변수를 사용할 수 있습니다.
예를 들어 라우팅 `/pets/{petID}`은 `/pets/6`에 대한 요청을 포착합니다. 통합 URI의 경로 변수를 참조하여 변수의 내용을 통합에 전송할 수 있습니다. 예를 들면, `/pets/extendedpath/{petID}`입니다.
복잡한 경로 변수를 사용하여 라우팅의 모든 자식 리소스를 포착할 수 있습니다. 복잡한 경로 변수를 생성하려면 변수 이름에 `+`를 추가합니다(예: `{proxy+}`).
모든 요청을 포착하는 HTTP 프록시 통합으로 라우팅을 설정하려면 복잡한 경로 변수(예: `/parent/{proxy+}`)를 사용하여 API 라우팅을 생성합니다. `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}` 메서드에서 HTTP 엔드포인트(예: `ANY`)에 라우팅을 통합합니다. 복잡한 경로 변수는 리소스 경로의 끝에 있어야 합니다.
# API Gateway에서 HTTP API에 대한 AWS 서비스 통합 생성
*1급 통합*을 사용하여 AWS 서비스와 HTTP API를 통합할 수 있습니다. 1급 통합은 HTTP API 경로를 AWS 서비스 API에 연결합니다. 클라이언트가 1급 통합이 지원되는 경로를 호출하면 API Gateway에서 AWS 서비스 API를 자동으로 호출합니다. 예를 들어 1급 통합을 사용하여 Amazon Simple Queue Service 대기열에 메시지를 보내거나 AWS Step Functions 상태 시스템을 시작할 수 있습니다. 지원되는 서비스 작업은 [통합 하위 유형 참조](http-api-develop-integrations-aws-services-reference.md) 단원을 참조하세요.
## 매핑 요청 파라미터
1급 통합에는 필수 및 선택적 파라미터가 사용됩니다. 통합을 생성하려면 필요한 모든 파라미터를 구성해야 합니다. 정적 값을 사용하거나 실행 시간에 동적으로 평가되는 파라미터를 매핑할 수 있습니다. 지원되는 통합 및 파라미터의 전체 목록은 [통합 하위 유형 참조](http-api-develop-integrations-aws-services-reference.md) 단원을 참조하세요.
다음 표에서는 지원되는 매핑 요청 파라미터를 설명합니다.
| 유형 | 예 | 참고 |
| --- | --- | --- |
| 헤더 값 | \$1request.header.name | 헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2"). |
| 쿼리 문자열 값 | \$1request.querystring.name | 쿼리 문자열 이름은 대/소문자를 구분합니다. API Gateway는 쉼표를 사용하여 여러 값을 결합합니다(예: "querystring1": "Value1,Value2"). |
| 경로 파라미터 | \$1request.path.name | 요청에 포함된 경로 파라미터의 값입니다. 예를 들어 라우팅이 /pets/\$1petId\$1인 경우 요청의 petId 파라미터를 \$1request.path.petId로 매핑할 수 있습니다. |
| 요청 본문 패스스루 | \$1request.body | API Gateway는 전체 요청 본문을 전달합니다. |
| 요청 본문 | \$1request.body.name | [JSON 경로 표현식](https://goessner.net/articles/JsonPath/index.html#e2). 재귀적 하강(\$1request.body..name) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 요청 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$request.body`을(를) 지정합니다. |
| 컨텍스트 변수 | \$1context.variableName | 지원되는 [컨텍스트 변수](http-api-logging-variables.md)의 값입니다. |
| 단계 변수 | \$1stageVariables.variableName | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
| 정적 값 | string | 상수 값입니다. |
## 1급 통합 생성
1급 통합을 생성하기 전에 통합 중인 AWS 서비스 작업을 호출할 수 있는 권한을 API Gateway에 부여하는 IAM 역할을 생성해야 합니다. 자세한 내용은 [AWS 서비스에 대한 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)을 참조하세요.
1급 통합을 생성하려면 지원되는 AWS 서비스 작업(예: `SQS-SendMessage`)을 선택하고, 요청 파라미터를 구성하고, 통합된 AWS 서비스 API를 호출할 수 있는 권한을 API Gateway에 부여하는 역할을 제공합니다. 통합 하위 유형에 따라 다른 요청 파라미터가 필요합니다. 자세한 내용은 [통합 하위 유형 참조](http-api-develop-integrations-aws-services-reference.md) 단원을 참조하세요.
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 Amazon SQS 메시지를 보내는 통합을 생성합니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## CloudFormation를 사용하여 1급 통합 생성
다음 예시는 Amazon EventBridge과의 최고 수준의 통합을 통해 `/{source}/{detailType}` 경로를 생성하는 CloudFormation 스니펫을 보여줍니다.
`Source` 파라미터는 `{source}` 경로 파라미터에 매핑되고, `DetailType`는 `{DetailType}` 경로 파라미터에 매핑되며, `Detail` 파라미터는 요청 본문에 매핑됩니다.
이 스니펫에는 API Gateway에 `PutEvents` 작업을 간접 호출할 권한을 부여하는 이벤트 버스 또는 IAM 역할이 표시되지 않습니다.
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# 통합 하위 유형 참조
HTTP API에 지원되는 [통합 하위 유형](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype)은 다음과 같습니다.
**Topics**
+ [
## EventBridge-PutEvents 1.0
](#EventBridge-PutEvents)
+ [
## SQS-SendMessage 1.0
](#SQS-SendMessage)
+ [
## SQS-ReceiveMessage 1.0
](#SQS-ReceiveMessage)
+ [
## SQS-DeleteMessage 1.0
](#SQS-DeleteMessage)
+ [
## SQS-PurgeQueue 1.0
](#SQS-PurgeQueue)
+ [
## AppConfig-GetConfiguration 1.0
](#AppConfig-GetConfiguration)
+ [
## Kinesis-PutRecord 1.0
](#Kinesis-PutRecord)
+ [
## StepFunctions-StartExecution 1.0
](#StepFunctions-StartExecution)
+ [
## StepFunctions-StartSyncExecution 1.0
](#StepFunctions-StartSyncExecution)
+ [
## StepFunctions-StopExecution 1.0
](#StepFunctions-StopExecution)
## EventBridge-PutEvents 1.0
규칙에 일치시킬 수 있도록 사용자 지정 이벤트를 Amazon EventBridge로 보냅니다.
| 파라미터 | 필수 |
| --- | --- |
| 세부 정보 | True |
| DetailType | True |
| 소스 | True |
| 시간 | False |
| EventBusName | False |
| 리소스 | False |
| Region | False |
| TraceHeader | False |
자세한 내용은 *Amazon EventBridge API 참조*의 [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html)를 참조하세요.
## SQS-SendMessage 1.0
메시지를 지정된 대기열에 전달합니다.
| 파라미터 | 필수 |
| --- | --- |
| QueueUrl | True |
| MessageBody | True |
| DelaySeconds | False |
| MessageAttributes | False |
| MessageDeduplicationId | False |
| MessageGroupId | False |
| MessageSystemAttributes | False |
| Region | False |
자세한 내용은 *Amazon Simple Queue Service API 참조*의 [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)를 참조하세요.
## SQS-ReceiveMessage 1.0
지정된 대기열에서 하나 이상의 메시지(최대 10개)를 가져옵니다.
| 파라미터 | 필수 |
| --- | --- |
| QueueUrl | True |
| AttributeNames | False |
| MaxNumberOfMessages | False |
| MessageAttributeNames | False |
| ReceiveRequestAttemptId | False |
| VisibilityTimeout | False |
| WaitTimeSeconds | False |
| Region | False |
자세한 내용은 *Amazon Simple Queue Service API 참조*의 [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)를 참조하세요.
## SQS-DeleteMessage 1.0
지정된 대기열에서 지정된 메시지를 삭제합니다.
| 파라미터 | 필수 |
| --- | --- |
| ReceiptHandle | True |
| QueueUrl | True |
| Region | False |
자세한 내용은 *Amazon Simple Queue Service API 참조*의 [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)를 참조하세요.
## SQS-PurgeQueue 1.0
지정된 대기열의 모든 메시지를 삭제합니다.
| 파라미터 | 필수 |
| --- | --- |
| QueueUrl | True |
| Region | False |
자세한 내용은 *Amazon Simple Queue Service API 참조*의 [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html)를 참조하세요.
## AppConfig-GetConfiguration 1.0
구성에 대한 정보를 수신합니다.
| 파라미터 | 필수 |
| --- | --- |
| 애플리케이션 | True |
| Environment | True |
| Configuration | True |
| ClientId | True |
| ClientConfigurationVersion | False |
| Region | False |
자세한 내용은 *AWS AppConfig API 참조*의 [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html)을 참조하세요.
## Kinesis-PutRecord 1.0
단일 데이터 레코드를 Amazon Kinesis 데이터 스트림에 씁니다.
| 파라미터 | 필수 |
| --- | --- |
| StreamName | True |
| Data | True |
| PartitionKey | True |
| SequenceNumberForOrdering | False |
| ExplicitHashKey | False |
| Region | False |
자세한 내용은 *Amazon Kinesis Data Streams API 참조*의 [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)를 참조하세요.
## StepFunctions-StartExecution 1.0
상태 시스템 실행을 시작합니다.
| 파라미터 | 필수 |
| --- | --- |
| StateMachineArn | True |
| 이름 | False |
| 입력 | False |
| Region | False |
자세한 내용은 *AWS Step Functions API 참조*의 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)을 참조하세요.
## StepFunctions-StartSyncExecution 1.0
동기 상태 시스템 실행을 시작합니다.
| 파라미터 | 필수 |
| --- | --- |
| StateMachineArn | True |
| 이름 | False |
| 입력 | False |
| Region | False |
| TraceHeader | False |
자세한 내용은 *AWS Step Functions API 참조*의 [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)을 참조하세요.
## StepFunctions-StopExecution 1.0
실행을 중지합니다.
| 파라미터 | 필수 |
| --- | --- |
| ExecutionArn | True |
| 원인 | False |
| 오류 | False |
| Region | False |
자세한 내용은 *AWS Step Functions API 참조*의 [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)을 참조하세요.
# API Gateway에서 HTTP API에 대한 프라이빗 통합 생성
프라이빗 통합을 사용하면 VPC의 프라이빗 리소스(예: Application Load Balancer 또는 Amazon ECS 컨테이너 기반 애플리케이션)와의 API 통합을 생성할 수 있습니다.
프라이빗 통합을 사용하여 VPC 외부의 클라이언트가 액세스할 수 있도록 VPC에 리소스를 노출할 수 있습니다. API Gateway가 지원하는 [권한 부여 방법](http-api-access-control.md)을 사용하여 API에 대한 액세스를 제어할 수 있습니다.
**참고**
프라이빗 통합을 생성하려면 먼저 VPC 링크를 생성해야 합니다. VPC 링크 V2는 이제 HTTP와 REST API 모두에서 지원됩니다. VPC 링크 V2에 대한 자세한 내용은 [API Gateway에서 VPC 링크 V2 설정](apigateway-vpc-links-v2.md) 섹션을 참조하세요.
VPC 링크 V2를 생성한 후에는 Application Load Balancer, Network Load Balancer 또는 AWS Cloud Map 서비스에 등록된 리소스에 연결되는 프라이빗 통합을 설정할 수 있습니다.
## 고려 사항
다음 고려 사항은 프라이빗 통합 사용에 영향을 미칠 수 있습니다.
+ 모든 리소스는 동일한 AWS 계정에서 소유해야 합니다. 여기에는 로드 밸런서 또는 AWS Cloud Map 서비스, VPC 링크 및 HTTP API가 포함됩니다.
+ 기본적으로 프라이빗 통합 트래픽은 HTTP 프로토콜을 사용합니다. HTTPS를 사용하려면 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html)를 지정합니다. AWS Management Console을 사용하여 이 작업을 수행하려면 프라이빗 통합을 생성할 때 **고급 설정**을 선택한 다음 보안 서버 이름을 입력합니다.
+ 프라이빗 통합의 경우 API Gateway에서 백엔드 리소스에 대한 요청에 API 엔드포인트의 [스테이지](http-api-stages.md) 부분을 포함합니다. 예를 들어 API `test` 스테이지에 대한 요청은 프라이빗 통합 요청에 `test/route-path`를 포함합니다. 백엔드 리소스에 대한 요청에서 단계 이름을 제거하려면 [파라미터 매핑](http-api-parameter-mapping.md)을 사용하여 요청 경로를 `$request.path`에 덮어씁니다.
## Application Load Balancer 또는 Network Load Balancer를 사용하여 프라이빗 통합 생성
프라이빗 통합을 생성하기 전에 VPC 링크 V2를 생성해야 합니다. VPC 링크 V2에 대한 자세한 내용은 [API Gateway에서 VPC 링크 V2 설정](apigateway-vpc-links-v2.md) 섹션을 참조하세요.
Application Load Balancer 또는 Network Load Balancer에서 프라이빗 통합을 생성하려면 HTTP 프록시 통합을 생성하고, 사용할 VPC 링크를 지정하고, 로드 밸런서의 리스너 ARN을 제공합니다.
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 VPC 링크를 통해 로드 밸런서에 연결하는 프라이빗 통합을 생성합니다.
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## AWS Cloud Map 서비스 검색을 사용하여 프라이빗 통합 생성
프라이빗 통합을 생성하기 전에 VPC 링크 V2를 생성해야 합니다. VPC 링크에 대한 자세한 내용은 [API Gateway에서 VPC 링크 V2 설정](apigateway-vpc-links-v2.md) 단원을 참조하세요 .
AWS Cloud Map와의 통합을 위해 API Gateway는 `DiscoverInstances`를 사용하여 리소스를 식별합니다. 쿼리 파라미터를 사용하여 특정 리소스를 대상으로 지정할 수 있습니다. 등록된 리소스의 속성에는 IP 주소와 포트가 포함되어야 합니다. API Gateway는 `DiscoverInstances`에서 반환된 정상 리소스에 요청을 분산합니다. 자세한 내용은 AWS Cloud Map API 참조의 [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html)를 참조하세요.
**참고**
Amazon ECS를 사용하여 AWS Cloud Map의 항목을 채우는 경우 Amazon ECS 서비스 검색과 함께 SRV 레코드를 사용하도록 Amazon ECS 작업을 구성하거나 Amazon ECS Service Connect를 활성화해야 합니다. 자세한 내용은 Amazon Elastic Container Service 개발자 안내서의 [서비스 상호 연결](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html)을 참조하세요.
AWS Cloud Map과의 프라이빗 통합을 생성하려면 HTTP 프록시 통합을 생성하고, 사용할 VPC 링크를 지정하고, AWS Cloud Map 서비스의 ARN을 제공합니다.
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 AWS Cloud Map 서비스 검색을 통해 리소스를 식별하는 프라이빗 통합을 생성합니다.
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# API Gateway에서 HTTP API CORS 구성
[CORS(Cross-Origin Resource Sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)는 브라우저에서 실행 중인 스크립트에서 시작되는 HTTP 요청을 제한하는 브라우저 보안 기능입니다. API에 액세스할 수 없고 `Cross-Origin Request Blocked`가 포함된 오류 메시지를 수신하는 경우 CORS를 활성화해야 할 수 있습니다. 자세한 내용은 [CORS란 무엇인가요?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)를 참조하세요.
CORS는 일반적으로 다른 도메인이나 오리진에 호스팅된 API에 액세스하는 웹 애플리케이션을 빌드하는 데 필요합니다. CORS를 활성화하여 다른 도메인에 호스팅된 웹 애플리케이션에서 API에 대한 요청을 허용할 수 있습니다. 예를 들어, API가 `https://{api_id}.execute-api.{region}.amazonaws.com/`에 호스팅되고 `example.com`에 호스팅된 웹 애플리케이션에서 API를 호출하려는 경우 API가 CORS를 지원해야 합니다.
API에 대해 CORS를 구성하면 API Gateway는 API에 대해 구성된 OPTIONS 경로가 없더라도 preflight OPTIONS 요청에 대한 응답을 자동으로 전송합니다. CORS 요청의 경우 API Gateway는 구성된 CORS 헤더를 통합의 응답에 추가합니다.
**참고**
API에 대해 CORS를 구성하는 경우, API Gateway는 백엔드 통합에서 반환된 CORS 헤더를 무시합니다.
CORS 구성에서 다음과 같은 매개 변수를 지정할 수 있습니다. API Gateway HTTP API 콘솔을 사용하여 이러한 파라미터를 추가하려면 값을 입력한 후 **추가**를 선택합니다.
| CORS 헤더 | CORS 구성 속성 | 예제 값 |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Headers | exposeHeaders | date, x-api-id, \$1 |
| Access-Control-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE, \$1 |
| Access-Control-Allow-Headers | allowHeaders | authorization, \$1 |
CORS 헤더를 반환하려면 요청에 `origin` 헤더가 포함되어야 합니다. `OPTIONS` 메서드의 경우 요청에 `origin` 헤더와 `Access-Control-Request-Method` 헤더가 포함되어야 합니다.
CORS 구성은 다음과 비슷할 수 있습니다.
![\[HTTP API에 대한 CORS 구성\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/http-cors-console.png)
## `$default` 라우팅 및 권한 부여자가 포함된 HTTP API에 CORS 구성
CORS를 활성화하고 HTTP API의 모든 라우팅에 대한 권한 부여를 구성할 수 있습니다. [`$default` 라우팅](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default)에 대한 CORS 및 권한 부여를 활성화하는 경우 고려할 몇 가지 사항이 있습니다. `$default` 라우팅은 `OPTIONS` 요청을 포함하여 명시적으로 정의되지 않은 모든 메서드 및 라우팅에 대한 요청을 포착합니다. 권한 부여되지 않은 `OPTIONS` 요청을 지원하려면 `OPTIONS /{proxy+}` 라우팅을 권한 부여가 필요하지 않은 API에 추가하고 통합을 라우팅에 연결합니다. `OPTIONS /{proxy+}` 라우팅이 `$default` 라우팅보다 우선 순위가 높습니다. 따라서 클라이언트가 권한 부여 없이 API에 `OPTIONS` 요청을 제출할 수 있습니다. 라우팅 우선 순위에 대한 자세한 내용은 [API 요청 라우팅](http-api-develop-routes.md#http-api-develop-routes.evaluation) 단원을 참조하세요.
## AWS CLI를 사용하여 HTTP API에 대한 CORS 구성
다음 [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) 명령은 `https://www.example.com`의 CORS 요청을 활성화할 수 있습니다.
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
자세한 내용은 Amazon API Gateway 버전 2 API 참조의 [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors)를 참조하세요.
# API Gateway에서 HTTP API에 대한 API 요청 및 응답 변환
백엔드 통합에 도달하기 전에 클라이언트의 API 요청을 수정할 수 있습니다. API Gateway가 클라이언트에 응답을 반환하기 전에 통합에서 응답을 변경할 수도 있습니다. *파라미터 매핑*을 사용하여 HTTP API에 대한 API 요청 및 응답을 수정합니다. 파라미터 매핑을 사용하려면 수정할 API 요청 또는 응답 파라미터를 지정하고 이러한 파라미터를 수정하는 방법을 지정합니다.
## API 요청 변환
요청 파라미터를 사용하여 요청이 백엔드 통합에 도달하기 전에 요청을 변경합니다. 헤더, 쿼리 문자열 또는 요청 경로를 수정할 수 있습니다.
요청 파라미터는 키-값 맵입니다. 키는 변경할 요청 파라미터의 위치와 변경 방법을 식별합니다. 이 값은 파라미터에 대한 새 데이터를 지정합니다.
다음 표에는 지원되는 키가 나와 있습니다.
| 유형 | 구문 |
| --- | --- |
| 헤더 | append\$1overwrite\$1remove:header.headername |
| 쿼리 문자열 | append\$1overwrite\$1remove:querystring.querystring-name |
| 경로 | overwrite:path |
다음 표에서는 파라미터에 매핑할 수 있는 지원되는 값을 보여 줍니다.
| 유형 | 구문 | 참고 |
| --- | --- | --- |
| 헤더 값 | \$1request.header.name 또는 \$1\$1request.header.name\$1 | 헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2"). 일부 헤더는 예약되어 있습니다. 자세한 내용은 [예약된 헤더](#http-api-mapping-reserved-headers) 단원을 참조하세요. |
| 쿼리 문자열 값 | \$1request.querystring.name 또는 \$1\$1request.querystring.name\$1 | 쿼리 문자열 이름은 대/소문자를 구분합니다. API Gateway는 쉼표를 사용하여 여러 값을 결합합니다(예: "querystring1" "Value1,Value2"). |
| 요청 본문 | \$1request.body.name 또는 \$1\$1request.body.name\$1 | JSON 경로 표현식입니다. 재귀적 하강(\$1request.body..name)) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 요청 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$request.body`을(를) 지정합니다. |
| 요청 경로 | \$1request.path 또는 \$1\$1request.path\$1 | 단계 이름이 없는 요청 경로입니다. |
| 경로 파라미터 | \$1request.path.name 또는 \$1\$1request.path.name\$1 | 요청에 포함된 경로 파라미터의 값입니다. 예를 들어 라우팅이 /pets/\$1petId\$1인 경우 요청의 petId 파라미터를 \$1request.path.petId(으)로 매핑할 수 있습니다. |
| 컨텍스트 변수 | \$1context.variableName 또는 \$1\$1context.variableName\$1 | [컨텍스트 변수](http-api-logging-variables.md)의 값입니다.특수 문자 `.` 및 `_`만 지원됩니다. |
| 단계 변수 | \$1stageVariables.variableName 또는 \$1\$1stageVariables.variableName\$1 | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
| 정적 값 | string | 상수 값입니다. |
**참고**
선택 표현식에 여러 변수를 사용하려면 변수를 괄호로 묶습니다. 예: `${request.path.name} ${request.path.id}`.
## API 응답 변환
응답 파라미터를 사용하여 클라이언트에 응답을 반환하기 전에 백엔드 통합에서 HTTP 응답을 변환합니다. API Gateway가 클라이언트에 응답을 반환하기 전에 응답의 헤더 또는 상태 코드를 수정할 수 있습니다.
통합에서 반환하는 각 상태 코드에 대한 응답 파라미터를 구성합니다. 응답 파라미터는 키-값 맵입니다. 키는 변경할 요청 파라미터의 위치와 변경 방법을 식별합니다. 이 값은 파라미터에 대한 새 데이터를 지정합니다.
다음 표에는 지원되는 키가 나와 있습니다.
| 유형 | 구문 |
| --- | --- |
| 헤더 | append\$1overwrite\$1remove:header.headername |
| 상태 코드 | overwrite:statuscode |
다음 표에서는 파라미터에 매핑할 수 있는 지원되는 값을 보여 줍니다.
| 유형 | 구문 | 참고 |
| --- | --- | --- |
| 헤더 값 | \$1response.header.name 또는 \$1\$1response.header.name\$1 | 헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2"). 일부 헤더는 예약되어 있습니다. 자세한 내용은 [예약된 헤더](#http-api-mapping-reserved-headers) 단원을 참조하세요. |
| 응답 본문 | \$1response.body.name 또는 \$1\$1response.body.name\$1 | JSON 경로 표현식. 재귀적 하강(\$1response.body..name) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 응답 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$response.body`을(를) 지정합니다. |
| 컨텍스트 변수 | \$1context.variableName 또는 \$1\$1context.variableName\$1 | 지원되는 [컨텍스트 변수](http-api-logging-variables.md)의 값입니다. |
| 단계 변수 | \$1stageVariables.variableName 또는 \$1\$1stageVariables.variableName\$1 | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. |
| 정적 값 | string | 상수 값입니다. |
**참고**
선택 표현식에 여러 변수를 사용하려면 변수를 괄호로 묶습니다. 예: `${request.path.name} ${request.path.id}`.
## 예약된 헤더
다음 헤더가 예약되어 있습니다. 이러한 헤더에 대한 요청 또는 응답 매핑은 구성할 수 없습니다.
+ access-control-\$1
+ apigw-\$1
+ 승인
+ 연결
+ Content-Encoding
+ Content-Length
+ Content-Location
+ 전달됨
+ Keep-Alive
+ Origin
+ 프록시-인증
+ Proxy-Authorization
+ TE
+ 트레일러
+ Transfer-Encoding
+ 업그레이드
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## 예시
다음 AWS CLI 예제에서는 파라미터 매핑을 구성합니다. CloudFormation 템플릿 예는 [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates)를 참조하세요.
### API 요청에 헤더 추가
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 백엔드 통합에 도달하기 전에 API 요청에 `header1`이라는 헤더를 생성합니다. API Gateway는 요청 ID로 헤더를 채웁니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### 요청 헤더 이름 바꾸기
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 요청 헤더의 이름을 `header1`에서 `header2`로 변경합니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### 통합에서 응답 변경
다음 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 통합에 대한 응답 파라미터를 구성합니다. 통합에서 500 상태 코드를 반환하면 API Gateway가 상태 코드를 403으로 변경하고 응답에 `header1`1을 추가합니다. 통합에서 404 상태 코드를 반환하면 API Gateway는 응답에 `error` 헤더를 추가합니다.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### 구성된 파라미터 매핑 제거
다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 명령은 `append:header.header1`에 대해 이전에 구성된 요청 파라미터를 제거합니다. 또한 200 상태 코드에 대해 이전에 구성된 응답 파라미터를 제거합니다.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# API Gateway에서 HTTP API에 대한 OpenAPI 정의 사용
OpenAPI 3.0 정의 파일을 사용하여 HTTP API를 정의할 수 있습니다. 그런 다음 정의를 API Gateway로 가져와서 API를 생성할 수 있습니다. OpenAPI로 API Gateway 확장에 대한 자세한 내용은 [API Gateway용 OpenAPI 확장 프로그램](api-gateway-swagger-extensions.md) 단원을 참조하세요.
## HTTP API 가져오기
OpenAPI 3.0 정의 파일을 가져와서 HTTP API를 생성할 수 있습니다.
REST API에서 HTTP API로 마이그레이션하려면 REST API를 OpenAPI 3.0 정의 파일로 내보낼 수 있습니다. 그런 다음 API 정의를 HTTP API로 가져옵니다. REST API 내보내기에 대한 자세한 내용은 [API Gateway에서 REST API 내보내기](api-gateway-export-api.md) 단원을 참조하세요.
**참고**
HTTP API는 REST API와 동일한 AWS 변수를 지원합니다. 자세한 내용은 [AWSOpenAPI 가져오기를 위한 변수](import-api-aws-variables.md) 단원을 참조하세요.
### 검증 정보 가져오기
API를 가져올 때 API Gateway는 세 가지 범주의 검증 정보를 제공합니다.
**Info**
속성은 OpenAPI 사양에 따라 유효하지만, HTTP API에 대해서는 해당 속성이 지원되지 않습니다.
예를 들어, HTTP API는 요청 검증을 지원하지 않으므로 다음 OpenAPI 3.0 코드 조각은 가져오기에 대한 정보를 생성합니다. API Gateway는 `requestBody` 및 `schema` 필드를 무시합니다.
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**경고**
속성 또는 구조는 OpenAPI 사양에 따라 유효하지 않지만, API 생성을 차단하지 않습니다. API Gateway가 이러한 경고를 무시하고 API 생성을 계속할지 또는 경고 시 API 생성을 중지할지를 지정할 수 있습니다.
HTTP API는 Lambda 프록시 및 HTTP 프록시 통합만 지원하므로 다음과 같은 OpenAPI 3.0 문서에서는 가져오기에 대한 경고가 생성됩니다.
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**오류**
OpenAPI 사양이 올바르지 않거나 형식이 잘못되었습니다. API Gateway는 잘못된 형식의 문서에서 리소스를 만들 수 없습니다. 오류를 수정한 다음, 다시 시도해야 합니다.
HTTP API는 OpenAPI 3.0 사양만 지원하므로 다음과 같은 API 정의는 가져올 때 오류가 발생합니다.
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
또 다른 예로 OpenAPI를 사용하면 특정 작업에 연결된 여러 보안 요구 사항이 있는 API를 정의할 수 있지만 API Gateway는 이를 지원하지 않습니다. 각 작업에는 IAM 권한 부여, Lambda 권한 부여자 또는 JWT 권한 부여자가 하나만 있을 수 있습니다. 여러 보안 요구 사항을 모형화하려 시도하면 오류가 발생합니다.
### AWS CLI를 사용하여 API 가져오기
다음 [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) 명령은 OpenAPI 3.0 정의 파일 `api-definition.json`을 HTTP API로 가져옵니다.
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
다음 예제 OpenAPI 3.0 정의를 가져와서 HTTP API를 생성할 수 있습니다.
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# API Gateway에서 HTTP API 내보내기
HTTP API를 생성한 후 API Gateway에서 API의 OpenAPI 3.0 정의를 내보낼 수 있습니다. 내보낼 스테이지를 선택하거나 API의 최신 구성을 내보낼 수 있습니다. 내보낸 API 정의를 API Gateway로 가져와 동일한 또 다른 API를 생성할 수도 있습니다. API 정의 가져오기에 대한 자세한 내용은 [HTTP API 가져오기](http-api-open-api.md#http-api-import) 단원을 참조하세요.
## AWS CLI를 사용하여 스테이지의 OpenAPI 3.0 정의 내보내기
다음 [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) 명령은 `prod`라는 API 스테이지의 OpenAPI 정의를 `stage-definition.yaml`이라는 YAML 파일로 내보냅니다. 내보낸 정의 파일에는 기본적으로 [API Gateway 확장](api-gateway-swagger-extensions.md)이 포함됩니다.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## AWS CLI를 사용하여 API의 최신 변경 사항에 대한 OpenAPI 3.0 정의 내보내기
다음 [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) 명령은 HTTP API의 OpenAPI 정의를 `latest-api-definition.json`이라는 JSON 파일로 내보냅니다. 이 명령은 스테이지를 지정하지 않으므로 API Gateway는 스테이지에 배포되었는지 여부에 관계없이 API의 최신 구성을 내보냅니다. 내보낸 정의 파일에는[API Gateway 확장](api-gateway-swagger-extensions.md)이 포함되지 않습니다.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
자세한 내용은 *Amazon API Gateway 버전 2 API 참조*의 [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods)를 참조하세요.
## API Gateway 콘솔을 사용하여 OpenAPI 3.0 정의 내보내기
다음 절차에서는 HTTP API의 OpenAPI 정의를 내보내는 방법을 보여줍니다.
**API Gateway 콘솔을 사용하여 OpenAPI 3.0 정의를 내보내려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. 기본 탐색 창의 **개발**에서 **내보내기**를 선택합니다.
1. API 내보내기를 위한 다음과 같은 옵션을 선택합니다.
![\[HTTP API 내보내기 옵션.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/export-http-api.png)
1. **소스**에서 OpenAPI 3.0 정의의 소스를 선택합니다. 내보낼 스테이지를 선택하거나 API의 최신 구성을 내보낼 수 있습니다.
1. [API Gateway 확장](api-gateway-swagger-extensions.md)을 포함하려면 **API Gateway 확장 포함**을 켭니다.
1. **출력 형식**에서 출력 형식을 선택합니다.
1. **다운로드**를 선택합니다.