# 사용자 지정 런타임을 위한 Lambda 런타임 API 사용
AWS Lambda은 [사용자 지정 런타임](runtimes-custom.md)에 HTTP API를 제공하여 Lambda에서 호출 이벤트를 수신하고 Lambda [실행 환경](lambda-runtimes.md) 내에서 응답 데이터를 다시 전송합니다. 이 섹션에서는 Lambda 런타임 API에 대한 API 참조에 대해 알아봅니다.
**Lambda 관리형 인스턴스 동시 요청 지원**
Lambda 관리형 인스턴스는 Lambda(기본값) 함수와 동일한 런타임 API를 사용합니다. 큰 차이점은 관리형 인스턴스가 구성된 `AWS_LAMBDA_MAX_CONCURRENCY` 제한까지 동시 `/next` 및 `/response` 요청을 수락할 수 있다는 것입니다. 이를 통해 단일 실행 환경 내에서 여러 개의 간접 호출을 동시에 처리할 수 있습니다. 관리형 인스턴스에 대한 자세한 내용은 [Lambda 관리형 인스턴스 실행 환경 이해](lambda-managed-instances-execution-environment.md) 항목을 참조하세요.
![\[실행 환경의 아키텍처 다이어그램.\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/telemetry-api-concept-diagram.png)
런타임 API 버전 **2018-06-01**에 대한 OpenAPI 사양은 [runtime-api.zip](samples/runtime-api.zip)에서 사용할 수 있습니다.
API 요청 URL을 만들려면 런타임에서 `AWS_LAMBDA_RUNTIME_API` 환경 변수에서 API 엔드포인트를 가져오고 API 버전을 추가한 다음 원하는 리소스 경로를 추가합니다.
**Example 요청**
```
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"
```
**Topics**
+ [다음 호출](#runtimes-api-next)
+ [호출 응답](#runtimes-api-response)
+ [초기화 오류](#runtimes-api-initerror)
+ [호출 오류](#runtimes-api-invokeerror)
## 다음 호출
**경로** – `/runtime/invocation/next`
**메서드** – **GET**
런타임에서는 호출 이벤트를 요청하기 위해 이 메시지를 Lambda로 보냅니다. 응답 본문에는 호출의 페이로드가 포함되어 있습니다. 이 페이로드는 함수 트리거의 이벤트 데이터를 포함하는 JSON 문서입니다. 응답 헤더에는 호출에 대한 추가 데이터가 포함되어 있습니다.
**응답 헤더**
+ `Lambda-Runtime-Aws-Request-Id` – 함수 호출을 트리거한 요청을 식별하는 요청 ID입니다.
예를 들어 `8476a536-e9f4-11e8-9739-2dfe598c3fcd`입니다.
+ `Lambda-Runtime-Deadline-Ms` – 함수가 Unix 시간 형식에 따른 밀리초 단위의 시간 제한에 도달하는 날짜입니다.
예를 들어 `1542409706888`입니다.
+ `Lambda-Runtime-Invoked-Function-Arn` – 호출에 지정된 Lambda 함수, 버전 또는 별칭의 ARN입니다.
예를 들어 `arn:aws:lambda:us-east-2:123456789012:function:custom-runtime`입니다.
+ `Lambda-Runtime-Trace-Id` – [AWS X-Ray 추적 헤더](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)입니다.
예를 들어 `Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1`입니다.
+ `Lambda-Runtime-Client-Context` – AWS Mobile SDK 호출에서 클라이언트 애플리케이션 및 디바이스에 관한 데이터입니다.
+ `Lambda-Runtime-Cognito-Identity` – AWS Mobile SDK 호출에서 Amazon Cognito 자격 증명 공급자에 관한 데이터입니다.
응답이 지연될 수 있으므로 `GET` 요청에 시간 제한을 설정하지 마세요. Lambda가 런타임을 부트스트랩하는 시점과 런타임에 반환할 이벤트가 있는 시점 사이에 런타임 프로세스가 몇 초 동안 동결될 수 있습니다.
요청 ID는 Lambda 내에서 호출을 추적합니다. 응답을 전송할 때에는 이 ID를 사용하여 호출을 지정합니다.
트레이스 헤더에는 추적 ID, 상위 ID 및 샘플링 결정이 포함되어 있습니다. 요청이 샘플링될 경우, 이 요청은 Lambda 또는 업스트림 서비스에 의해 샘플링된 것입니다. 런타임은 헤더의 값을 사용해 `_X_AMZN_TRACE_ID`을 설정해야 합니다. X-Ray SDK는 이 값을 판독하여 ID를 가져온 다음, 요청을 추적할지 여부를 결정합니다.
## 호출 응답
**경로** – `/runtime/invocation/AwsRequestId/response`
**메서드** – **POST**
함수가 완료될 때까지 실행되면 런타임은 호출 응답을 Lambda로 보냅니다. 동기식 간접 호출의 경우, Lambda는 응답을 클라이언트로 보냅니다.
**Example 성공 요청**
```
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "SUCCESS"
```
## 초기화 오류
함수가 오류를 반환하거나 런타임에서 초기화 중에 오류가 발생하면 런타임에서는 이 메서드를 사용하여 Lambda에 오류를 보고합니다.
**경로** – `/runtime/init/error`
**메서드** – **POST**
**헤더**
`Lambda-Runtime-Function-Error-Type` – 런타임에서 발생한 오류 유형입니다. 필수 항목 여부: 아니요
이 헤더는 문자열 값으로 구성됩니다. Lambda는 모든 문자열을 허용하지만 형식을 사용하는 것이 좋습니다. 예:
+ Runtime.NoSuchHandler
+ Runtime.APIKeyNotFound
+ Runtime.ConfigInvalid
+ Runtime.UnknownReason
**본문 파라미터**
`ErrorRequest` – 오류에 대한 정보입니다. 필수 항목 여부: 아니요
이 필드는 다음과 같은 구조의 JSON 객체입니다.
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Lambda는 `errorType`에 대한 모든 값을 허용합니다.
다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.
**Example 함수 오류**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**응답 본문 파라미터**
+ `StatusResponse` – 문자열. 상태 정보, 202 응답 코드와 함께 전송됨.
+ `ErrorResponse` – 오류 응답 코드와 함께 전송되는 추가 오류 정보입니다. ErrorResponse는 오류 유형과 오류 메시지가 포함되어 있습니다.
**응답 코드**
+ 202 - 수락됨
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 런타임을 신속히 종료해야 합니다.
**Example 초기화 오류 요청**
```
ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"
```
## 호출 오류
함수가 오류를 반환하거나 런타임에 오류가 발생하면 런타임에서는 이 메서드를 사용하여 오류를 Lambda에 보고합니다.
**경로** – `/runtime/invocation/AwsRequestId/error`
**메서드** – **POST**
**헤더**
`Lambda-Runtime-Function-Error-Type` – 런타임에서 발생한 오류 유형입니다. 필수 항목 여부: 아니요
이 헤더는 문자열 값으로 구성됩니다. Lambda는 모든 문자열을 허용하지만 형식을 사용하는 것이 좋습니다. 예:
+ Runtime.NoSuchHandler
+ Runtime.APIKeyNotFound
+ Runtime.ConfigInvalid
+ Runtime.UnknownReason
**본문 파라미터**
`ErrorRequest` – 오류에 대한 정보입니다. 필수 항목 여부: 아니요
이 필드는 다음과 같은 구조의 JSON 객체입니다.
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Lambda는 `errorType`에 대한 모든 값을 허용합니다.
다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.
**Example 함수 오류**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**응답 본문 파라미터**
+ `StatusResponse` – 문자열. 상태 정보, 202 응답 코드와 함께 전송됨.
+ `ErrorResponse` – 오류 응답 코드와 함께 전송되는 추가 오류 정보입니다. ErrorResponse는 오류 유형과 오류 메시지가 포함되어 있습니다.
**응답 코드**
+ 202 - 수락됨
+ 400 - 잘못된 요청
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 런타임을 신속히 종료해야 합니다.
**Example 오류 요청**
```
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"
```