# API Gateway HTTP API
REST API와 HTTP API는 모두 RESTful API 제품입니다. REST API는 HTTP API보다 더 많은 기능을 지원하지만 HTTP API는 최소한의 기능으로 설계되어 더 낮은 가격으로 제공될 수 있습니다. 자세한 내용은 [REST API와 HTTP API 중에서 선택](http-api-vs-rest.md) 단원을 참조하십시오.
HTTP API를 사용하여 AWS Lambda 함수 또는 라우팅 가능한 HTTP 엔드포인트에 요청을 전송할 수 있습니다. 예를 들어 백엔드의 Lambda 함수와 통합되는 HTTP API를 생성할 수 있습니다. 클라이언트가 API를 호출하면 API Gateway는 Lambda 함수에 요청을 전송하고 함수의 응답을 클라이언트에 반환합니다.
HTTP API는 [OpenID Connect](https://openid.net/developers/how-connect-works/) 및 [OAuth 2.0](https://oauth.net/2/) 권한 부여를 지원합니다. 여기에서는 CORS(Cross-Origin Resource Sharing) 및 자동 배포가 기본적으로 지원됩니다.
AWS 관리 콘솔, AWS CLI, API, CloudFormation 또는 SDK를 사용하여 HTTP API를 생성할 수 있습니다.
**Topics**
+ [API Gateway에서 HTTP API 개발](http-api-develop.md)
+ [고객이 간접적으로 호출할 수 있도록 HTTP API 게시](http-api-publish.md)
+ [API Gateway에서 HTTP API 보호](http-api-protect.md)
+ [API Gateway에서 HTTP API 모니터링](http-api-monitor.md)
+ [API Gateway에서 HTTP API 관련 문제 해결](http-api-troubleshooting.md)
# 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. **다운로드**를 선택합니다.
# 고객이 간접적으로 호출할 수 있도록 HTTP API 게시
스테이지 및 사용자 지정 도메인 이름을 사용하여 클라이언트가 호출할 수 있도록 API를 게시할 수 있습니다.
API 스테이지는 API의 수명 주기 상태에 대한 논리적 참조(예: `dev`, `prod`, `beta`, `v2`)입니다. 각 스테이지는 API 배포에 대한 명명된 참조이며, 클라이언트 애플리케이션 프로그램에서 호출을 하는 데 사용할 수 있습니다. API의 각 스테이지에 대해 통합 및 설정을 서로 다르게 구성할 수 있습니다.
사용자 지정 도메인 이름을 사용하여 클라이언트가 API를 호출할 수 있도록 기본 URL인 `https://api-id.execute-api.region.amazonaws.com/stage` 보다 더 간단하고 직관적인 URL을 제공할 수 있습니다.
**참고**
API Gateway API의 보안을 강화하기 위해 `execute-api.{region}.amazonaws.com` 도메인은 [PSL(Public Suffix List)](https://publicsuffix.org/)에 등록됩니다. 보안 강화를 위해 API Gateway API 기본 도메인 이름에 민감한 쿠키를 설정해야 하는 경우 `__Host-` 접두사가 있는 쿠키를 사용하는 것이 좋습니다. 이렇게 쿠키를 설정하면 교차 사이트 요청 위조 시도(CSRF)로부터 도메인을 보호하는 데 도움이 됩니다. 자세한 내용은 Mozilla 개발자 네트워크의 [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) 페이지를 참조하십시오.
**Topics**
+ [API Gateway의 HTTP API에 대한 스테이지](http-api-stages.md)
+ [API Gateway의 HTTP API 보안 정책](http-api-ciphers.md)
+ [API Gateway의 HTTP API에 대한 사용자 지정 도메인 이름](http-api-custom-domain-names.md)
# API Gateway의 HTTP API에 대한 스테이지
API 스테이지는 API의 수명 주기 상태에 대한 논리적 참조(예: `dev`, `prod`, `beta`, `v2`)입니다. API 스테이지는 API ID 및 스테이지 이름으로 식별되며, API를 호출하는 데 사용하는 URL에 포함됩니다. 각 스테이지는 API 배포에 대한 명명된 참조이며, 클라이언트 애플리케이션 프로그램에서 호출을 하는 데 사용할 수 있습니다.
API의 URL 기반에서 제공되는 `$default` 스테이지를 생성할 수 있습니다(예: `https://{api_id}.execute-api.{region}.amazonaws.com/`). 이 URL을 사용하여 API 단계를 호출합니다.
배포는 API 구성의 스냅샷입니다. 단계에 API를 배포한 후에는 클라이언트가 API를 호출할 수 있습니다. 변경 사항을 적용하려면 API를 배포해야 합니다. 자동 배포를 활성화하면 API에 대한 변경 사항이 자동으로 릴리스됩니다.
# API Gateway에서 HTTP API용 스테이지 변수 사용
스테이지 변수는 HTTP API의 스테이지에 대해 정의할 수 있는 키-값 페어입니다. 환경 변수와 비슷한 역할을 하며, API 설정에 사용할 수 있습니다.
단계 변수는 자격 증명과 같은 중요한 데이터에 사용할 수 없습니다. 중요한 데이터를 통합에 전달하려면 AWS Lambda 권한 부여자를 사용합니다. Lambda 권한 부여자의 출력에서 중요한 데이터를 통합에 전달할 수 있습니다. 자세한 내용은 [Lambda 권한 부여자 응답 형식](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response) 단원을 참조하십시오.
## 예 - 스테이지 변수를 사용하여 HTTP 통합 엔드포인트 사용자 지정
예를 들어 스테이지 변수를 정의한 다음, 해당 값을 HTTP 프록시 통합을 위한 HTTP 엔드포인트로서 설정할 수 있습니다. 또한 추후에 연결된 스테이지 변수 이름을 사용하여 엔드포인트를 참조할 수 있습니다. 이렇게 하면 각 스테이지의 서로 다른 엔드포인트에서 동일한 API 설정을 사용할 수 있습니다. 마찬가지로 스테이지 변수를 사용하여 API의 각 스테이지에 대해 서로 다른 AWS Lambda 함수 통합을 지정할 수 있습니다.
스테이지 변수를 사용하여 HTTP 통합 엔드포인트를 사용자 지정하려면 먼저 스테이지(예: `url`)의 이름과 값을 `example.com`로 설정해야 합니다. 그런 다음 HTTP 프록시 통합을 설정합니다. 엔드포인트의 URL을 입력하는 대신, 단계 변수 값인 **http://\$1\$1stageVariables.url\$1**을 사용하도록 API Gateway에 지시할 수 있습니다. 이 값은 API의 스테이지에 따라 실행 시간에 스테이지 변수 `${}`을 대체하도록 API Gateway에 지시합니다.
비슷한 방법으로 스테이지 변수를 참조하여 Lambda 함수 이름이나 AWS 역할 ARN을 지정할 수 있습니다.
Lambda 함수 이름을 단계 변수 값으로 지정할 때는 Lambda 함수에 대한 권한을 수동으로 구성해야 합니다. 다음 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령은 Lambda 함수에 대한 권한을 구성합니다.
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# API Gateway의 HTTP API에 대한 API Gateway의 스테이지 변수 참조
다음과 같은 경우에 HTTP API에 API Gateway 스테이지 변수를 사용할 수 있습니다.
## HTTP 통합 URI
다음 예제에서 보듯 스테이지 변수를 HTTP 통합 URI의 일부로 사용할 수 있습니다.
+ 프로토콜이 없는 전체 URI - `http://${stageVariables.}`
+ 전체 도메인 - `http://${stageVariables.}/resource/operation`
+ 하위 도메인 - `http://${stageVariables.}.example.com/resource/operation`
+ 경로 - `http://example.com/${stageVariables.}/bar`
+ 쿼리 문자열 - `http://example.com/foo?q=${stageVariables.}`
## Lambda 함수
다음 예제와 같이 Lambda 함수 통합 이름이나 별칭 대신 스테이지 변수를 사용할 수 있습니다.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**참고**
Lambda 함수에 대해 단계 변수를 사용하려면 함수가 API와 동일한 계정에 있어야 합니다. 단계 변수는 교차 계정 Lambda 함수를 지원하지 않습니다.
## AWS 통합 자격 증명
다음 예제와 같이 스테이지 변수를 AWS 사용자 또는 역할 자격 증명 ARN의 일부로 사용할 수 있습니다.
+ `arn:aws:iam:::${stageVariables.}`
# API Gateway의 HTTP API 보안 정책
API Gateway는 모든 HTTP API 엔드포인트에 대한 보안 정책 `TLS_1_2`를 적용합니다.
보안 정책은 Amazon API Gateway가 제공하는 최소 TLS 버전과 암호 제품군의 사전 정의된 조합입니다.** TLS 프로토콜은 클라이언트와 서버 간의 변조 및 도청과 같은 네트워크 보안 문제를 해결합니다. 클라이언트가 사용자 지정의 도메인을 통해 API에 TLS 핸드셰이크를 설정하면 보안 정책은 클라이언트가 선택할 수 있는 TLS 버전 및 암호 제품군 옵션을 적용합니다. 이 보안 정책은 TLS 1.2 및 TLS 1.3 트래픽을 허용하고 TLS 1.0 트래픽은 거부합니다.
## HTTP APIs에 지원되는 TLS 프로토콜 및 암호.
다음 표에서는 HTTP API에 지원되는 TLS 프로토콜을 설명합니다.
| **TLS 프로토콜** | **TLS\$11\$12 보안 정책** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
다음 표에서는 HTTP API에 대한 TLS 1\$12 보안 정책에 사용할 수 있는 TLS 암호를 설명합니다.
| **TLS 싸이퍼** | **TLS\$11\$12 보안 정책** |
| --- | --- |
| TLS-AES-128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| TLS-AES-256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| TLS-CHACHA20-POLY1305-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/success_icon.svg) 예 |
## OpenSSL 및 RFC 암호 이름
OpenSSL 및 IETF RFC 5246은 동일한 암호에 대해 서로 다른 이름을 사용합니다. 암호 이름 목록은 [OpenSSL 및 RFC 암호 이름](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names) 단원을 참조합니다.
## REST API 및 WebSocket API에 대한 정보
REST APIs 및 WebSocket API에 대한 자세한 내용은 [API Gateway에서 사용자 지정 도메인에 대한 보안 정책 선택](apigateway-custom-domain-tls-version.md) 및 [API Gateway의 WebSocket API 보안 정책](websocket-api-ciphers.md)를 참조합니다.
# API Gateway의 HTTP API에 대한 사용자 지정 도메인 이름
*사용자 지정 도메인 이름*은 API 사용자에게 제공할 수 있는 더 간단하고 직관적인 URL입니다.
API를 배포한 후 사용자 및 사용자 고객은 다음 형식의 기본 URL을 사용하여 API를 호출할 수 있습니다.
```
https://api-id.execute-api.region.amazonaws.com/stage
```
여기서 *api-id*는 API Gateway에서 생성되고 *region*은 AWS 리전이며 *stage*는 API를 배포할 때 사용자가 지정합니다.
URL의 호스트 이름 부분(즉, `api-id.execute-api.region.amazonaws.com`)은 API 엔드포인트를 가리킵니다. 기본 API 엔드포인트는 임의로 생성되므로 기억하기가 어려우며 사용자 친화적이지 않습니다.
사용자 지정 도메인 이름을 사용하면 API의 호스트 이름을 설정하고 기본 경로(예: `myservice`)를 선택하여 대체 URL을 API에 매핑할 수 있습니다. 예를 들어, 더 사용자 친화적인 API 기본 URL은 다음과 같습니다.
```
https://api.example.com/myservice
```
## 고려 사항
다음 고려 사항은 사용자 지정 도메인 이름 사용에 영향을 미칠 수 있습니다.
+ 리전 사용자 지정 도메인 이름은 REST API 및 HTTP API와 연결될 수 있습니다. API Gateway 버전 2 API를 사용하여 REST API에 대한 리전 사용자 지정 도메인 이름을 생성하고 관리할 수 있습니다.
+ 최소 TLS 버전의 경우 TLS 1.2만 지원됩니다.
+ DNS 공급자의 리소스 레코드를 생성하거나 업데이트하여 API 엔드포인트에 매핑해야 합니다. 이렇게 매핑하지 않으면 사용자 지정 도메인 이름이 목적지인 API 요청은 API Gateway에 도달할 수 없습니다.
+ 와일드카드 인증서를 사용하면 기본 할당량을 초과하지 않고 거의 무제한 수의 도메인 이름을 지원할 수 있습니다. 자세한 내용은 [와일드카드 사용자 정의 도메인 이름](#http-wildcard-custom-domain-names) 섹션을 참조하세요.
## 사전 조건
사용자 지정 도메인 이름을 생성하기 위한 사전 요구 사항은 다음과 같습니다.
### 도메인 이름 등록
API에 대한 사용자 지정 도메인 이름을 설정하려면 등록된 인터넷 도메인 이름이 있어야 합니다. [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/)를 사용하거나 사용자가 선택한 서드 파티 도메인 등록자를 사용하여 인터넷 도메인을 등록할 수 있습니다. 사용자 지정 도메인 이름은 하위 도메인의 이름이거나 등록된 인터넷 도메인의 루트 도메인("zone apex"라고도 함) 이름일 수 있습니다.
도메인 이름은 [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) 사양을 따라야 하며 라벨당 최대 63옥텟, 총 255옥텝을 포함할 수 있습니다.
### 사용자 지정 도메인 이름에 대한 인증서
API에 대한 사용자 지정 도메인 이름을 설정하기 전에 ACM에서 SSL/TLS 인증서를 준비해야 합니다. 사용자 지정 도메인 이름을 생성하는 AWS 리전에서 ACM을 사용할 수 없는 경우 해당 리전의 API Gateway로 인증서를 가져와야 합니다.
SSL/TLS 인증서를 가져오려면 PEM 형식의 SSL/TLS 인증서 본문, 해당하는 프라이빗 키 및 사용자 지정 도메인 이름에 대한 인증서 체인을 제공해야 합니다.
ACM에 저장된 각 인증서는 ARN으로 식별됩니다. ACM에서 발행한 인증서를 사용하면 프라이빗 키 같은 민감한 인증서 세부 정보의 공개를 걱정할 필요가 없습니다. 해당 ARN을 참조하기만 하면 도메인 이름에 대해 AWS에서 관리하는 인증서를 사용할 수 있습니다.
애플리케이션에서 ACM 인증서를 고정하기 위해 인증서 고정(SSL 고정)을 사용하는 경우, AWS가 인증서를 갱신한 후 애플리케이션이 도메인에 연결하지 못하게 될 수 있습니다. 자세한 내용은 *AWS Certificate Manager 사용 설명서*의 [인증서 고정 문제](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html)를 참조하세요.
## 와일드카드 사용자 정의 도메인 이름
와일드카드 사용자 지정 도메인 이름을 사용하면 [기본 할당량](limits.md)을 초과하지 않고 거의 무제한 수의 도메인 이름을 지원할 수 있습니다. 예를 들어 각 고객에게 고유한 도메인 이름인 `customername.api.example.com`을 제공할 수 있습니다.
와일드카드 사용자 지정 도메인 이름을 생성하려면, 와일드카드(`*`)를 루트 도메인의 가능한 모든 하위 도메인을 나타내는 사용자 지정 도메인의 첫 번째 하위 도메인으로 지정할 수 있습니다.
예를 들어 와일드카드 사용자 정의 도메인 이름 `*.example.com`을 사용하면 `a.example.com`, `b.example.com` 및 `c.example.com` 같은 하위 도메인이 모두 동일한 도메인으로 라우팅됩니다.
와일드카드 사용자 지정 도메인 이름은 API Gateway의 표준 사용자 지정 도메인 이름과 별개의 구성을 지원합니다. 예를 들어, 단일 AWS 계정에서 `*.example.com`과 `a.example.com`가 다르게 동작하도록 구성할 수 있습니다.
와일드카드 사용자 지정 도메인 이름을 생성하려면 DNS 또는 이메일 검증 방법을 사용하여 검증한 ACM에서 발급한 인증서를 제공해야 합니다.
**참고**
다른 AWS 계정에서 와일드카드 사용자 지정 도메인 이름과 충돌하는 사용자 지정 도메인 이름을 만든 경우에는 와일드카드 사용자 지정 도메인 이름을 생성할 수 없습니다. 예를 들어 계정 A에서 `a.example.com`가 생성된 경우, 계정 B는 와일드카드 사용자 지정 도메인 이름 `*.example.com`을 생성할 수 없습니다.
계정 A와 계정 B가 한 소유자를 공유하는 경우 [AWS 지원 센터](https://console.aws.amazon.com/support/home#/)에 문의하여 예외를 요청할 수 있습니다.
## 사용자 지정 도메인 이름에 대한 다음 단계
HTTP API에 대한 사용자 지정 도메인 이름을 설정하려면 API Gateway 개발자 안내서의 REST API 섹션에 있는 설명서를 사용하세요.
우선 사용자 지정 도메인 이름에 대한 인증서를 지정합니다. 자세한 내용은 [AWS Certificate Manager에서 인증서 준비](how-to-specify-certificate-for-custom-domain-name.md) 섹션을 참조하세요. 다음으로 리전 사용자 지정 도메인 이름을 생성합니다. 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 섹션을 참조하세요.
# API 스테이지를 HTTP API에 대한 사용자 지정 도메인 이름에 매핑
API 매핑을 사용하여 API 스테이지를 사용자 지정 도메인 이름에 연결합니다. 도메인 이름을 생성하고 DNS 레코드를 구성한 후에는 API 매핑을 사용하여 사용자 지정 도메인 이름을 통해 API로 트래픽을 보냅니다.
API 매핑은 API, 스테이지 및 매핑에 사용할 경로(선택 사항)를 지정합니다. 예를 들어 API의 `production` 스테이지를 `https://api.example.com/orders`에 매핑할 수 있습니다.
HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑할 수 있습니다.
API 매핑을 생성하기 전에 API, 스테이지 및 사용자 지정 도메인 이름이 있어야 합니다. 사용자 지정 도메인 이름 생성에 대한 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
## API 요청 라우팅
여러 수준(예: `orders/v1/items` 및 `orders/v2/items`)으로 API 매핑을 구성할 수 있습니다.
여러 수준 API 매핑의 경우 API Gateway는 일치하는 경로가 가장 긴 API 매핑으로 요청을 라우팅합니다. API Gateway는 호출할 API를 선택하기 위해 API 경로가 아닌 API 매핑에 대해 구성된 경로만 고려합니다. 요청과 일치하는 경로가 없으면 API Gateway는 빈 경로 `(none)`에 매핑한 API로 요청을 보냅니다.
여러 수준 API 매핑을 사용하는 사용자 지정 도메인 이름의 경우 API Gateway는 일치하는 경로가 가장 긴 API 매핑으로 요청을 라우팅합니다.
예를 들어 다음 API 매핑이 있는 사용자 지정 도메인 이름 `https://api.example.com`을(를) 살펴보겠습니다.
1. `(none)`이(가) API 1에 매핑됩니다.
1. `orders`이(가) API 2에 매핑됩니다.
1. `orders/v1/items`이(가) API 3에 매핑됩니다.
1. `orders/v2/items`이(가) API 4에 매핑됩니다.
1. `orders/v2/items/categories`이(가) API 5에 매핑됩니다.
| 요청 | 선택한 API | 설명 |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v1/items` | `API 3` | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v2/items` | `API 4` | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway는 일치하는 경로가 가장 긴 매핑을 선택합니다. 요청 끝에 있는 `123`은(는) 선택 항목에 영향을 주지 않습니다. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway는 일치하는 경로가 가장 긴 매핑을 선택합니다. |
| `https://api.example.com/customers` | `API 1` | API Gateway는 빈 매핑을 캐치 올(catch-all)로 사용합니다. |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway는 일치하는 접두사가 가장 긴 매핑을 선택합니다. 단일 수준 매핑으로 구성된 사용자 지정 도메인 이름(예: 단지 `https://api.example.com/orders` 및 `https://api.example.com/`)의 경우 `ordersandmore`와 일치하는 경로가 없으므로 API Gateway는 `API 1`을 선택합니다. |
## 제한 사항
+ API 매핑에서 사용자 지정 도메인 이름과 매핑된 API는 동일한 AWS 계정에 있어야 합니다.
+ API 매핑에는 문자, 숫자 및 문자 `$-_.+!*'()/`만 포함해야 합니다.
+ API 매핑에서 경로의 최대 길이는 300자입니다.
+ 각 도메인 이름에 대해 여러 수준의 API 매핑이 200개 있을 수 있습니다. 이 제한에는 `/prod`와 같은 단일 수준의 API 매핑은 포함되지 않습니다.
+ TLS 1.2 보안 정책을 사용하여 HTTP API를 리전별 사용자 지정 도메인 이름에만 매핑할 수 있습니다.
+ WebSocket API를 HTTP API 또는 REST API와 동일한 사용자 지정 도메인 이름에 매핑할 수 없습니다.
+ 여러 레벨로 API 매핑을 생성하는 경우 API Gateway는 모든 헤더 이름을 소문자로 변환합니다.
## API 매핑 생성
API 매핑을 생성하려면 먼저 사용자 지정 도메인 이름, API 및 스테이지를 생성해야 합니다. 사용자 지정 도메인 이름 생성에 대한 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
예를 들어 모든 리소스를 생성하는 AWS Serverless Application Model 템플릿에 대해서는 GitHub의 [SAM 세션](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)을 참조하세요.
------
#### [ AWS Management Console ]
**API 매핑 생성**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **사용자 지정 도메인 이름**을 선택합니다.
1. 이미 생성한 사용자 지정 도메인 이름을 선택합니다.
1. **API 매핑**을 선택합니다.
1. **API 매핑 구성**을 선택합니다.
1. **새 매핑 추가**를 선택합니다.
1. **API**, **스테이지** 및 **경로**(선택 사항)를 입력합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) 명령은 API 매핑을 생성합니다. 이 예에서 API Gateway는 지정된 API 및 스테이지로 `api.example.com/v1/orders` 요청을 보냅니다.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
다음 CloudFormation 예에서는 API 매핑을 생성합니다.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# HTTP API의 기본 엔드포인트 비활성화
기본적으로 클라이언트는 API에 대해 API Gateway가 생성하는 `execute-api` 엔드포인트를 사용하여 API를 호출할 수 있습니다. 클라이언트가 사용자 지정 도메인 이름을 사용해야만 API에 액세스할 수 있도록 하려면 기본 `execute-api` 엔드포인트를 비활성화합니다. 기본 엔드포인트를 비활성화하면 API의 모든 스테이지에 영향이 미칩니다.
다음 절차는 HTTP API의 기본 엔드포인트를 비활성화하는 방법을 보여 줍니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. API ID를 선택하여 **API 세부 정보** 페이지를 엽니다.
1. **API 세부 정보** 탭에서 **편집**을 선택합니다.
1. **기본 엔드포인트**에서 **비활성화**를 선택합니다.
1. **Save**(저장)를 선택합니다.
스테이지에 자동 배포를 활성화하는 경우 변경 사항을 적용하기 위해 API를 재배포하지 않아도 됩니다. 그밖에는 API를 재배포해야 합니다.
1. (선택 사항) **배포**를 선택한 다음, 변경 사항을 적용하려면 API를 재배포하거나 새 스테이지를 생성하세요.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령은 HTTP API의 기본 엔드포인트를 비활성화합니다.
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
기본 엔드포인트를 비활성화한 후 자동 배포를 활성화하지 않는 한 변경 사항을 적용하려면 API를 배포해야 합니다.
다음 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) 명령을 사용하면 배포가 생성됩니다.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# HTTP API의 사용자 지정 도메인 이름에 대한 IP 주소 유형
API를 만들 때 도메인을 간접적으로 호출할 수 있는 IP 주소 유형을 지정합니다. IPv4를 선택하여 IPv4 주소가 도메인을 간접적으로 호출하도록 확인하거나, 듀얼 스택을 선택하여 IPv4 및 IPv6 주소가 모두 도메인을 간접적으로 호출하도록 허용할 수 있습니다. IP 공간 소진을 완화하기 위해 또는 보안 태세를 위해 IP 주소 유형을 듀얼 스택으로 설정하는 것이 좋습니다. 듀얼 스택 IP 주소 유형의 이점에 대한 자세한 내용은 [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)를 참조하세요.
## IP 주소 유형에 대한 고려 사항
다음 고려 사항은 IP 주소 유형 사용에 영향을 미칠 수 있습니다.
+ API Gateway 사용자 지정 도메인 이름의 기본 IP 주소 유형은 IPv4입니다.
+ 사용자 지정 도메인 이름은 여기에 매핑된 모든 API에 대해 동일한 IP 주소 유형을 가질 필요가 없습니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
## 사용자 지정 도메인 이름의 IP 주소 유형 변경
도메인의 엔드포인트 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다. AWS Management Console, AWS CLI, CloudFormation 또는 AWS SDK를 사용하여 도메인의 엔드포인트 구성을 업데이트할 수 있습니다.
------
#### [ AWS Management Console ]
**사용자 지정 도메인 이름의 IP 주소 유형을 변경하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 퍼블릭 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**을 선택합니다.
1. IP 주소 유형에서 **IPv4** 또는 **듀얼 스택**을 선택합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령은 IP 주소 유형이 듀얼 스택이 되도록 API를 업데이트합니다.
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
출력은 다음과 같습니다.
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# API Gateway에서 HTTP API 보호
API Gateway는 악의적인 사용자나 트래픽 스파이크 같은 특정 위협으로부터 API를 보호할 수 있는 여러 가지 방법을 제공합니다. 제한 대상 설정 및 상호 TLS 활성화와 같은 전략을 사용하여 API를 보호할 수 있습니다. 이 섹션에서는 API Gateway를 사용하여 이러한 기능을 활성화하는 방법을 배울 수 있습니다.
**Topics**
+ [API Gateway의 처리량 향상을 위해 HTTP API에 대한 요청을 제한할 수 있습니다.](http-api-throttling.md)
+ [API Gateway에서 HTTP API에 대한 상호 TLS 인증을 켜는 방법](http-api-mutual-tls.md)
# API Gateway의 처리량 향상을 위해 HTTP API에 대한 요청을 제한할 수 있습니다.
API에 대한 제한을 구성하여 너무 많은 요청으로 인해 과부하되지 않도록 보호할 수 있습니다. 제한은 모두 최선의 방식으로 적용되며 보장된 요청 한도가 아닌 대상으로 간주해야 합니다.
API Gateway는 요청에 대해 토큰이 계산되는 토큰 버킷 알고리즘을 사용하여 API에 대한 요청을 제한합니다. 특히 API Gateway는 리전별로 계정의 모든 API에 대한 요청 제출 속도와 버스트를 검사합니다. 토큰 버킷 알고리즘에서 버스트는 이러한 제한의 사전 정의된 초과 실행을 허용할 수 있지만, 다른 요인으로도 제한을 초과할 수 있습니다.
요청 제출이 정상 상태의 요청 속도 및 버스트 제한을 초과할 경우 API Gateway에서 요청을 제한하기 시작합니다. 이 시점에서 클라이언트는 `429 Too Many Requests` 오류 응답을 받을 수 있습니다. 이러한 예외를 포착하면 클라이언트는 속도 제한 방식으로 실패한 요청을 다시 제출할 수 있습니다.
API 개발자는 개별 API 단계 또는 경로에 대한 목표 제한을 설정하여 계정의 모든 API에서 전반적인 성능을 향상시킬 수 있습니다.
## 리전별 계정 수준 조절
기본적으로 API Gateway는 리전별로 AWS 계정 내의 모든 API에서 안정적인 상태의 초당 요청(RPS)을 제한합니다. 또한 리전별로 AWS 계정 내 모든 API에 대해 버스트(즉, 최대 버킷 크기)를 제한합니다. API Gateway에서 버스트 제한은 API Gateway가 `429 Too Many Requests` 오류 응답을 반환하기 전에 수행할 동시 요청 제출의 최대 목표 수를 나타냅니다. 조절 할당량에 대한 자세한 내용은 [Amazon API Gateway 할당량](limits.md) 단원을 참조하세요.
계정당 한도는 지정된 리전에 있는 계정의 모든 API에 적용됩니다. 계정 수준 속도 제한은 요청 시 늘릴 수 있습니다. 제한 시간이 더 짧고 페이로드가 더 작은 API를 사용하면 더 높은 제한이 가능합니다. 리전별로 계정 수준 조절 한도 증가를 요청하려면 [AWS 지원 센터](https://console.aws.amazon.com/support/home#/)에 문의하시기 바랍니다. 자세한 내용은 [Amazon API Gateway 할당량](limits.md) 섹션을 참조하세요. 이러한 제한은 AWS 제한 한도보다 높을 수 없습니다.
## 라우팅 수준 스로틀
라우팅 수준 스로틀을 설정해 API의 특정 단계 또는 개별 라우팅에 대해 계정 수준 요청 스로틀 한도를 재정의할 수 있습니다. 기본 경로 제한 한도는 계정 수준 속도 제한을 초과할 수 없습니다.
AWS CLI를 사용하여 라우팅 수준 스로틀을 구성할 수 있습니다. 다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) 명령은 API의 지정된 스테이지 및 경로에 대한 사용자 지정 스로틀링을 구성합니다.
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# API Gateway에서 HTTP API에 대한 상호 TLS 인증을 켜는 방법
상호 TLS 인증에는 클라이언트와 서버 간의 양방향 인증이 필요합니다. 상호 TLS를 사용하는 경우 클라이언트가 API에 액세스하려면 자격 증명을 확인하기 위해 X.509 인증서를 제공해야 합니다. 상호 TLS는 사물 인터넷(IoT) 및 B2B 애플리케이션에 일반적으로 요구됩니다.
API Gateway가 지원하는 다른 [권한 부여 및 인증 작업](apigateway-control-access-to-api.md)과 함께 상호 TLS를 사용할 수 있습니다. API Gateway는 클라이언트가 제공하는 인증서를 Lambda 권한 부여자와 백엔드 통합에 전달합니다.
**중요**
기본적으로 클라이언트는 API에 대해 API Gateway가 생성하는 `execute-api` 엔드포인트를 사용하여 API를 호출할 수 있습니다. 클라이언트가 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용해야만 API에 액세스할 수 있도록 하려면 기본 `execute-api` 엔드포인트를 비활성화합니다. 자세한 내용은 [HTTP API의 기본 엔드포인트 비활성화](http-api-disable-default-endpoint.md) 단원을 참조하세요.
## 상호 TLS의 사전 조건
상호 TLS를 구성하려면 다음이 필요합니다.
+ 사용자 지정 도메인 이름
+ 사용자 지정 도메인 이름에 대해 AWS Certificate Manager에 구성된 하나 이상의 인증서
+ Amazon S3에 구성 및 업로드된 트러스트 스토어
### 사용자 지정 도메인 이름
HTTP API에 상호 TLS를 활성화하려면 API에 대한 사용자 지정 도메인 이름을 구성해야 합니다. 사용자 지정 도메인 이름에 상호 TLS를 활성화한 다음 클라이언트에 사용자 지정 도메인 이름을 제공할 수 있습니다. 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스하려면 클라이언트가 API 요청에서 신뢰할 수 있는 인증서를 제공해야 합니다. 추가 정보는 [API Gateway의 HTTP API에 대한 사용자 지정 도메인 이름](http-api-custom-domain-names.md) 단원에서 확인할 수 있습니다.
### AWS Certificate Manager에서 발급된 인증서 사용
ACM에서 직접 공인 인증서를 요청하거나 공용 인증서 또는 자체 서명된 인증서를 가져올 수 있습니다. ACM에 인증서를 설정하려면 [ACM](https://console.aws.amazon.com/acm/)으로 이동하세요. 인증서를 가져오려면 다음 단원을 계속 읽으세요.
### 가져온 인증서 또는 AWS Private Certificate Authority 인증서 사용
ACM으로 가져온 인증서 또는 AWS Private Certificate Authority에서 가져온 인증서를 상호 TLS와 함께 사용하려면 API Gateway에서 ACM이 발급한 `ownershipVerificationCertificate`가 필요합니다. 이 소유권 인증서는 도메인 이름을 사용할 수 있는 권한이 있는지 확인하는 데에만 사용됩니다. TLS 핸드셰이크에는 사용되지 않습니다. 아직 `ownershipVerificationCertificate`가 없으면 [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/)으로 이동하여 하나를 설정합니다.
도메인 이름의 수명 동안 이 인증서를 유효하게 유지해야 합니다. 인증서가 만료되고 자동 갱신이 실패하면 도메인 이름에 대한 모든 업데이트가 잠깁니다. 다른 변경 사항을 적용하기 전에 유효한 `ownershipVerificationCertificate`를 사용해 `ownershipVerificationCertificateArn`을 업데이트해야 합니다. `ownershipVerificationCertificate`는 API Gateway의 다른 상호 TLS 도메인에 대한 서버 인증서로 사용할 수 없습니다. 인증서를 ACM으로 직접 다시 가져오는 경우 발급자는 동일하게 유지해야 합니다.
### 트러스트 스토어 구성
트러스트 스토어는 파일 확장자가 `.pem`인 텍스트 파일입니다. 인증 기관으로부터의 신뢰할 수 있는 인증서 목록입니다. 상호 TLS를 사용하려면 API에 액세스하도록 신뢰할 수 있는 X.509 인증서의 트러스트 스토어를 생성합니다.
발급 CA 인증서부터 루트 CA 인증서까지의 전체 신뢰 체인을 트러스트 스토어에 포함시켜야 합니다. API Gateway는 현재 신뢰 체인에 있는 모든 CA에서 발급한 클라이언트 인증서를 수락합니다. 공인 또는 사설 인증 기관의 인증서가 포함될 수 있습니다. 인증서의 체인 길이는 최대 4개가 될 수 있습니다. 자체 서명된 인증서를 제공할 수도 있습니다. 트러스트 스토어에서 지원되는 해싱 알고리즘은 다음과 같습니다.
+ SHA-256 이상
+ RSA-2048 이상
+ ECDSA-256 이상
API Gateway에서는 여러 인증서 속성의 유효성을 검사합니다. Lambda 권한 부여자를 사용하여 클라이언트가 API를 호출할 때 인증서가 해지되었는지 확인하는 것과 같은 추가 검사를 수행할 수 있습니다. API Gateway는 다음 속성의 유효성을 검사합니다.
| 검증 | 설명 |
| --- | --- |
| X.509 구문 | 인증서는 X.509 구문 요구 사항을 충족해야 합니다. |
| 무결성 | 인증서 내용이 트러스트 스토어의 인증 기관에서 서명한 내용에서 변경되어서는 안 됩니다. |
| 유효성 | 인증서의 유효 기간이 최신이어야 합니다. |
| 이름 체인/키 체인 | 인증서의 이름과 주체는 끊어지지 않는 체인을 형성해야 합니다. 인증서의 체인 길이는 최대 4개가 될 수 있습니다. |
### 단일 파일의 Amazon S3 버킷에 트러스트 스토어를 업로드합니다.
**Example certificates.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
다음 [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) AWS CLI 명령은 Amazon S3 버킷에 `certificates.pem`을 업로드합니다.
```
aws s3 cp certificates.pem s3://bucket-name
```
## 사용자 지정 도메인 이름에 대한 상호 TLS 구성
HTTP API에 대한 상호 TLS를 구성하려면 API에 대해 최소 TLS 버전이 1.2인 리전 사용자 지정 도메인 이름을 사용해야 합니다. 사용자 지정 도메인 이름 생성 및 구성에 대한 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
**참고**
프라이빗 API에는 상호 TLS가 지원되지 않습니다.
트러스트 스토어를 Amazon S3에 업로드한 후 상호 TLS를 사용하도록 사용자 지정 도메인 이름을 구성할 수 있습니다. 다음 [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)은 상호 TLS를 사용하여 사용자 지정 도메인 이름을 생성합니다.
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
도메인 이름을 생성한 후에는 API 작업에 대한 DNS 레코드와 기본 경로 매핑을 구성해야 합니다. 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
## 상호 TLS가 요구되는 사용자 지정 도메인 이름을 사용하여 API 호출
상호 TLS가 활성화된 API를 호출하려면 클라이언트가 API 요청에서 신뢰할 수 있는 인증서를 제공해야 합니다. 클라이언트가 API를 호출하려고 하면 API Gateway는 트러스트 스토어에서 클라이언트 인증서의 발급자를 찾습니다. API Gateway가 요청을 진행하려면 인증서의 발급자 및 루트 CA 인증서까지의 전체 신뢰 체인이 트러스트 스토어에 있어야 합니다.
다음 예제 `curl` 명령은 요청에 `api.example.com,`을 포함하여 `my-cert.pem`에 요청을 보냅니다. `my-key.key`는 인증서의 프라이빗 키입니다.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
트러스트 스토어가 인증서를 신뢰하는 경우에만 API가 호출됩니다. 다음 조건에서는 API Gateway가 TLS 핸드셰이크에 실패하고 `403` 상태 코드와 함께 요청을 거부합니다. 인증서가 다음 상태인 경우:
+ 신뢰할 수 없음
+ 만료됨
+ 지원되는 알고리즘을 사용하지 않음
**참고**
API Gateway에서는 인증서가 해지되었는지 여부를 확인하지 않습니다.
## 트러스트 스토어 업데이트
트러스트 스토어의 인증서를 업데이트하려면 새 인증서 번들을 Amazon S3에 업로드합니다. 그런 다음 업데이트된 인증서를 사용하도록 사용자 지정 도메인 이름을 업데이트할 수 있습니다.
[Amazon S3 버전 관리](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)를 사용하여 트러스트 스토어의 여러 버전을 유지 관리합니다. 새 트러스트 스토어 버전을 사용하도록 사용자 지정 도메인 이름을 업데이트하면 인증서가 유효하지 않을 경우 API Gateway에서 경고가 반환됩니다.
API Gateway는 도메인 이름을 업데이트할 때만 인증서 경고를 생성합니다. API Gateway는 이전에 업로드한 인증서 만료를 알려주지 않습니다.
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령은 새 트러스트 스토어 버전을 사용하도록 사용자 지정 도메인 이름을 업데이트합니다.
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## 상호 TLS 비활성화
사용자 지정 도메인 이름에 상호 TLS를 사용하지 않도록 설정하려면 다음 명령과 같이 사용자 지정 도메인 이름에서 해당 트러스트 스토어를 제거합니다.
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령은 사용자 지정 도메인 이름을 업데이트하여 사용자 지정 도메인 이름에서 트러스트 스토어를 제거합니다.
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## HTTP API의 상호 TLS 문제 해결
아래에서는 상호 TLS를 켤 때 발생할 수 있는 오류 및 문제를 해결하는 방법을 조언합니다.
### 인증서 경고 문제 해결
상호 TLS가 포함된 사용자 지정 도메인 이름을 만들 때 트러스트 스토어의 인증서가 유효하지 않을 경우 API Gateway 에서 경고가 반환됩니다. 이는 새 트러스트 스토어를 사용하도록 사용자 지정 도메인 이름을 업데이트할 때에도 발생할 수 있습니다. 이러한 경고는 경고를 유발한 인증서와 인증서 주체에 문제가 있음을 나타냅니다. API에 대해 상호 TLS가 계속 활성화되어 있지만 일부 클라이언트는 API에 액세스하지 못할 수 있습니다.
경고를 유발한 인증서를 식별하려면 트러스트 스토어에서 인증서를 디코딩해야 합니다. `openssl` 같은 도구를 사용하여 인증서를 디코딩하고 해당 주체를 식별할 수 있습니다.
다음 명령은 주체를 포함하여 인증서의 내용을 표시합니다.
```
openssl x509 -in certificate.crt -text -noout
```
경고를 유발한 인증서를 업데이트하거나 제거한 다음 새 트러스트 스토어를 Amazon S3에 업로드합니다. 새 트러스트 스토어를 업로드한 후 새 트러스트 스토어를 사용하도록 사용자 지정 도메인 이름을 업데이트합니다.
### 도메인 이름 충돌 문제 해결
오류 `"The certificate subject conflicts with an existing certificate from a different issuer."`은(는) 여러 인증 기관이 이 도메인에 대한 인증서를 발급했음을 의미합니다. 인증서의 각 주체에 대해 API Gateway에는 상호 TLS 도메인에 대한 발급자가 하나만 있을 수 있습니다. 해당 주제에 대한 모든 인증서는 단일 발급자를 통해서만 받아야 합니다. 본인이 제어할 수 없지만 도메인 이름의 소유권을 증명할 수는 있는 인증서에 문제가 있는 경우 [지원에 문의](https://console.aws.amazon.com/support/cases#/create)를 눌러 티켓을 엽니다.
### 도메인 이름 상태 메시지 문제 해결
`PENDING_CERTIFICATE_REIMPORT`: 이것은 인증서를 ACM으로 다시 가져왔으며, 새 인증서에 SAN(주체 대체 이름)이 `ownershipVerificationCertificate`에 포함되지 않거나 인증서의 주체 또는 SAN이 도메인 이름을 포함하지 않기 때문에 유효성 검사에 실패했다는 의미입니다. 잘못 구성되었거나 잘못된 인증서를 가져왔을 수 있습니다. 유효한 인증서를 ACM으로 다시 가져와야 합니다. 검증에 대한 자세한 내용은 [도메인 소유권 검증](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html)을 참조하세요.
`PENDING_OWNERSHIP_VERIFICATION`: 이것은 이전에 확인된 인증서가 만료되어 ACM이 인증서를 자동 갱신할 수 없다는 의미입니다. 인증서를 갱신하거나 새 인증서를 요청해야 합니다. 인증서 갱신에 대한 자세한 내용은 [ACM의 관리형 인증서 갱신 문제 해결](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html) 가이드를 참조하세요.
# API Gateway에서 HTTP API 모니터링
CloudWatch 지표와 CloudWatch Logs를 사용하여 HTTP API를 모니터링할 수 있습니다. 로그와 지표를 결합하여 오류를 기록하고 API의 성능을 모니터링할 수 있습니다.
**참고**
API Gateway는 다음과 같은 경우 로그 및 지표를 생성하지 않을 수 있습니다.
413 요청 엔터티가 너무 큼 오류가 발생한 경우
429개 초과로 요청이 너무 많음 오류가 발생한 경우
API 매핑이 없는 사용자 지정 도메인으로 보낸 요청에서 400개의 연속 오류가 발생한 경우
내부 오류로 인해 500개의 연속 오류가 발생한 경우
**Topics**
+ [API Gateway에서 HTTP API에 대한 CloudWatch 지표 모니터링](http-api-metrics.md)
+ [API Gateway에서 HTTP API 로깅 구성](http-api-logging.md)
# API Gateway에서 HTTP API에 대한 CloudWatch 지표 모니터링
API Gateway에서 원시 데이터를 수집하고 읽기 가능한 실시간에 가까운 지표로 처리하는 CloudWatch를 사용하여 API 실행을 모니터링할 수 있습니다. 이러한 통계는 15개월 간 기록되므로 기록 정보에 액세스하고 웹 애플리케이션이나 서비스가 어떻게 수행되고 있는지 전체적으로 더 잘 파악할 수 있습니다. 기본적으로 API Gateway 지표 데이터는 1분 간격으로 CloudWatch로 자동 전송됩니다. 지표를 모니터링하려면 API용 CloudWatch 대시보드를 만드세요. CloudWatch 대시보드를 만드는 방법에 대한 자세한 내용은 **Amazon CloudWatch 사용 설명서에서 [CloudWatch 대시보드 생성](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html)을 참조하세요. 자세한 내용은 *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch란 무엇입니까?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)를 참조하십시오.
HTTP API에서는 다음과 같은 지표가 지원됩니다. 또한 세부 지표를 활성화하여 경로 수준 지표를 Amazon CloudWatch에 쓸 수도 있습니다.
| 측정치 | 설명 |
| --- | --- |
| 4xx | 지정한 기간 내에 캡처된 클라이언트 측 오류 수 |
| 5xx | 지정한 기간 내에 캡처된 서버 측 오류 수. |
| 개수 | 지정된 기간 동안의 총 API 요청 수. |
| IntegrationLatency | API Gateway가 요청을 백엔드로 릴레이할 때부터 백엔드에서 응답을 수신할 때까지의 시간입니다. |
| Latency | API Gateway가 클라이언트에서 요청을 수신할 때부터 클라이언트에게 응답을 반환할 때까지의 시간입니다. 지연 시간에는 통합 지연 시간과 기타 API Gateway 오버헤드가 포함됩니다. |
| DataProcessed | 처리된 데이터의 양(바이트)입니다. |
다음 표의 차원을 사용하여 API Gateway 지표를 필터링할 수 있습니다.
| 차원 | 설명 |
| --- | --- |
| ApiId | 지정한 API ID를 사용하여 API에 대한 API Gateway 지표를 필터링합니다. |
| ApiId, 스테이지 | 지정한 API ID와 스테이지 ID를 사용하여 API 스테이지에 대한 API Gateway 지표를 필터링합니다. |
| ApiId, Method, Resource, Stage | 지정한 API ID, 스테이지 ID, 리소스 경로 및 라우팅 ID를 사용하여 API 메서드에 대한 API Gateway 지표를 필터링합니다. 사용자가 세부 CloudWatch 지표를 명시적으로 활성화하지 않으면 API Gateway는 이러한 지표를 전송하지 않습니다. API Gateway V2 REST API의 [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) 작업을 호출하여 `detailedMetricsEnabled` 속성을 `true`로 업데이트하면 됩니다. 또는 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) AWS CLI 명령을 호출하여 `DetailedMetricsEnabled` 속성을 `true`로 업데이트할 수 있습니다. 이러한 지표를 활성화할 경우 계정에 추가 비용이 발생합니다. 요금에 대한 자세한 내용은 [Amazon CloudWatch 요금](https://aws.amazon.com/cloudwatch/pricing/)을 참조하십시오. |
# API Gateway에서 HTTP API 로깅 구성
로깅을 활성화하여 CloudWatch Logs에 로그를 기록할 수 있습니다. [로깅 변수](http-api-logging-variables.md)를 사용하여 로그의 내용을 사용자 지정할 수 있습니다.
보안 태세를 개선하려면 HTTP API의 모든 단계에 대해 CloudWatch Logs에 로그를 작성하는 것이 좋습니다. 다양한 규정 준수 프레임워크를 준수하기 위해 이 작업을 수행해야 할 수 있습니다. 자세한 내용은 *AWS Security Hub 사용 설명서*에서 [Amazon API Gateway 제어](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)를 참조하세요.
HTTP API에 대한 로깅을 활성화하려면 다음을 수행해야 합니다.
1. 사용자가 로깅을 활성화하는 데 필요한 권한을 가지고 있는지 확인합니다.
1. CloudWatch Logs 로그 그룹을 생성합니다.
1. API 단계에 대한 CloudWatch Logs 로그 그룹의 ARN을 제공합니다.
## 로깅을 활성화하는 권한
API에 대한 로깅을 활성화하려면 사용자는 다음과 같은 권한을 가지고 있어야 합니다.
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## 로그 그룹 생성 및 HTTP API에 대한 로깅 활성화
AWS Management Console 또는 AWS CLI를 사용하여 로그 그룹을 생성하고 액세스 로깅을 활성화할 수 있습니다.
------
#### [ AWS Management Console ]
1. 로그 그룹 생성.
콘솔을 사용하여 로그 그룹을 생성하는 방법을 알아보려면 [Amazon CloudWatch Logs 사용 설명서의 로그 그룹 생성](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)을 참조하세요.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. 기본 탐색 패널의 **Monitor**(모니터링) 탭에서 **Logging**(로깅) 선택합니다.
1. 로깅을 활성화할 단계를 선택하고 **Select**(선택)를 선택합니다.
1. **Edit**(편집)을 선택하여 액세스 로깅을 활성화합니다.
1. **Access logging**(액세스 로깅)을 활성화하고 CloudWatch Logs를 입력한 다음 로그 형식을 선택합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) 명령은 로그 그룹을 생성합니다.
```
aws logs create-log-group --log-group-name my-log-group
```
로깅을 활성화하려면 로그 그룹의 Amazon 리소스 이름(ARN)이 필요합니다. ARN 형식은 arn:aws:logs:*region*: *account-id*:log-group:*log-group-name*입니다.
다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) 명령은 HTTP API의 `$default` 스테이지에 대한 로깅을 활성화합니다.
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## 로그 형식 예
일반적으로 사용되는 몇 가지 액세스 로그 형식의 예제가 API Gateway 콘솔에 표시되며 다음과 같이 나열됩니다.
+ `CLF`([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV`(쉼표로 분리된 값):
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# HTTP API 액세스 로그 사용자 정의
다음 변수를 사용하여 HTTP API 액세스 로그를 사용자 지정할 수 있습니다. HTTP API의 액세스 로그에 대해 자세히 알아보려면 [API Gateway에서 HTTP API 로깅 구성](http-api-logging.md) 단원을 참조하십시오.
| 파라미터 | 설명 |
| --- | --- |
| \$1context.accountId | API 소유자의 AWS 계정 ID입니다. |
| \$1context.apiId | 식별자 API Gateway가 API에 할당합니다. |
| \$1context.authorizer.claims.property | 메서드 호출자가 성공적으로 인증된 후 JWT(JSON Web Token)에서 반환된 클레임의 속성(예: `$context.authorizer.claims.username`)입니다. 자세한 내용은 [API Gateway에서 JWT 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어](http-api-jwt-authorizer.md) 섹션을 참조하세요. `$context.authorizer.claims`를 호출하면 null이 반환됩니다. |
| \$1context.authorizer.error | 권한 부여자로부터 반환된 오류 메시지입니다. |
| \$1context.authorizer.property | API Gateway Lambda 권한 부여자 함수에서 반환된 `context` 맵의 지정된 키-값 페어의 값입니다. 예를 들어, 권한 부여자는 다음 `context` 맵을 반환합니다. "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} `$context.authorizer.key`를 호출하면 `"value"` 문자열이 반환되고, `$context.authorizer.numKey`를 호출하면 `1`이 반환되고, `$context.authorizer.boolKey`를 호출하면 `true`가 반환됩니다. |
| \$1context.awsEndpointRequestId | `x-amz-request-id` 또는 `x-amzn-requestId` 헤더의 AWS 엔드포인트 요청 ID입니다. |
| \$1context.awsEndpointRequestId2 | `x-amz-id-2` 헤더의 AWS 엔드포인트 요청 ID입니다. |
| \$1context.customDomain.basePathMatched | 들어오는 요청이 일치하는 API 매핑의 경로입니다. 클라이언트가 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 적용할 수 있습니다. 예를 들어 클라이언트가 `https://api.example.com/v1/orders/1234`에 요청을 보내고 요청이 API 매핑을 경로 `v1/orders`와(과) 일치시키는 경우 값은 `v1/orders`입니다. 자세한 내용은 [API 스테이지를 HTTP API에 대한 사용자 지정 도메인 이름에 매핑](http-api-mappings.md) 단원을 참조하십시오. |
| \$1context.dataProcessed | 처리된 데이터의 양(바이트)입니다. |
| \$1context.domainName | API를 호출하는 데 사용되는 정식 도메인 이름입니다. 이 이름은 수신되는 `Host` 헤더와 동일해야 합니다. |
| \$1context.domainPrefix | `$context.domainName`의 첫 번째 레이블입니다. |
| \$1context.error.message | API Gateway 오류 메시지가 포함된 문자열입니다. |
| \$1context.error.messageString | \$1context.error.message의 따옴표 붙은 값, 즉 "\$1context.error.message"입니다. |
| \$1context.error.responseType | `GatewayResponse`의 한 유형입니다. 자세한 내용은 [CloudWatch 지표로 WebSocket API 실행 모니터링](apigateway-websocket-api-logging.md) 및 [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)(을)를 참조하세요. |
| \$1context.extendedRequestId | \$1context.requestId와 동일합니다. |
| \$1context.httpMethod | 사용된 HTTP 메서드입니다. 유효한 값에는 `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` 및 `PUT`이 있습니다. |
| \$1context.identity.accountId | 요청과 연결된 AWS 계정 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.caller | 요청에 서명한 호출자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.cognitoAuthenticationProvider | 요청을 작성한 직접 호출자가 사용한 모든 Amazon Cognito 인증 공급자의 쉼표로 구분된 목록입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 예를 들어, Amazon Cognito 사용자 풀의 자격 증명의 경우 `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 사용 가능한 Amazon Cognito 인증 공급자에 대한 자세한 내용은 Amazon Cognito 개발자 안내서**의 [페더레이션 자격 증명 사용](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)을 참조하세요. |
| \$1context.identity.cognitoAuthenticationType | 요청을 작성한 호출자의 Amazon Cognito 인증 유형입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 가능한 값에는 인증 자격 증명에 대한 `authenticated` 및 미인증 자격 증명에 대한 `unauthenticated`이(가) 포함됩니다. |
| \$1context.identity.cognitoIdentityId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. |
| \$1context.identity.cognitoIdentityPoolId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 풀 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. |
| \$1context.identity.principalOrgId | [AWS 조직 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.clientCert.clientCertPem | 상호 TLS 인증 시 클라이언트가 제공한 PEM 인코딩된 클라이언트 인증서입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.clientCert.subjectDN | 클라이언트가 제공하는 인증서의 주체가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.clientCert.issuerDN | 클라이언트가 제공하는 인증서의 발행자가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.clientCert.serialNumber | 인증서의 일련 번호입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.clientCert.validity.notBefore | 인증서의 유효 기간이 시작되는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.clientCert.validity.notAfter | 인증서의 유효 기간이 끝나는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. |
| \$1context.identity.sourceIp | API Gateway 엔드포인트를 요청하는 즉시 TCP 연결의 소스 IP 주소입니다. |
| \$1context.identity.user | 리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.userAgent | API 호출자의 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 헤더입니다. |
| \$1context.identity.userArn | 인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. 자세한 내용은 [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) 단원을 참조하세요. |
| \$1context.integration.error | 통합에서 반환된 오류 메시지입니다. \$1context.integrationErrorMessage와 동일합니다. |
| \$1context.integration.integrationStatus | Lambda 프록시 통합의 경우 백엔드 Lambda 함수 코드가 아니라 AWS Lambda에서 반환된 상태 코드입니다. |
| \$1context.integration.latency | 통합 지연 시간(ms)입니다. \$1context.integrationLatency와 동일합니다. |
| \$1context.integration.requestId | AWS 엔드포인트의 요청 ID입니다. \$1context.awsEndpointRequestId와 동일합니다. |
| \$1context.integration.status | 통합에서 반환된 상태 코드입니다. Lambda 프록시 통합의 경우 Lambda 함수 코드에서 반환된 상태 코드입니다. |
| \$1context.integrationErrorMessage | 통합 오류 메시지가 포함된 문자열입니다. |
| \$1context.integrationLatency | 통합 지연 시간(ms)입니다. |
| \$1context.integrationStatus | Lambda 프록시 통합의 경우 이 파라미터는 백엔드 Lambda 함수가 아니라 AWS Lambda에서 반환된 상태 코드를 나타냅니다. |
| \$1context.path | 요청 경로입니다. 예를 들어 /\$1stage\$1/root/child입니다. |
| \$1context.protocol | 요청 프로토콜입니다(예: HTTP/1.1). API Gateway API는 HTTP/2 요청을 수락할 수 있지만 API Gateway는 HTTP/1.1을 사용하여 백엔드 통합에 요청을 보냅니다. 따라서 클라이언트가 HTTP/2를 사용하는 요청을 보내더라도 요청 프로토콜은 HTTP/1.1로 기록됩니다. |
| \$1context.requestId | API Gateway가 API 요청에 할당하는 ID입니다. |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 형식 요청 시간(dd/MMM/yyyy:HH:mm:ss \$1-hhmm)입니다. |
| \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 형식 요청 시간입니다. |
| \$1context.responseLatency | 응답 지연 시간(ms)입니다. |
| \$1context.responseLength | 바이트로 된 응답 페이로드 길이입니다. |
| \$1context.routeKey | API 요청의 경로 키입니다(예: `/pets`). |
| \$1context.stage | API 요청의 개발 단계입니다(예: `beta` 또는 `prod`). |
| \$1context.status | 메서드 응답 상태입니다. |
# API Gateway에서 HTTP API 관련 문제 해결
다음 주제에서는 HTTP API를 사용할 때 발생할 수 있는 오류 및 문제에 대한 문제 해결 조언을 제공합니다.
**Topics**
+ [HTTP API Lambda 통합 관련 문제 해결](http-api-troubleshooting-lambda.md)
+ [HTTP API JWT 권한 부여자 관련 문제 해결](http-api-troubleshooting-jwt.md)
# HTTP API Lambda 통합 관련 문제 해결
다음은 [AWS Lambda 통합](http-api-develop-integrations-lambda.md)를 HTTP API와 함께 사용할 때 발생할 수 있는 오류 및 문제에 대한 문제 해결 조언을 제공합니다.
## 문제: Lambda 통합이 있는 내 API가 `{"message":"Internal Server Error"}`를 반환합니다.
내부 서버 오류 문제를 해결하려면 로그 형식에 `$context.integrationErrorMessage` [로깅 변수](http-api-logging-variables.md)를 추가하고 HTTP API의 로그를 봅니다. 이를 위해 다음을 수행합니다.
**을 사용하여 로그 그룹 생성AWS Management Console**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. **로그 그룹**을 선택합니다.
1. **로그 그룹 생성**을 선택합니다.
1. 로그 그룹 이름을 입력한 다음 **생성**을 선택합니다.
1. 로그 그룹의 Amazon 리소스 이름(ARN)을 기록해 둡니다. ARN 형식은 arn:aws:logs:*region*: *account-id*:log-group:*log-group-name*입니다. HTTP API에 대한 액세스 로깅을 활성화하려면 로그 그룹 ARN이 필요합니다.
**`$context.integrationErrorMessage` 로깅 변수를 추가하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. **모니터**에서 **로깅**을 선택합니다.
1. API의 단계를 선택합니다.
1. **편집**을 선택한 다음 액세스 로깅을 활성화합니다.
1. **로그 대상**에 이전 단계에서 생성한 로그 그룹의 ARN을 입력합니다.
1. **로그 형식**에서 **CLF**를 선택합니다. API Gateway는 예제 로그 형식을 생성합니다.
1. 로그 형식의 끝에 `$context.integrationErrorMessage`를 추가합니다.
1. **저장**을 선택합니다.
**API 로그를 보려면**
1. 로그를 생성합니다. 브라우저 또는 `curl`을 사용하여 API를 호출합니다.
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. **모니터**에서 **로깅**을 선택합니다.
1. 로깅을 활성화한 API의 단계를 선택합니다.
1. **CloudWatch에서 로그 보기**를 선택합니다.
1. 최신 로그 스트림을 선택하여 HTTP API의 로그를 확인합니다.
1. 로그 항목은 다음과 같아야 합니다.
![\[Lambda의 통합 오류 메시지를 보여주는 CloudWatch Logs 로그 항목입니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
`$context.integrationErrorMessage`가 로그 형식에 추가되었으므로 문제를 요약해서 보여주는 오류 메시지가 로그에 표시됩니다.
Lambda 함수 코드에 문제가 있음을 나타내는 다른 오류 메시지가 로그에 포함될 수 있습니다. 이 경우 Lambda 함수 코드를 확인하고 Lambda 함수가 [필수 형식](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response)으로 응답을 반환하는지 확인합니다. 로그에 오류 메시지가 포함되어 있지 않은 경우 `$context.error.message` 및 `$context.error.responseType`를 로그 형식에 추가하여 문제를 해결하는 데 도움이 되는 자세한 내용을 확인하세요.
이 경우 API Gateway에 Lambda 함수를 호출하는 데 필요한 권한이 없는 것으로 로그에 표시됩니다.
API Gateway 콘솔에서 Lambda 통합을 생성하면 API Gateway가 Lambda 함수를 호출할 권한을 자동으로 구성합니다. AWS CLI, CloudFormation 또는 SDK를 사용하여 Lambda 통합을 생성하는 경우 API Gateway에 함수를 호출할 권한을 부여해야 합니다. 다음 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령은 다양한 HTTP API 경로에 Lambda 함수를 간접적으로 호출할 수 있는 권한을 부여합니다.
**Example 예 — HTTP API의 `$default` 스테이지 및 `$default` 라우트의 경우**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example 예 — HTTP API의 `prod` 스테이지 및 `test` 라우트의 경우**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
Lambda 콘솔의 **권한** 탭에서 [함수 정책을 확인](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)합니다.
API를 다시 호출해 보십시오. Lambda 함수의 응답이 표시되어야 합니다.
# HTTP API JWT 권한 부여자 관련 문제 해결
다음은 HTTP API에서 JSON Web Token(JWT) 권한 부여자를 사용할 때 발생할 수 있는 오류 및 문제에 대한 문제 해결 조언을 제공합니다.
## 문제: 내 API가 `401 {"message":"Unauthorized"}`를 반환합니다.
API의 응답에서 `www-authenticate` 헤더를 확인합니다.
다음 명령은 `curl`을 사용하여 `$request.header.Authorization`을 ID 소스로 사용하는 JWT 권한 부여자를 통해 API에 요청을 보냅니다.
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
API의 응답에는 `www-authenticate` 헤더가 포함됩니다.
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
이 경우 `www-authenticate` 헤더는 유효한 대상에게 토큰이 발급되지 않았음을 나타냅니다. API Gateway에서 요청을 승인하려면 JWT의 `aud` 또는 `client_id` 클레임이 권한 부여자에 대해 구성된 대상 항목 중 하나와 일치해야 합니다. API Gateway는 `aud`가 존재하지 않는 경우에만 `client_id`의 유효성을 검사합니다. `aud`와 `client_id`가 모두 있는 경우 API Gateway는 `aud`의 유효성을 검사합니다.
JWT를 디코딩하고 API에 필요한 발행자, 대상 및 범위와 일치하는지 확인할 수도 있습니다. 웹사이트 [jwt.io](https://jwt.io/)는 브라우저에서 JWT를 디버깅할 수 있습니다. OpenID Foundation에는 [JWT 작업을 위한 라이브러리 목록](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/)이 포함되어 있습니다.
JWT 권한 부여자에 대한 자세한 내용은 [API Gateway에서 JWT 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어](http-api-jwt-authorizer.md) 단원을 참조하세요.