# x-amazon-apigateway-integration 객체
<a name="api-gateway-swagger-extensions-integration"></a>

 이 메서드에 사용된 백엔드 통합의 세부 정보를 지정합니다. 이 확장은 [OpenAPI 작업](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) 객체의 확장된 속성입니다. 결과는 [API Gateway 통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 객체입니다.


| 속성 이름 | 유형 | 설명 | 
| --- | --- | --- | 
| cacheKeyParameters | string의 어레이 | 값을 캐시할 요청 파라미터의 목록입니다. | 
| cacheNamespace | string | 캐시된 관련 파라미터의 API 관련 태그 그룹입니다. | 
| connectionId | string | 프라이빗 통합을 위한 [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html)의 ID. | 
| connectionType | string | 통합 연결 유형. 유효 값은 프라이빗 통합의 경우, "VPC\_LINK"이고 그 밖의 경우에는 "INTERNET"입니다. | 
| credentials | string |  AWS IAM 역할 기반 자격 증명에 대해 해당하는 IAM 역할의 ARN을 지정하세요. 지정되어 있지 않으면 자격 증명이 기본적으로 리소스 기반 권한으로 설정되어 API가 리소스에 액세스할 수 있으려면 이 권한을 수동으로 추가해야 합니다. 자세한 내용은 [리소스 정책을 사용하여 권한 부여](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy) 단원을 참조하세요.<br />참고: IAM 자격 증명을 사용할 때 최상의 성능을 위해 이 API가 배포된 리전에서 [AWS STS 리전 엔드포인트](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html)가 활성화되어 있는지 확인하세요. | 
| contentHandling | string | 요청 페이로드 인코딩 변환 유형입니다. 유효한 값은 1) 이진 페이로드를 Base64 인코딩 문자열로 변환하거나, 텍스트 페이로드를 CONVERT\_TO\_TEXT 인코딩 문자열로 변환하거나, 기본적으로 수정 없이 텍스트 페이로드를 패스스루하는 경우에는 utf-8이고, 2) 텍스트 페이로드를 Base64 디코딩 BLOB로 변환하거나 기본적으로 수정 없이 이진 페이로드를 패스스루하는 경우에는 CONVERT\_TO\_BINARY입니다. | 
| httpMethod | string |  통합 요청에서 사용된 HTTP 메서드입니다. Lambda 함수 호출의 경우 값은 POST여야 합니다. | 
| integrationSubtype | string | AWS 서비스 통합에 대한 통합 하위 유형을 지정합니다. HTTP API에서만 지원됩니다. 지원되는 통합 하위 유형은 [통합 하위 유형 참조](http-api-develop-integrations-aws-services-reference.md) 단원을 참조하세요. | 
| integrationTarget | string | 요청을 보낼 ALB 또는 NLB 리스너입니다. VPC 링크 V2를 사용하는 프라이빗 통합에만 지원됩니다. 자세한 내용은 [API Gateway에서 VPC 링크 V2 설정](apigateway-vpc-links-v2.md) 섹션을 참조하세요. | 
| passthroughBehavior | string |  매핑되지 않은 콘텐츠 형식의 요청 페이로드를 수정 없이 통합 요청을 통해 전달하는 방식을 지정합니다. 지원되는 값은 when\_no\_templates, when\_no\_match 및 never입니다. 자세한 내용은 [Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior)를 참조하세요. | 
| payloadFormatVersion | string | 통합으로 전송되는 페이로드의 형식을 지정합니다. HTTP API에 필요합니다. HTTP API의 경우 Lambda 프록시 통합에 대해 지원되는 값은 1.0 및 2.0입니다. 다른 모든 통합의 경우 1.0은 유일하게 지원되는 값입니다. 자세한 내용은 [API Gateway에서 HTTP API에 대한 AWS Lambda 프록시 통합 생성](http-api-develop-integrations-lambda.md) 및 [통합 하위 유형 참조](http-api-develop-integrations-aws-services-reference.md) 단원을 참조하세요. | 
| requestParameters | [x-amazon-apigateway-integration.requestParameters 객체](api-gateway-swagger-extensions-integration-requestParameters.md) | REST API의 경우 메서드 요청 파라미터에서 통합 요청 파라미터로의 매핑을 지정합니다. 지원되는 요청 파라미터는 `querystring`, `path`, `header` 및 `body`입니다.<br />HTTP API의 경우 요청 파라미터는 지정된 `AWS_PROXY`과의 `integrationSubtype` 통합에 전달되는 파라미터를 지정하는 키-값 맵입니다. 정적 값을 제공하거나 런타임 시 평가되는 요청 데이터, 스테이지 변수 또는 컨텍스트 변수를 매핑할 수 있습니다. 자세한 내용은 [API Gateway에서 HTTP API에 대한 AWS 서비스 통합 생성](http-api-develop-integrations-aws-services.md) 단원을 참조하세요. | 
| requestTemplates | [x-amazon-apigateway-integration.requestTemplates 객체](api-gateway-swagger-extensions-integration-requestTemplates.md) | 지정된 MIME 유형의 요청 페이로드에 대한 매핑 템플릿입니다. | 
| responses | [x-amazon-apigateway-integration.responses 객체](api-gateway-swagger-extensions-integration-responses.md) | 메서드의 응답을 정의하고 통합 응답에서 메서드 응답으로 원하는 파라미터 매핑 또는 페이로드 매핑을 지정합니다. | 
| responseTransferMode | string | 통합의 응답 전송 모드입니다. API Gateway가 전송을 시작하기 전에 전체 응답을 수신할 때까지 기다리도록 하려면 BUFFERED를 사용합니다. API Gateway가 부분 응답을 사용할 수 있게 되었을 때 클라이언트에 다시 보내도록 하려면 STREAM을 사용합니다. 자세한 내용은 [API Gateway에서 프록시 통합에 대한 통합 응답 스트리밍](response-transfer-mode.md)를 참조하세요. | 
| timeoutInMillis | integer | 50ms\~29,000ms 사이의 통합 제한 시간. | 
| type | string | 지정된 백엔드와의 통합 유형입니다. 유효한 값은 다음과 같습니다.[See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html)<br />통합 유형에 대한 자세한 내용은 [integration:type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type)을 참조하세요. | 
| tlsConfig | [x-amazon-apigateway-integration.tlsConfig 객체](api-gateway-extensions-integration-tls-config.md) | 통합을 위한 TLS 구성을 지정합니다. | 
| uri | string | 백엔드의 엔드포인트 URI입니다. aws 유형 통합의 경우 이는 ARN 값입니다. HTTP 통합의 경우 이는 https 또는 http 스키마를 포함한 HTTP 엔드포인트의 URL입니다. | 

## x-amazon-apigateway-integration 예제
<a name="api-gateway-swagger-extensions-integration-example"></a>

HTTP API의 경우, OpenAPI 정의의 구성 요소 섹션에서 통합을 정의할 수 있습니다. 자세한 내용은 [x-amazon-apigateway-integrations 객체](api-gateway-extensions-integrations.md) 단원을 참조하세요.

```
"x-amazon-apigateway-integration": {
    "$ref": "#/components/x-amazon-apigateway-integrations/{{integration1}}"
}
```

 다음 예제에서는 Lambda 함수와의 통합을 생성합니다. 데모를 위해 `requestTemplates`에 표시된 샘플 매핑 템플릿과 아래 예의 `responseTemplates`는 `{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }`의 JSON 출력 또는 `{ "stage":"value_1", "user-id":"value_2" }`의 XML 출력을 생성하기 위해 다음 JSON 형식의 페이로드에 적용되는 것으로 가정됩니다. `<stage>value_1</stage>` 

```
"x-amazon-apigateway-integration" : {
    "type" : "aws",
    "uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",
    "httpMethod" : "POST",
    "credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role",
    "requestTemplates" : {
                "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
                "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
    },
    "requestParameters" : {
        "integration.request.path.{{stage}}" : "method.request.querystring.{{version}}",
        "integration.request.querystring.{{provider}}" : "method.request.querystring.{{vendor}}"
    },
    "cacheNamespace" : "cache namespace",
    "cacheKeyParameters" : [],
    "responses" : {
        "2\\d{2}" : {
            "statusCode" : "200",
            "responseParameters" : {
                "method.response.header.{{requestId}}" : "integration.response.header.{{cid}}"
            },
            "responseTemplates" : {
                "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
                "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
            }
        },
        "302" : {
            "statusCode" : "302",
            "responseParameters" : {
                "method.response.header.Location" : "integration.response.body.{{redirect.url}}"
            }
        },
        "default" : {
            "statusCode" : "400",
            "responseParameters" : {
                "method.response.header.{{test-method-response-header}}" : "{{'static value'}}"
            }
        }
    }
}
```

매핑 템플릿에서 JSON 문자열의 큰따옴표 (")는 문자열 이스케이프 (\\")여야 합니다.