커스텀 런타임용 Lambda 런타임 API 사용

AWS Lambda는 커스텀 런타임이 Lambda에서 호출 이벤트를 받고 Lambda 실행 환경 내에서 응답 데이터를 다시 보낼 수 있도록 HTTP API를 제공해요. 이 섹션은 Lambda 런타임 API의 API 참조를 담고 있어요.

Lambda Managed Instances는 동시 요청을 지원합니다
Lambda Managed Instances는 Lambda(기본) 함수와 동일한 런타임 API를 사용해요. 핵심 차이는 Managed Instances가 구성된 AWS_LAMBDA_MAX_CONCURRENCY 한도까지 동시 /next 및 /response 요청을 받아들일 수 있다는 점이에요. 이 덕분에 단일 실행 환경 내에서 여러 호출을 동시에 처리할 수 있죠. Managed Instances에 대한 자세한 내용은 Lambda Managed Instances 실행 환경 이해를 참고하세요.

실행 환경의 아키텍처 다이어그램.

런타임 API 버전 2018-06-01의 OpenAPI 사양은 runtime-api.zip에서 확인할 수 있어요.

API 요청 URL을 만들려면 런타임이 AWS_LAMBDA_RUNTIME_API 환경 변수에서 API 엔드포인트를 가져와 API 버전을 추가하고, 원하는 리소스 경로를 추가하면 됩니다.

예제 요청

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

출처: AWS Lambda 개발자 안내서

본문

Topics(주제)

다음 호출
호출 응답
초기화 오류
호출 오류
복원 후(After-Restore, SnapStart에만 적용)
복원 오류(Restore error, SnapStart에만 적용)

다음 호출(Next invocation)

경로 – /runtime/invocation/next

메서드 – GET

런타임은 Lambda에 호출 이벤트를 요청하기 위해 이 메시지를 보내요. 응답 본문에는 호출 페이로드가 담겨 있으며, 이는 함수 트리거의 이벤트 데이터가 들어 있는 JSON 문서예요. 응답 헤더에는 호출에 대한 추가 데이터가 포함되죠.

응답 헤더

Lambda-Runtime-Aws-Request-Id – 함수 호출을 트리거한 이벤트예요. 이벤트 소스가 요청 ID를 제공하거나 Lambda가 수신 시 자동 생성해요. 하나의 요청 ID는 여러 번의 호출 시도로 이어질 수 있어요. 응답이나 오류를 보낼 때 URL 경로에서 사용하세요.

예를 들어 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 추적 헤더예요.

예를 들어 Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.
Lambda-Runtime-Client-Context – AWS Mobile SDK에서의 호출용으로, 클라이언트 애플리케이션과 디바이스에 대한 데이터예요.
Lambda-Runtime-Cognito-Identity – AWS Mobile SDK에서의 호출용으로, Amazon Cognito 자격 증명 공급자에 대한 데이터예요.
Lambda-Runtime-Invocation-Id – 이 호출 시도의 고유 식별자예요.

응답이 지연될 수 있으므로 GET 요청에는 타임아웃을 설정하지 마세요. Lambda가 런타임을 부트스트랩한 시점부터 런타임이 반환할 이벤트가 생길 때까지, 런타임 프로세스가 몇 초 동안 멈춰 있을 수 있어요.

요청 ID(Lambda-Runtime-Aws-Request-Id)는 고유 이벤트를 식별해요. 요청 ID는 이벤트 소스가 제공하거나 Lambda가 수신 시 자동 생성해요. 응답이나 오류를 보낼 때 URL 경로에서 요청 ID를 사용하세요.

호출 ID(Lambda-Runtime-Invocation-Id)는 이벤트에 대한 단일 호출 시도를 나타내요. 하나의 요청 ID는 여러 번의 호출 시도로 이어질 수 있으며, 각 시도는 고유한 호출 ID를 가져요. Lambda는 각 호출 ID를 정확히 한 번만 사용하고 절대 재사용하지 않아요. /response 및 /error 호출에서 이 값을 그대로 다시 보내세요. 이 헤더는 기존 런타임과의 하위 호환성을 위해 선택 사항이며, 생략해도 거부가 발생하진 않아요. Lambda는 헤더가 있는데 그 값이 활성 호출과 일치하지 않을 때만 400 InvalidInvocationId로 거부해요.

추적 헤더에는 추적 ID, 부모 ID, 샘플링 결정이 포함돼요. 요청이 샘플링되면 그 요청은 Lambda 또는 업스트림 서비스에 의해 샘플링된 거예요. 런타임은 이 헤더의 값으로 _X_AMZN_TRACE_ID를 설정해야 해요. X-Ray SDK는 이 값을 읽어 ID를 얻고 요청을 추적할지 결정해요.

호출 응답(Invocation response)

경로 – /runtime/invocation/{{AwsRequestId}}/response

메서드 – POST

함수가 완료까지 실행된 후 런타임은 호출 응답을 Lambda로 보내요. 동기식 호출의 경우 Lambda가 응답을 클라이언트로 전송해요.

요청 헤더

Lambda-Runtime-Invocation-Id – /next에서 받은 값을 그대로 다시 보내세요. 값이 활성 호출과 일치하지 않으면 Lambda는 400 InvalidInvocationId로 요청을 거부해요.

예제 성공 요청

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

초기화 오류(Initialization error)

함수가 오류를 반환하거나 런타임이 초기화 중 오류를 만나면, 런타임은 이 메서드를 사용해 오류를 Lambda에 보고해요.

경로 – /runtime/init/error

메서드 – POST

헤더

Runtime.NoSuchHandler
Runtime.APIKeyNotFound
Runtime.ConfigInvalid
Runtime.BeforeSnapshotError (SnapStart용)
Runtime.UnknownReason

이 패턴과 일치하지 않는 값은 Runtime.Unknown 또는 Function.Unknown으로 정규화됩니다.

본문 매개변수

ErrorRequest – 오류에 대한 정보예요. 필수: 아니요.

이 필드는 다음 구조의 JSON 객체에요:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda는 errorType에 어떤 값도 수락한다는 점에 유의하세요.

다음 예제는 호출에서 제공된 이벤트 데이터를 함수가 파싱할 수 없을 때의 Lambda 함수 오류 메시지를 보여줘요.

예제 함수 오류

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}

응답 본문 매개변수

StatusResponse – String. 202 응답 코드와 함께 전송되는 상태 정보예요.
ErrorResponse – 오류 응답 코드와 함께 전송되는 추가 오류 정보예요. ErrorResponse는 오류 유형과 오류 메시지를 포함해요.

응답 코드

202 – 수락됨(Accepted)
403 – 금지(Forbidden)
500 – 컨테이너 오류. 복구 불가능한 상태. 런타임은 신속히 종료해야 해요.

예제 초기화 오류 요청

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"

호출 오류(Invocation error)

함수가 오류를 반환하거나 런타임이 오류를 만나면, 런타임은 이 메서드를 사용해 오류를 Lambda에 보고해요.

경로 – /runtime/invocation/{{AwsRequestId}}/error

메서드 – POST

헤더

Lambda-Runtime-Function-Error-Type – 런타임이 만난 오류 유형이에요. 필수: 아니요.

이 헤더는 문자열 값으로 구성돼요. Lambda는 어떤 문자열도 수락하지만 <category.reason> 형식을 권장해요. 예:

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 함수 오류 메시지를 보여줘요.

예제 함수 오류

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}

응답 본문 매개변수

StatusResponse – String. 202 응답 코드와 함께 전송되는 상태 정보예요.
ErrorResponse – 오류 응답 코드와 함께 전송되는 추가 오류 정보예요. ErrorResponse는 오류 유형과 오류 메시지를 포함해요.

응답 코드

202 – 수락됨(Accepted)
400 – 잘못된 요청(Bad Request)
403 – 금지(Forbidden)
500 – 컨테이너 오류. 복구 불가능한 상태. 런타임은 신속히 종료해야 해요.

예제 오류 요청

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"

복원 후(After-Restore, SnapStart에만 적용)

경로 – /runtime/restore/next

메서드 – GET

before-snapshot 훅이 완료된 후 런타임은 GET /runtime/restore/next를 호출해요. 이는 /runtime/invocation/next와 유사한 반복자(iterator) 스타일의 블로킹 호출로, 런타임이 실행 환경을 스냅샷할 준비가 되었음을 Lambda에 알려줘요. 이 요청은 Lambda가 스냅샷에서 실행 환경을 복원할 때까지 블록된 후, 빈 본문과 함께 HTTP 200 응답을 반환해요.

헤더

필요한 헤더가 없어요.

응답 코드

200 – Lambda가 실행 환경을 복원했어요. after-restore 훅을 실행하세요. 응답 본문은 비어 있어요.
403 – 금지. 런타임이 /restore/next를 허용하는 상태가 아니에요(예: 런타임이 이미 /invocation/next 또는 /restore/next를 호출했음).
404 – 이 함수에 SnapStart가 활성화되어 있지 않아요.
500 – 컨테이너 오류. 실행 환경이 복구 불가능한 상태예요. 런타임 프로세스를 종료하세요.

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

HTTP/1.1 200 OK
Content-Length: 0

참고
이(또는 다른 어떤) 런타임 API 요청에는 클라이언트 측 소켓 또는 읽기 타임아웃을 설정하지 마세요. 이는 반복자 스타일의 블로킹 호출이며, 요청이 열려 있는 동안 Lambda는 실행 환경을 고정(freeze)해요. 이 요청은 Lambda 서비스에서 연결이 유휴 상태로 간주되지 않으면서 스냅샷의 전체 수명(잠재적으로 며칠, 몇 주 또는 그 이상) 동안 열려 있을 수 있어요.

복원 오류(Restore error, SnapStart에만 적용)

after-restore 훅이 실패하거나 런타임이 복원 중 오류를 만나면, 런타임은 이 메서드를 사용해 오류를 Lambda에 보고해요. Lambda는 진행 중인 호출을 실패시키고 실행 환경을 내려요.

경로 – /runtime/restore/error

메서드 – POST

헤더

Lambda-Runtime-Function-Error-Type – 런타임이 만난 오류 유형이에요. 이 헤더는 선택 사항이에요. Lambda는 어떤 문자열 값도 수락하며, Category가 Runtime 또는 Function이고 Reason이 대문자로 시작하는 <Category.Reason> 형식을 권장해요(예: Runtime.AfterRestoreError). 이 패턴과 일치하지 않는 값은 Runtime.Unknown 또는 Function.Unknown으로 정규화됩니다.

응답 코드

202 – 수락됨. 응답 본문은 {"status":"OK"}예요. 런타임은 프로세스를 종료해야 해요.
403 – 금지. 런타임이 /restore/error를 허용하는 상태가 아니에요(예: /restore/next가 호출되지 않음).
404 – 이 함수에 SnapStart가 활성화되어 있지 않아요.
500 – 컨테이너 오류. 실행 환경이 복구 불가능한 상태예요. 런타임 프로세스를 종료하세요.

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}

더 알아보기 (Learn more)

커스텀 런타임이 호출 이벤트를 받고 응답·오류를 보내는 런타임 API 엔드포인트와, SnapStart의 복원 관련 호출까지 참고하세요.