API 매핑을 사용하여 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 연결합니다. - Amazon API Gateway
사용자 지정 도메인 이름에 대한 수신 요청API 요청 매핑제한 사항API 매핑 생성

API 매핑을 사용하여 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 연결합니다.

API 매핑을 사용하여 API 스테이지를 사용자 지정 도메인 이름에 연결합니다. 이렇게 하면 사용자 지정 도메인 이름을 통해 API로 트래픽이 전송됩니다.

API 매핑은 API, 스테이지 및 매핑에 사용할 경로(선택 사항)를 지정합니다. 예를 들어 https://api.example.com/orders를 API의 production 스테이지에 매핑할 수 있습니다.

HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑할 수 있습니다.

API 매핑을 생성하기 전에 API, 스테이지 및 사용자 지정 도메인 이름이 있어야 합니다. 사용자 지정 도메인 이름 생성에 대한 자세한 내용은 ‭API Gateway에서 리전 사용자 지정 도메인 이름 설정‬ 단원을 참조하세요.

사용자 지정 도메인 이름에 대한 수신 요청

사용자 지정 도메인 이름을 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은(는) 선택 항목에 영향을 주지 않습니다. 사용자 지정 도메인 이름에 대한 수신 요청을(를) 참조하세요.

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로 설정되어 있어야 합니다. 라우팅 모드를 설정하는 방법에 대한 자세한 내용은 사용자 지정 도메인 이름의 라우팅 모드 설정 섹션을 참조하세요.

예를 들어 모든 리소스를 생성하는 AWS Serverless Application Model 템플릿에 대해서는 GitHub의 SAM 세션을 참조하세요.

AWS Management Console

  1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  2. 기본 탐색 창에서 사용자 지정 도메인 이름을 선택합니다.

  3. 사용자 지정 도메인 이름을 선택합니다.

  4. 라우팅 세부 정보 탭에서 API 매핑 구성을 선택합니다.

  5. 매핑에 대한 API, 스테이지 및 경로를 입력합니다.

  6. 저장을 선택합니다.

AWS CLI

다음 create-api-mapping 명령은 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
AWS CloudFormation

다음 AWS 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