Usar a API de runtime do Lambda para runtimes personalizados - AWS Lambda
Próxima invocaçãoResposta de invocaçãoErro de inicializaçãoErro de invocação

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.

Diagrama de arquitetura do ambiente de execução.

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.

exemplo Solicitação
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.

Cabeçalhos de resposta

  • Lambda-Runtime-Aws-Request-Id: o ID da solicitação, que identifica a solicitação que acionou a invocação da função.

    Por exemplo, 8476a536-e9f4-11e8-9739-2dfe598c3fcd.

  • Lambda-Runtime-Deadline-Ms: a data em que a função expira tempo em milissegundos do Unix.

    Por exemplo, 1542409706888.

  • Lambda-Runtime-Invoked-Function-Arn: o ARN da função do Lambda, versão ou alias especificado na invocação.

    Por exemplo, arn:aws:lambda:us-east-2:123456789012:function:custom-runtime.

  • Lambda-Runtime-Trace-Id: o cabeçalho de rastreamento do AWS X-Ray.

    Por exemplo, Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.

  • Lambda-Runtime-Client-Context: para invocações do AWS Mobile SDK, os dados sobre a aplicação cliente e o dispositivo.

  • Lambda-Runtime-Cognito-Identity: para invocações do AWS Mobile SDK, os dados sobre o provedor de identidade do Amazon Cognito.

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.

O ID da solicitação rastreia a invocação dentro do Lambda. Use-o para especificar a invocação ao enviar a resposta.

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.

exemplo solicitação com êxito
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS"

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 tempo de execução. 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:

  • Runtime.NoSuchHandler

  • Runtime.APIKeyNotFound

  • Runtime.ConfigInvalid

  • Runtime.UnknownReason

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.

exemplo Erro de função
{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}
Parâmetros do corpo da resposta

  • StatusResponse – String. Informações de status, enviadas com 202 códigos de resposta.

  • ErrorResponse: informações adicionais de erro, enviadas com os códigos de resposta de erro. O ErrorResponse contém um tipo de erro e uma mensagem de erro.

Códigos de resposta

  • 202: aceito

  • 403: proibido

  • 500: erro de contêiner. Estado não recuperável. O tempo de execução deve sair imediatamente.

exemplo solicitação com erro de inicialização
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 tempo de execução. 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:

  • Runtime.NoSuchHandler

  • Runtime.APIKeyNotFound

  • Runtime.ConfigInvalid

  • Runtime.UnknownReason

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.

exemplo Erro de função
{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}
Parâmetros do corpo da resposta

  • StatusResponse – String. Informações de status, enviadas com 202 códigos de resposta.

  • ErrorResponse: informações adicionais de erro, enviadas com os códigos de resposta de erro. O ErrorResponse contém um tipo de erro e uma mensagem de erro.

Códigos de resposta

  • 202: aceito

  • 400: solicitação inválida

  • 403: proibido

  • 500: erro de contêiner. Estado não recuperável. O tempo de execução deve sair imediatamente.

exemplo solicitação com erro
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"