Usar o Lambda com o Amazon MQ - AWS Lambda

Usar o Lambda com o Amazon MQ

O Amazon MQ é um serviço de agente de mensagens gerenciado para o Apache ActiveMQ e o RabbitMQ. O Lambda é compatível apenas com o Apache ActiveMQ. Um agente de mensagens permite que aplicativos de software e componentes se comuniquem usando várias linguagens de programação, sistemas operacionais e protocolos de mensagens formais por meio de destinos de eventos de tópico ou fila.

O Amazon MQ também pode gerenciar instâncias do Amazon Elastic Compute Cloud (Amazon EC2) em eu nome instalando agentes do ActiveMQ e fornecendo diferentes topologias de rede e outras necessidades de infraestrutura.

Você pode usar uma função do Lambda para processar registros de seu agente de mensagens do Amazon MQ. Sua função é acionada por meio de um mapeamento de fontes de eventos, um recurso do Lambda que lê mensagens do agente e invoa a função de maneira síncrona.

O mapeamento de fontes de eventos do Amazon MQ tem as seguintes restrições de configuração:

  • Autenticação – somente o SimpleAuthenticationPlugin do ActiveMQ é compatível. As credenciais do usuário associadas ao agente são o único método de conexão. Para obter mais informações sobre autenticação, consulte Autenticação e autorização de mensagens para ActiveMQ no Guia do desenvolvedor do Amazon MQ.

  • Cota de conexão – os agentes têm um número máximo de conexões permitidas por protocolo de nível de transmissão de dados. Essa cota é baseada no tipo de instância do agente. Para obter mais informações, consulte a seção Agentes de cotas no Amazon MQ do Guia do desenvolvedor do Amazon MQ.

  • Conectividade – você pode criar agentes em uma Virtual Private Cloud (VPC) pública ou privada. Para VPCs privadas, sua função do Lambda precisa acessar a VPC para interagir com os registros. Para obter mais informações, consulte API do mapeamento da fonte de eventos adiante neste tópico.

  • Destinos de eventos – somente destinos de fila são compatíveis. No entanto, você pode usar um tópico virtual, que se comporta como um tópico internamente enquanto interage com o Lambda como uma fila. Para obter mais informações, consulte Virtual Destinations no site do Apache ActiveMQ.

  • Topologia de rede – apenas um agente de instância única ou em espera é aceito por mapeamento de fonte de eventos. Os agentes de instância única requerem um endpoint de failover. Para obter mais informações sobre esses modos de implantação do agente, consulte Arquitetura do agente do Amazon MQ no Guia do desenvolvedor do Amazon MQ.

  • Protocolos – o Lambda consome mensagens usando o protocolo OpenWire/Java Message Service (JMS). Nenhum outro protocolo é compatível. Dentro do protocolo JMS, somente TextMessage e BytesMessage são compatíveis. Para obter mais informações sobre o protocolo OpenWire, consulte OpenWire no site do Apache ActiveMQ.

O Lambda oferece suporte automaticamente às versões mais recentes do ActiveMQ que não têm suporte no Amazon MQ. Para obter as versões compatíveis mais recentes, consulte as Notas de versão do Amazon MQ no Guia do desenvolvedor do Amazon MQ.

nota

Por padrão, o Amazon MQ tem uma janela de manutenção semanal para agentes. Durante essa janela de tempo, os agentes não estão disponíveis. Para agentes sem espera, o Lambda não é possível processar nenhuma mensagem durante essa janela.

Grupo de consumidores do Lambda

Para interagir com o Amazon MQ, o Lambda cria um grupo de consumidores que pode ler a partir de seus agentes do Amazon MQ. O grupo de consumidores é criado com o mesmo ID que um UUID de mapeamento da fonte de eventos.

O Lambda extrairá as mensagens até que ele tenha processado um máximo de 6 MB, até o tempo limite ou até que o tamanho do lote seja atendido. Quando configurado, o tamanho do lote determina o número máximo de itens a serem recuperados em um único lote. Seu lote é convertido em uma carga útil do Lambda e sua função de destino é invocada. As mensagens não são persistentes nem desserializadas. Em vez disso, eles são recuperados pelo grupo de consumidores como um BLOB de bytes e são codificados em base64 para uma carga útil JSON.

nota

O tempo máximo de invocação da função é de 14 minutos.

O Lambda processa todos os lotes recebidos simultaneamente e dimensiona a simultaneidade automaticamente para atender às demandas. Você pode monitorar o uso da simultaneidade de uma determinada função usando a métrica ConcurrentExecutions no Amazon CloudWatch. Para obter mais informações sobre a simultaneidade, consulte Gerenciar a simultaneidade para uma função do Lambda.

exemplo Evento de registro do Amazon MQ

{ "eventSource": "aws:amq", "eventSourceArn": "arn:aws:mq:us-west-2:112556298976:broker:test:b-9bcfa592-423a-4942-879d-eb284b418fc8", "messages": { [ { "messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1.mq.us-west-2.amazonaws.com-37557-1234520418293-4:1:1:1:1", "messageType": "jms/text-message", "data": "QUJDOkFBQUE=", "connectionId": "myJMSCoID", "redelivered": false, "destination": { "physicalname": "testQueue" }, "timestamp": 1598827811958, "brokerInTime": 1598827811958, "brokerOutTime": 1598827811959 }, { "messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1.mq.us-west-2.amazonaws.com-37557-1234520418293-4:1:1:1:1", "messageType":"jms/bytes-message", "data": "3DTOOW7crj51prgVLQaGQ82S48k=", "connectionId": "myJMSCoID1", "persistent": false, "destination": { "physicalname": "testQueue" }, "timestamp": 1598827811958, "brokerInTime": 1598827811958, "brokerOutTime": 1598827811959 } ] } }

Permissões da função de execução

Para ler registros de um agente do Amazon MQ, sua função do Lambda precisa das seguintes permissões adicionadas à função de execução dela:

nota

Ao usar uma chave criptografada gerenciada pelo cliente, adicione a permissão kms:Decrypt também.

Configurar um agente como uma fonte de eventos

Crie um mapeamento de fontes de eventos para instruir o Lambda a enviar registros de um agente do Amazon MQ para uma função do Lambda. É possível criar vários mapeamentos de origem de evento para processar os mesmos dados com várias funções ou processar itens de várias fontes com uma única função.

Para configurar sua função para ler do Amazon MQ, crie um trigger do MQ no console do Lambda.

Para criar um gatilho

  1. Abra a página Funções do console do Lambda.

  2. Escolha uma função.

  3. Em Function overview (Visão geral da função), escolha Add trigger (Adicionar gatilho).

  4. Escolha um tipo de gatinho.

  5. Configure as opções necessárias e, em seguida, escolha Add (Adicionar).

O Lambda oferece suporte às seguintes opções para as fontes de eventos do Amazon MQ:

  • MQ broker (Agente do MQ) – selecione um agente do Amazon MQ.

  • Batch size (Tamanho do lote) – defina o número máximo de mensagens a serem recuperadas em um único lote.

  • Queue name (Nome da fila) – digite a fila do Amazon MQ a ser consumida.

  • Source access configuration (Configuração de acesso à origem) – selecione o segredo do AWS Secrets Manager que armazena as credenciais do agente.

  • Enable trigger (Habilitar gatilho) – desabilite o trigger para interromper o processamento de registros.

Para habilitar ou desabilitar o trigger (ou excluí-lo), selecione o trigger do MQ no designer. Para reconfigurar o trigger, use as operações da API de mapeamento de fontes de eventos.

API do mapeamento da fonte de eventos

Para gerenciar uma origem de evento com a AWS CLI ou o AWS SDK, é possível usar as seguintes operações de API:

Para criar o mapeamento da fonte de eventos com a AWS Command Line Interface (AWS CLI), use o comando create-event-source-mapping.

Por padrão, os agentes do Amazon MQ são criados com o a sinalização PubliclyAccessible definida como falsa. O agente recebe um endereço IP público somente quando PubliclyAccessible é definido como verdadeiro.

Para ter acesso total ao mapeamento de fontes de eventos, seu agente deve usar um endpoint público ou fornecer acesso à VPC. Para atender aos requisitos de acesso da Amazon VPC, é possível executar um dos seguintes procedimentos:

As regras de grupos de segurança da Amazon Virtual Private Cloud (Amazon VPC) que você configurar deverão ter as seguintes configurações, no mínimo:

  • Regras de entrada – para um agente sem acessibilidade pública, permita todo o tráfego em todas as portas para o grupo de segurança especificado como sua fonte. Para um corretor com acessibilidade pública, permita todo o tráfego em todas as portas para todos os destinos.

  • Regras de saída – Permitir todo o tráfego em todas as portas para todos os destinos.

A configuração da Amazon VPC é detectável pela API do Amazon MQ e não precisa ser configurada nas definições de create-event-source-mapping.

O exemplo de comando da AWS CLI a seguir cria uma fonte de eventos que mapeia uma função do Lambda chamada MQ-Example-Function para um agente do Amazon MQ chamado ExampleMQBroker. O comando também fornece um segredo do Secrets Manager chamado ExampleMQBrokerUserPassword que armazena as credenciais do agente.

aws lambda create-event-source-mapping \ --event-source-arn arn:aws:mq:us-east-1:12345678901:broker:ExampleMQBroker:b-b4d492ef-bdc3-45e3-a781-cd1a3102ecca \ --function-name MQ-Example-Function \ --source-access-configuration Type=BASIC_AUTH,URI=arn:aws:secretsmanager:us-east-1:12345678901:secret:ExampleMQBrokerUserPassword-xPBMTt \ --queues ExampleQueue

Você deve ver a saída a seguir:

{ "UUID": "91eaeb7e-c976-1234-9451-8709db01f137", "BatchSize": 100, "EventSourceArn": "arn:aws:mq:us-east-1:12345678901:broker:ExampleMQBroker:b-b4d492ef-bdc3-45e3-a781-cd1a3102ecca", "FunctionArn": "arn:aws:lambda:us-east-1:12345678901:function:MQ-Example-Function", "LastModified": 1601927898.741, "LastProcessingResult": "No records processed", "State": "Creating", "StateTransitionReason": "USER_INITIATED", "Queues": [ "ExampleQueue" ], "SourceAccessConfigurations": [ { "Type": "BASIC_AUTH", "URI": "arn:aws:secretsmanager:us-east-1:12345678901:secret:ExampleMQBrokerUserPassword-xPBMTt" } ] }

Usando o comando update-event-source-mapping, você pode configurar opções adicionais, por exemplo, como os lotes são processados, e especificar quando descartar registros que não podem ser processados. O exemplo de comando a seguir atualiza um mapeamento de fonte de eventos para ter um tamanho de lote igual a 2.

aws lambda update-event-source-mapping \ --uuid 91eaeb7e-c976-1234-9451-8709db01f137 \ --batch-size 2

Você deve ver a saída a seguir:

{ "UUID": "91eaeb7e-c976-1234-9451-8709db01f137", "BatchSize": 2, "EventSourceArn": "arn:aws:mq:us-east-1:12345678901:broker:ExampleMQBroker:b-b4d492ef-bdc3-45e3-a781-cd1a3102ecca", "FunctionArn": "arn:aws:lambda:us-east-1:12345678901:function:MQ-Example-Function", "LastModified": 1601928393.531, "LastProcessingResult": "No records processed", "State": "Updating", "StateTransitionReason": "USER_INITIATED" }

As configurações atualizadas são aplicadas de forma assíncrona e não são refletidas na saída até que o processo seja concluído. Use o comando get-event-source-mapping para visualizar o status atual do seu recurso.

aws lambda get-event-source-mapping \ --uuid 91eaeb7e-c976-4939-9451-8709db01f137

Você deve ver a saída a seguir:

{ "UUID": "91eaeb7e-c976-4939-9451-8709db01f137", "BatchSize": 2, "EventSourceArn": "arn:aws:mq:us-east-1:12345678901:broker:ExampleMQBroker:b-b4d492ef-bdc3-45e3-a781-cd1a3102ecca", "FunctionArn": "arn:aws:lambda:us-east-1:12345678901:function:MQ-Example-Function", "LastModified": 1601928393.531, "LastProcessingResult": "No records processed", "State": "Enabled", "StateTransitionReason": "USER_INITIATED" }

Erros de mapeamento da fonte de eventos

Quando uma função do Lambda encontra um erro irrecuperável, o consumidor do Amazon MQ interrompe o processamento de registros. Qualquer outro consumidor pode continuar o processamento, contanto que não encontre o mesmo erro. Para determinar a possível causa de um consumidor interrompido, verifique o campo StateTransitionReason nos detalhes de devolução do EventSourceMapping para obter um dos seguintes códigos:

ESM_CONFIG_NOT_VALID

A configuração do mapeamento da fonte de eventos não é válida.

EVENT_SOURCE_AUTHN_ERROR

O Lambda falhou ao autenticar a fonte de eventos.

EVENT_SOURCE_AUTHZ_ERROR

O Lambda não tem as permissões necessárias para acessar a fonte de eventos.

FUNCTION_CONFIG_NOT_VALID

A configuração da função não é válida.

Os registros também não serão processados se forem descartados devido ao seu tamanho. O limite de tamanho para registros do Lambda é de 6 MB. Para entregar mensagens novamente após um erro da função, use uma política de reeentrega e o processamento de Dead Letter Queue (DLQ – Fila de mensagens mortas) com o Amazon MQ. Para obter mais informações, consulte Message Redelivery and DLQ Handling no site do Apache ActiveMQ.