# API Gateway의 REST API에 대한 HTTP 통합
<a name="setup-http-integrations"></a>

 HTTP 프록시 통합 또는 HTTP 사용자 지정 통합을 사용하여 API 메서드를 HTTP 엔드포인트와 통합할 수 있습니다.

API Gateway는 80, 443, 1024-65535 엔드포인트 포트를 지원합니다.

 프록시 통합을 사용하면 설정이 간단합니다. 콘텐츠 인코딩 또는 캐싱에 관심이 없다면 백엔드 요구 사항에 따라 HTTP 메서드 및 HTTP 엔드포인트 URI를 설정하기만 하면 됩니다.

 사용자 지정 통합은 설정이 이보다 복잡합니다. 프록시 통합 설정 단계 외에도 수신 요청 데이터가 통합 요청에 매핑되는 방식과 그 결과로 얻는 통합 응답 데이터가 메서드 응답에 매핑되는 방식을 지정해야 합니다.

**Topics**
+ [API Gateway에서 HTTP 프록시 통합 설정](#api-gateway-set-up-http-proxy-integration-on-proxy-resource)
+ [API Gateway에서 HTTP 사용자 지정 통합 설정](#set-up-http-custom-integrations)

## API Gateway에서 HTTP 프록시 통합 설정
<a name="api-gateway-set-up-http-proxy-integration-on-proxy-resource"></a>

HTTP 프록시 통합 유형을 사용하여 프록시 리소스를 설정하려면 복잡한 경로 파라미터(예: `/parent/{proxy+}`)를 사용하여 API 리소스를 생성한 후 이 리소스를 `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}` 메서드의 HTTP 백엔드 엔드포인트(예: `ANY`)와 통합합니다. 복잡한 경로 파라미터는 리소스 경로의 끝에 와야 합니다.

비 프록시 리소스를 사용할 때와 마찬가지로 API Gateway 콘솔을 사용하거나, OpenAPI 정의 파일을 가져오거나, API Gateway REST API를 직접 호출하여 HTTP 프록시 통합을 통해 프록시 리소스를 설정할 수 있습니다. API Gateway 콘솔을 사용하여 HTTP 프록시 통합을 통해 프록시 리소스를 구성하는 방법에 대한 자세한 내용은 [자습서: HTTP 프록시 통합을 통해 REST API 생성](api-gateway-create-api-as-simple-proxy-for-http.md) 단원을 참조하세요.

다음 OpenAPI 정의 파일은 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) 웹사이트에 통합된 프록시 리소스를 포함하는 API의 예를 보여줍니다.

------
#### [ OpenAPI 3.0 ]

```
{
   "openapi": "3.0.0",
   "info": {
      "version": "2016-09-12T23:19:28Z",
      "title": "PetStoreWithProxyResource"
   },
   "paths": {
      "/{proxy+}": {
         "x-amazon-apigateway-any-method": {
            "parameters": [
               {
                  "name": "proxy",
                  "in": "path",
                  "required": true,
                  "schema": {
                     "type": "string"
                  }
               }
            ],
            "responses": {},
            "x-amazon-apigateway-integration": {
               "responses": {
                  "default": {
                     "statusCode": "200"
                  }
               },
               "requestParameters": {
                  "integration.request.path.proxy": "method.request.path.proxy"
               },
               "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
               "passthroughBehavior": "when_no_match",
               "httpMethod": "ANY",
               "cacheNamespace": "rbftud",
               "cacheKeyParameters": [
                  "method.request.path.proxy"
               ],
               "type": "http_proxy"
            }
         }
      }
   },
   "servers": [
      {
         "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ]
}
```

------
#### [ OpenAPI 2.0 ]

```
{
  "swagger": "2.0",
  "info": {
    "version": "2016-09-12T23:19:28Z",
    "title": "PetStoreWithProxyResource"
  },
  "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
  "basePath": "/test",
  "schemes": [
    "https"
  ],
  "paths": {
    "/{proxy+}": {
      "x-amazon-apigateway-any-method": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "proxy",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {},
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.path.proxy": "method.request.path.proxy"
          },
          "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "ANY",
          "cacheNamespace": "rbftud",
          "cacheKeyParameters": [
            "method.request.path.proxy"
          ],
          "type": "http_proxy"
        }
      }
    }
  }
}
```

------

이 예에서 캐시 키는 프록시 리소스의 `method.request.path.proxy` 경로 파라미터에 선언됩니다. 이는 API Gateway 콘솔을 사용하여 API를 생성할 때의 기본 설정입니다. API의 기본 경로(`/test`, 단계에 해당함)는 웹사이트의 PetStore 페이지(`/petstore`)에 매핑됩니다. 단일 통합 요청으로 API의 복잡한 경로 변수와 완전 포착(catch-all) `ANY` 메서드를 사용하여 전체 PetStore 웹사이트를 미러링합니다. 다음 예에서는 이 미러링을 보여줍니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets`로 설정**

  프런트엔드에서 시작되는 메서드 요청:

  ```
  GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
  ```

  백엔드로 전송되는 통합 요청:

  ```
  GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
  ```

  `ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 반려 동물의 첫 번째 배치를 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets?type=dog`로 설정**

  ```
  GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
  ```

  백엔드로 전송되는 통합 요청:

  ```
  GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
  ```

  `ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 지정된 개의 첫 번째 배치를 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets/{petId}`로 설정**

  프런트엔드에서 시작되는 메서드 요청:

  ```
  GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
  ```

  백엔드로 전송되는 통합 요청:

  ```
  GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
  ```

  `ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 지정된 반려 동물을 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `POST`으로 설정하고 `{proxy+}`를 `pets`로 설정**

  프런트엔드에서 시작되는 메서드 요청:

  ```
  POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
  Content-Type: application/json
  Content-Length: ...
  
  {
    "type" : "dog",
    "price" : 1001.00
  }
  ```

  백엔드로 전송되는 통합 요청:

  ```
  POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
  Content-Type: application/json
  Content-Length: ...
  
  {
    "type" : "dog",
    "price" : 1001.00
  }
  ```

  `ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 새로 생성된 반려 동물을 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets/cat`로 설정**

  프런트엔드에서 시작되는 메서드 요청:

  ```
  GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
  ```

  백엔드로 전송되는 통합 요청:

  ```
  GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
  ```

  프록시 리소스 경로의 런타임 인스턴스가 백엔드 엔드포인트와 일치하지 않고 결과 요청이 잘못되었습니다. 따라서 `400 Bad Request` 응답이 다음 오류 메시지와 함께 반환됩니다.

  ```
  {
    "errors": [
      {
        "key": "Pet2.type",
        "message": "Missing required field"
      },
      {
        "key": "Pet2.price",
        "message": "Missing required field"
      }
    ]
  }
  ```
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `null`로 설정**

  프런트엔드에서 시작되는 메서드 요청:

  ```
  GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
  ```

  백엔드로 전송되는 통합 요청:

  ```
  GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
  ```

  타겟 리소스는 프록시 리소스의 상위이지만, `ANY` 메서드의 런타임 인스턴스가 해당 리소스의 API에 정의되어 있지 않습니다. 따라서 이 `GET` 요청은 API Gateway에서 반환되는 `403 Forbidden` 오류 메시지와 함께 `Missing Authentication Token` 응답을 반환합니다. API가 상위 리소스(`ANY`)에 `GET` 또는 `/` 메서드를 공개할 경우 이 호출은 백엔드에서 반환되는 `404 Not Found` 메시지와 함께 `Cannot GET /petstore` 응답을 반환합니다.

클라이언트 요청에 대해 타겟 엔드포인트 URL이 잘못되거나 HTTP 동사가 유효하지만 지원되지 않는 경우 백엔드에서 `404 Not Found` 응답을 반환합니다. 지원되지 않는 HTTP 메서드의 경우 `403 Forbidden` 응답이 반환됩니다.

## API Gateway에서 HTTP 사용자 지정 통합 설정
<a name="set-up-http-custom-integrations"></a>

 HTTP 사용자 지정 통합(다른 명칭: 비프록시 통합)에서는 API 메서드와 API 통합 간에 전달할 데이터와 그 데이터를 전달하는 방식을 제어할 수 있는 권한이 더 많습니다. 이러한 제어는 데이터 매핑을 통해 할 수 있습니다.

메서드 요청 설정의 일부로 [메서드](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스에 대한 [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters)속성을 설정입니다. 이를 통해 클라이언트로부터 프로비저닝되는 메서드 요청 파라미터 중 어떤 것이 백엔드로 디스패치되기 전에 통합 요청 파라미터 또는 적용 가능한 본문 속성에 매핑되도록 할지 선언합니다. 그런 다음 통합 요청 설정의 일부로 해당 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) 속성을 설정하여 파라미터 대 파라미터 매핑을 지정합니다. 또한 [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) 속성을 설정하여 지원되는 각 콘텐츠 유형에 매핑 템플릿을 지정합니다. 매핑 템플릿은 메서드 요청 파라미터 또는 본문을 통합 요청 본문으로 매핑합니다.

 마찬가지로 메서드 응답 설정의 일부로 [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스에 대한 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) 속성을 설정합니다. 이를 통해 클라이언트로 디스패치될 메서드 응답 파라미터 중 어떤 것이 백엔드로부터 반환된 통합 응답 파라미터 또는 적용 가능한 특정 본문 속성으로부터 매핑되도록 할지 선언합니다. 그런 다음 백엔드의 응답을 기반으로 통합 응답을 선택하도록 [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)을 설정합니다. 비프록시 HTTP 통합의 경우 이는 정규식입니다. 예를 들어 모든 2xx HTTP 응답 상태 코드를 HTTP 엔드포인트에서 이 출력 매핑으로 매핑하려면 `2\d{2}`를 사용합니다.

**참고**  
API Gateway는 응답 매핑을 위해서 Java 패턴 스타일 정규식을 사용합니다. 자세한 내용은 Oracle 설명서의 [패턴 ](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) 단원을 참조하세요

그런 다음 통합 응답 설정의 일부로 해당 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스에 대한 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) 속성을 설정하여 파라미터 대 파라미터 매핑을 지정합니다. 또한 [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) 맵을 설정하여 지원되는 각 콘텐츠 유형에 매핑 템플릿을 지정합니다. 매핑 템플릿은 통합 응답 파라미터 또는 통합 응답 본문 속성을 메서드 응답 본문으로 매핑합니다.

 매핑 템플릿 설정에 대한 자세한 내용은 [API Gateway에서 REST API의 데이터 변환](rest-api-data-transformations.md) 단원을 참조하세요.