# Usar a API de runtime do Lambda para runtimes personalizados
<a name="runtimes-api"></a>

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

**As instâncias gerenciadas do Lambda oferecem suporte a solicitações simultâneas**  
As instâncias gerenciadas do Lambda usam a mesma API de runtime das funções do Lambda (padrão). A principal diferença é que as instâncias gerenciadas podem aceitar solicitações simultâneas `/next` e `/response` até o limite configurado `AWS_LAMBDA_MAX_CONCURRENCY`. Isso permite que várias invocações sejam processadas simultaneamente em um único ambiente de execução. Para obter mais informações sobre instâncias gerenciadas, consulte [Noções básicas sobre o ambiente de execução das instâncias gerenciadas do Lambda](lambda-managed-instances-execution-environment.md).

![\[Diagrama de arquitetura do ambiente de execução.\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/telemetry-api-concept-diagram.png)


A especificação OpenAPI para a versão da API de runtime **2018-06-01** está disponível aqui: [runtime-api.zip](samples/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.

**Example Solicitação**  

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

**Topics**
+ [Próxima invocação](#runtimes-api-next)
+ [Resposta de invocação](#runtimes-api-response)
+ [Erro de inicialização](#runtimes-api-initerror)
+ [Erro de invocação](#runtimes-api-invokeerror)

## Próxima invocação
<a name="runtimes-api-next"></a>

**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](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader). 

  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
<a name="runtimes-api-response"></a>

**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.

**Example 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
<a name="runtimes-api-initerror"></a>

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.

**Example 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.

**Example 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
<a name="runtimes-api-invokeerror"></a>

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.

**Example 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.

**Example 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"
```