Usar a API de runtime do Lambda para runtimes personalizados

O AWS Lambda fornece uma API HTTP para runtimes personalizados para receber eventos de invocação do Lambda e enviar dados de resposta de volta para o ambiente de execução do Lambda. Esta seção contém a referência de API para a API do runtime do Lambda.

A especificação OpenAPI para a versão da API de runtime 2018-06-01 está disponível aqui: runtime-api.zip

Para criar um URL de solicitação de API, os runtimes obtêm o endpoint da API da variável de ambiente do AWS_LAMBDA_RUNTIME_API, adiciona a versão da API e o caminho de recurso desejado.

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

Próxima invocação

Caminho – /runtime/invocation/next

Método – GET

O runtime envia essa mensagem ao Lambda para solicitar um evento de invocação. O corpo da resposta contém a carga útil da invocação, que é um documento JSON que contém os dados do evento do acionador da função. Os cabeçalhos de resposta contêm dados adicionais sobre a invocação.

Não defina um tempo limite na solicitação GET, pois a resposta poderá estar atrasada. Entre o momento em que o Lambda inicializa o runtime e o momento em que o runtime tem um evento para retornar, o processo do runtime pode ficar congelado por vários segundos.

Um ID de solicitação (Lambda-Runtime-Aws-Request-Id) identifica um evento exclusivo. Os IDs de solicitação são fornecidos por fontes de eventos ou gerados automaticamente pelo Lambda na ingestão. Use o ID da solicitação no caminho do URL ao enviar a resposta ou o erro.

Um ID de invocação (Lambda-Runtime-Invocation-Id) representa uma única tentativa de invocação para um evento. Um único ID de solicitação pode resultar em várias tentativas de invocação, cada uma com seu próprio ID de invocação exclusivo. O Lambda usa cada ID de invocação exatamente uma vez e nunca o reutiliza. Repasse esse valor nas chamadas /response e /error. O cabeçalho é opcional para compatibilidade com os runtimes atuais em relação às versões anteriores. Omiti-lo não aciona uma rejeição. O Lambda só rejeita com 400 InvalidInvocationId quando há o cabeçalho, mas o valor não corresponde à invocação ativa.

O cabeçalho de rastreamento contém o ID de rastreamento, o ID pai e a decisão de amostragem. Se a solicitação for de amostra, a amostra da solicitação foi feita pelo Lambda ou um serviço upstream. O runtime deve definir o _X_AMZN_TRACE_ID com o valor do cabeçalho. O X-Ray SDK lê isso para obter os IDs e determinar se deve rastrear a solicitação.

Resposta de invocação

Caminho – /runtime/invocation/AwsRequestId/response

Método – POST

Depois que a função for executada até a conclusão, o runtime envia uma resposta de invocação para o Lambda. Para invocações síncronas, o Lambda envia a resposta de volta para o cliente.

Cabeçalhos de solicitação

Lambda-Runtime-Invocation-Id: repasse o valor recebido de /next. O Lambda rejeita a solicitação com 400 InvalidInvocationId se o valor não corresponder à invocação ativa.

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"

Erro de inicialização

Se a função retornar um erro ou o runtime encontrar um erro durante a inicialização, o runtime usará esse método para relatar o erro ao Lambda.

Caminho – /runtime/init/error

Método – POST

Cabeçalhos

Lambda-Runtime-Function-Error-Type: o tipo de erro encontrado pelo runtime. Esse cabeçalho é opcional. O Lambda aceita qualquer valor de string; recomendamos usar o formato <Category.Reason>, em que a Categoria é Runtime ou Function e o Motivo começa com uma letra maiúscula. Por exemplo:

Os valores que não correspondem a esse padrão são normalizados como Runtime.Unknown ou Function.Unknown.

Body parameters (Parâmetros do corpo

ErrorRequest: informações adicionais sobre o erro. Obrigatório: não

Este campo é um objeto JSON com a seguinte estrutura:

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

Observe que o Lambda aceita qualquer valor para errorType.

O exemplo a seguir mostra uma mensagem de erro de função do Lambda na qual a função não pôde analisar os dados do evento fornecidos na chamada.

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

Erro de invocação

Se a função retornar um erro ou o runtime encontrar um erro, o runtime usará esse método para relatar o erro ao Lambda.

Caminho – /runtime/invocation/AwsRequestId/error

Método – POST

Cabeçalhos

Lambda-Runtime-Function-Error-Type: o tipo de erro encontrado pelo runtime. Obrigatório: não

Este cabeçalho consiste em um valor de string. Lambda aceita qualquer string, mas recomendamos o formato <category.reason>. Por exemplo:

Lambda-Runtime-Invocation-Id: repasse o valor recebido de /next. O Lambda rejeita a solicitação com 400 InvalidInvocationId se o valor não corresponder à invocação ativa.

Body parameters (Parâmetros do corpo

ErrorRequest: informações adicionais sobre o erro. Obrigatório: não

Este campo é um objeto JSON com a seguinte estrutura:

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

Observe que o Lambda aceita qualquer valor para errorType.

O exemplo a seguir mostra uma mensagem de erro de função do Lambda na qual a função não pôde analisar os dados do evento fornecidos na chamada.

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

Após a restauração (aplicável somente ao SnapStart)

Caminho – /runtime/restore/next

Método – GET

Depois que os hooks do pré-snapshot são concluídos, o runtime chama GET /runtime/restore/next. Essa é uma chamada de bloqueio no estilo iterador, semelhante a /runtime/invocation/next, que sinaliza ao Lambda que o runtime está pronto para que o ambiente de execução seja capturado. A solicitação bloqueia até que o Lambda restaure o ambiente de execução a partir de um snapshot e, em seguida, retorne uma resposta HTTP 200 com um corpo vazio.

Cabeçalhos

Nenhum cabeçalho é necessário.

Sintaxe da solicitação

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

Sintaxe da resposta

HTTP/1.1 200 OK
Content-Length: 0

Erro de restauração (aplicável somente ao SnapStart)

Se um hook após a restauração falhar ou o runtime encontrar um erro durante a restauração, o runtime usará esse método para relatar o erro ao Lambda. O Lambda falha na invocação em andamento e destrói o ambiente de execução.

Caminho – /runtime/restore/error

Método – POST

Cabeçalhos

Lambda-Runtime-Function-Error-Type: o tipo de erro encontrado pelo runtime. Esse cabeçalho é opcional. O Lambda aceita qualquer valor de string; recomendamos usar o formato <Category.Reason>, em que a Categoria é Runtime ou Function e o Motivo começa com uma letra maiúscula (por exemplo, Runtime.AfterRestoreError). Os valores que não correspondem a esse padrão são normalizados como Runtime.Unknown ou 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"}