사용자 지정 런타임을 위한 Lambda 런타임 API 사용

AWS Lambda은 사용자 지정 런타임에 HTTP API를 제공하여 Lambda에서 호출 이벤트를 수신하고 Lambda 실행 환경 내에서 응답 데이터를 다시 전송합니다. 이 섹션에서는 Lambda 런타임 API에 대한 API 참조에 대해 알아봅니다.

런타임 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"

다음 호출

경로 – /runtime/invocation/next

매서드 – GET

런타임에서는 호출 이벤트를 요청하기 위해 이 메시지를 Lambda로 보냅니다. 응답 본문에는 호출의 페이로드가 포함되어 있습니다. 이 페이로드는 함수 트리거의 이벤트 데이터를 포함하는 JSON 문서입니다. 응답 헤더에는 호출에 대한 추가 데이터가 포함되어 있습니다.

응답이 지연될 수 있으므로 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를 가져온 다음, 요청을 추적할지 여부를 결정합니다.

호출 응답

경로 – /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"

초기화 오류

함수가 오류를 반환하거나 런타임에서 초기화 중에 오류가 발생하면 런타임에서는 이 메서드를 사용하여 Lambda에 오류를 보고합니다.

경로 – /runtime/init/error

메서드 – POST

헤더

Lambda-Runtime-Function-Error-Type – 런타임에서 발생한 오류 유형입니다. 이 헤더는 선택 사항입니다. Lambda는 모든 문자열 값을 허용합니다. Category가 Runtime 또는 Function이고 Reason이 대문자로 시작하는 <Category.Reason> 형식을 사용하는 것이 좋습니다. 예제:

이 패턴과 일치하지 않는 값은 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": [ ]
}      

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는 모든 문자열을 허용하지만 <category.reason> 형식을 사용하는 것이 좋습니다. 예제:

Lambda-Runtime-Invocation-Id – /next에서 수신한 값을 다시 에코합니다. Lambda는 값이 활성 호출과 일치하지 않는 경우 400 InvalidInvocationId를 사용해 요청을 거부합니다.

본문 파라미터

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": [ ]
}      

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"

복원 후(SnapStart에만 해당)

경로 – /runtime/restore/next

매서드 – GET

스냅샷 이전 후크가 완료되고 나면 런타임이 GET /runtime/restore/next를 호출합니다. 이것은 /runtime/invocation/next와 비슷한 반복자 스타일의 차단 호출로, Lambda에 런타임이 실행 환경을 스냅샷할 준비가 되었다고 신호합니다. 이 요청은 Lambda가 스냅샷으로부터 실행 환경을 복원할 때까지 차단되고, 본문이 비어 있는 HTTP 200 응답을 반환합니다.

헤더

헤더가 필요하지 않습니다.

요청 구문

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

응답 구문

HTTP/1.1 200 OK
Content-Length: 0

복원 오류(SnapStart에만 해당)

복원 후 후크가 실패하거나 런타임에서 복원 중에 오류가 발생하면, 런타임이 이 메서드를 사용해 오류를 Lambda에 보고합니다. Lambda는 진행 중인 호출을 실패 처리하고 실행 환경을 해체합니다.

경로 – /runtime/restore/error

메서드 – POST

헤더

Lambda-Runtime-Function-Error-Type – 런타임에서 발생한 오류 유형입니다. 이 헤더는 선택 사항입니다. Lambda는 모든 문자열 값을 허용합니다. Category가 Runtime 또는 Function이고 Reason이 대문자로 시작하는 <Category.Reason> 형식을 사용하는 것이 좋습니다(예: Runtime.AfterRestoreError). 이 패턴과 일치하지 않는 값은 Runtime.Unknown 또는 Function.Unknown으로 정규화됩니다.

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"}