API Gateway의 REST API에 대한 HTTP 통합 - Amazon API Gateway
API Gateway에서 HTTP 프록시 통합 설정 HTTP 사용자 지정 통합 설정

API Gateway의 REST API에 대한 HTTP 통합

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

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

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

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

API Gateway에서 HTTP 프록시 통합 설정

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 생성 단원을 참조하세요.

다음 OpenAPI 정의 파일은 PetStore 웹사이트에 통합된 프록시 리소스를 포함하는 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 사용자 지정 통합 설정

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

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

마찬가지로 메서드 응답 설정의 일부로 MethodResponse 리소스에 대한 responseParameters 속성을 설정합니다. 이를 통해 클라이언트로 디스패치될 메서드 응답 파라미터 중 어떤 것이 백엔드로부터 반환된 통합 응답 파라미터 또는 적용 가능한 특정 본문 속성으로부터 매핑되도록 할지 선언합니다. 그런 다음 통합 응답 설정의 일부로 해당 IntegrationResponse 리소스에 대한 responseParameters 속성을 설정하여 파라미터 대 파라미터 매핑을 지정합니다. 또한 requestTemplates 맵을 설정하여 지원되는 각 콘텐츠 유형에 매핑 템플릿을 지정합니다. 매핑 템플릿은 통합 응답 파라미터 또는 통합 응답 본문 속성을 메서드 응답 본문으로 매핑합니다.

매핑 템플릿 설정에 대한 자세한 내용은 API Gateway에서 REST API의 데이터 변환 단원을 참조하세요.