Invocação de funções do Lambda duráveis

As funções do Lambda duráveis oferecem suporte aos mesmos métodos de invocação das funções do Lambda padrão. É possível invocar funções duráveis de forma síncrona, assíncrona ou por meio de mapeamentos da origem do evento. O processo de invocação é idêntico às funções padrão, mas as funções duráveis fornecem recursos adicionais para execuções de longa duração e gerenciamento automático de estados.

Métodos de invocação

Invocação síncrona: invoque uma função durável e aguarde a resposta. As invocações síncronas são limitadas pelo Lambda a 15 minutos (ou menos, dependendo da função configurada e do tempo limite de execução). Use a invocação síncrona quando precisar de resultados imediatos ou ao fazer a integração com APIs e serviços que esperem uma resposta. É possível usar operações de espera para uma computação eficiente sem interromper o chamador. A invocação aguarda a conclusão de toda a execução durável. Para iniciar a execução com idempotência, use o parâmetro do nome da execução conforme descrito em Idempotência.

aws lambda invoke \
  --function-name my-durable-function:1 \
  --cli-binary-format raw-in-base64-out \
  --payload '{"orderId": "12345"}' \
  response.json
    

Invocação assíncrona: coloque um evento na fila para processamento sem esperar por uma resposta. O Lambda coloca o evento em uma fila e retorna imediatamente. Invocações assíncronas oferecem suporte a durações de execução de até um ano. Use a invocação assíncrona para cenários fire-and-forget ou quando o processamento puder ocorrer em segundo plano. Para iniciar a execução com idempotência, use o parâmetro do nome da execução conforme descrito em Idempotência.

aws lambda invoke \
  --function-name my-durable-function:1 \
  --invocation-type Event \
  --cli-binary-format raw-in-base64-out \
  --payload '{"orderId": "12345"}' \
  response.json
    

Mapeamentos da origem do evento: configure o Lambda para invocar automaticamente sua função durável quando os registros estiverem disponíveis em serviços baseados em streaming ou em filas, como o Amazon SQS, o Kinesis ou o DynamoDB. Os mapeamentos da origem do evento sondam a origem do evento e invocam sua função com lotes de registros. Para obter detalhes sobre o uso de mapeamentos da origem do evento com funções duráveis, incluindo limites de duração de execução, consulte Mapeamentos da origem do evento com funções duráveis.

Para obter detalhes completos sobre cada método de invocação, consulte invocação síncrona e invocação assíncrona.

nota

As funções duráveis oferecem suporte a filas de mensagens não entregues (DLQs) para tratamento de erros, mas não oferecem suporte a destinos do Lambda. Configure uma DLQ para capturar registros de invocações com falhas.

Requisito de ARNs qualificados

As funções duráveis exigem identificadores qualificados para invocação. É necessário invocar funções duráveis usando um número de versão, alias ou $LATEST. É possível usar um ARN totalmente qualificado ou um nome de função com sufixo de versão/alias. Não é possível usar um identificador não qualificado (sem uma versão ou sufixo de alias).

Invocações válidas:

# Using full ARN with version number
arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:1

# Using full ARN with alias
arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:prod

# Using full ARN with $LATEST
arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:$LATEST

# Using function name with version number
my-durable-function:1

# Using function name with alias
my-durable-function:prod
    

Invocações inválidas:

# Unqualified ARN (not allowed)
arn:aws:lambda:us-east-1:123456789012:function:my-durable-function

# Unqualified function name (not allowed)
my-durable-function
    

Esse requisito garante que as execuções duráveis permaneçam consistentes durante todo o seu ciclo de vida. Quando uma execução durável é iniciada, ela é fixada na versão específica da função. Se sua função for pausada e retomada horas ou dias depois, o Lambda invocará a mesma versão que iniciou a execução, garantindo a consistência do código em todo o fluxo de trabalho.

Melhor prática

Use aliases ou versões numeradas para funções duráveis de produção, em vez de $LATEST. As versões numeradas são imutáveis e garantem uma reprodução determinística. Opcionalmente, os aliases fornecem uma referência estável que pode ser atualizada para apontar para novas versões sem alterar o código de invocação. Quando você atualiza um alias, as novas execuções usam a nova versão, enquanto as execuções em andamento continuam com a versão original. É possível usar $LATEST para prototipagem ou para reduzir os tempos de implantação durante o desenvolvimento, entendendo que as execuções podem não ser reproduzidas corretamente (ou até mesmo falhar) se o código subjacente mudar durante o andamento das execuções.

Noções básicas sobre o ciclo de vida da execução

Quando você invoca uma função durável, o Lambda cria uma execução durável que pode abranger várias invocações de funções:

1. Invocação inicial: sua solicitação de invocação cria uma nova execução durável. O Lambda atribui um ID de execução exclusivo e inicia o processamento.

2. Execução e criação de pontos de verificação: à medida que sua função executa operações duráveis, o SDK cria pontos de verificação que monitoram o andamento.

3. Suspensão (se necessário): se sua função usa esperas duráveis, como wait ou waitForCallback, ou novas tentativas automáticas de etapas, o Lambda suspende a execução e interrompe a cobrança pelo tempo de computação.

4. Retomada: na hora de prosseguir (inclusive após novas tentativas), o Lambda invoca sua função novamente. O SDK reproduz o log do ponto de verificação e continua de onde a execução foi pausada.

5. Conclusão: quando sua função retorna um resultado final ou gera um erro não tratado, a execução durável é concluída.

Para invocações síncronas, o chamador espera que toda a execução durável seja concluída, incluindo qualquer operação de espera. Se a execução exceder o tempo limite de invocação (15 minutos ou menos), a invocação expirará. Para invocações assíncronas, o Lambda retorna imediatamente e a execução continua de forma independente. Use as APIs de execução durável para monitorar o status da execução e recuperar os resultados finais.

Invocação a partir do código da aplicação

Use os SDKs da AWS para invocar funções duráveis a partir do código da sua aplicação. O processo de invocação é idêntico às funções padrão:

TypeScript

import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';

const client = new LambdaClient({});

// Synchronous invocation
const response = await client.send(new InvokeCommand({
  FunctionName: 'arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:1',
  Payload: JSON.stringify({ orderId: '12345' })
}));

const result = JSON.parse(Buffer.from(response.Payload!).toString());

// Asynchronous invocation
await client.send(new InvokeCommand({
  FunctionName: 'arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:1',
  InvocationType: 'Event',
  Payload: JSON.stringify({ orderId: '12345' })
}));
          

Python

import boto3
import json

client = boto3.client('lambda')

# Synchronous invocation
response = client.invoke(
    FunctionName='arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:1',
    Payload=json.dumps({'orderId': '12345'})
)

result = json.loads(response['Payload'].read())

# Asynchronous invocation
client.invoke(
    FunctionName='arn:aws:lambda:us-east-1:123456789012:function:my-durable-function:1',
    InvocationType='Event',
    Payload=json.dumps({'orderId': '12345'})
)
          

Invocações encadeadas

Funções duráveis podem invocar outras funções duráveis e não duráveis usando a operação invoke do DurableContext. Isso cria uma invocação em cadeia em que a função de chamada espera (é suspendida) até que a função invocada seja concluída:

TypeScript

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    // Invoke another durable function and wait for result
    const result = await context.invoke(
      'process-order',
      'arn:aws:lambda:us-east-1:123456789012:function:order-processor:1',
      { orderId: event.orderId }
    );
    
    return { statusCode: 200, body: JSON.stringify(result) };
  }
);
          

Python

@durable_execution
def handler(event, context: DurableContext):
    # Invoke another durable function and wait for result
    result = context.invoke(
        'arn:aws:lambda:us-east-1:123456789012:function:order-processor:1',
        {'orderId': event['orderId']},
        name='process-order'
    )
    
    return {'statusCode': 200, 'body': json.dumps(result)}
          

Invocações encadeadas criam um ponto de verificação na função de chamada. Se a função de chamada for interrompida, ela será retomada a partir do ponto de verificação com o resultado da função invocada sem invocar novamente a função.

nota

Não há suporte para invocações encadeadas entre contas. A função invocada deve estar na mesma conta da AWS da função de chamada.