# API 매핑을 사용하여 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 연결합니다.
API 매핑을 사용하여 API 스테이지를 사용자 지정 도메인 이름에 연결합니다. 이렇게 하면 사용자 지정 도메인 이름을 통해 API로 트래픽이 전송됩니다.
API 매핑은 API, 스테이지 및 매핑에 사용할 경로(선택 사항)를 지정합니다. 예를 들어 `https://api.example.com/orders`를 API의 `production` 스테이지에 매핑할 수 있습니다.
HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑할 수 있습니다.
API 매핑을 생성하기 전에 API, 스테이지 및 사용자 지정 도메인 이름이 있어야 합니다. 사용자 지정 도메인 이름 생성에 대한 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
## 사용자 지정 도메인 이름에 대한 수신 요청
사용자 지정 도메인 이름을 API의 스테이지에 매핑하면 API Gateway가 수신되는 기본 경로를 제거합니다. 이렇게 하면 API에 대한 간접 호출에서 매핑된 기본 경로가 제거됩니다. 예를 들어 기본 경로가 `https://api.example.com/orders/shop/5`에서 `test` 스테이지로 매핑되어 있고 `https://api.example.com/orders/shop/5/hats` 요청을 사용한 경우, API Gateway는 `orders/shop/5/hats` 리소스가 아닌 API `test` 스테이지의 `/hats` 리소스를 간접적으로 호출합니다.
## API 요청 매핑
다음은 API Gateway가 API 매핑을 평가하는 방법을 설명합니다.
`orders`에서 API `beta` 스테이지로의 API 매핑 및 `shipping`에서 API `alpha` 스테이지로의 API 매핑과 같은 단일 수준 매핑을 사용하여 API 매핑을 만들 수 있습니다. TLS 1.2 보안 정책을 사용하는 리전 사용자 지정 도메인 이름의 경우 API Gateway는 다단계 API 매핑을 지원합니다. `orders/v1/items`에서 API `alpha` 스테이지와 `orders/v2/items`에서 API `beta` 스테이지로의 API 매핑을 만들 수 있습니다. 여러 수준을 사용하여 매핑을 만드는 경우 API Gateway는 일치하는 경로가 가장 긴 API 매핑으로 요청을 전송합니다.
빈 경로 `(none)`에 대한 API 매핑을 만들 수 있습니다. 요청과 일치하는 경로가 없으면 API Gateway는 빈 경로 `(none)`에 요청을 보냅니다.
다음 예제에서는 사용자 지정 도메인 이름 `https://api.example.com`에 다음 API 매핑이 있습니다.
| API 매핑 | 선택한 API |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
다음 표는 API Gateway가 이전 API 매핑을 예제 요청에 적용하는 방법을 보여줍니다.
| 요청 | 선택한 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`은(는) 선택 항목에 영향을 주지 않습니다. [사용자 지정 도메인 이름에 대한 수신 요청](#rest-api-mappings-incoming-requests)을(를) 참조하세요. |
| `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 매핑을 생성한 후에는 DNS 공급자의 리소스 레코드를 생성하거나 업데이트하여 API 엔드포인트에 매핑해야 합니다.
+ 여러 레벨로 API 매핑을 생성하는 경우 API Gateway는 모든 헤더 이름을 소문자로 변환합니다.
## API 매핑 생성
API 매핑을 생성하려면 먼저 사용자 지정 도메인 이름, API 및 스테이지를 생성해야 합니다. 사용자 지정 도메인 이름에는 라우팅 모드가 `ROUTING_RULE_THEN_API_MAPPING` 또는 `API_MAPPING_ONLY`로 설정되어 있어야 합니다. 라우팅 모드를 설정하는 방법에 대한 자세한 내용은 [사용자 지정 도메인 이름의 라우팅 모드 설정](set-routing-mode.md) 섹션을 참조하세요.
예를 들어 모든 리소스를 생성하는 AWS Serverless Application Model 템플릿에 대해서는 GitHub의 [SAM 세션](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)을 참조하세요.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. 사용자 지정 도메인 이름을 선택합니다.
1. **라우팅 세부 정보** 탭에서 **API 매핑 구성**을 선택합니다.
1. 매핑에 대한 **API**, **스테이지** 및 **경로**를 입력합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) 명령은 API 매핑을 생성합니다. 이 예에서 API Gateway는 지정된 API 및 스테이지로 `api.example.com/v1/orders` 요청을 보냅니다.
**참고**
여러 수준으로 API 매핑을 생성하려면 `apigatewayv2`을(를) 사용해야 합니다.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
다음 CloudFormation 예에서는 API 매핑을 생성합니다.
**참고**
여러 수준으로 API 매핑을 생성하려면 `AWS::ApiGatewayV2`을(를) 사용해야 합니다.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------