Encaminhe Eventos de Pedidos com EventBridge

Introdução

O atendimento de pedidos precisa dos pedidos recém-feitos, enquanto eventos de cobrança e cancelamento devem ir para outros destinos. Você encaminhará eventos correspondentes para uma fila e verificará quais mensagens realmente chegam.

O EventBridge seleciona eventos recebidos e os encaminha ao SQS, uma fila que armazena mensagens. O acesso pela CLI já está configurado; não é necessário ter conta pessoal da AWS nem chaves de acesso.

Conclua primeiro Envie e Consuma Tarefas com SQS e Proteja um bucket com uma política de recurso. Esta VM independente fornece seu próprio acesso à CLI e dados de referência; filas e credenciais anteriores não são reutilizadas.

Relação com as certificações

Visão geral do laboratório

Prepare um Barramento e uma Fila de Destino

Nesta etapa, crie os locais independentes onde os eventos entram e o trabalho correspondente aguarda um consumidor.

Use AWS View na parte superior para comparar as consultas da CLI com os recursos e resultados reais deste laboratório. Preserve os dados de referência fornecidos.

O Amazon EventBridge encaminha eventos que descrevem coisas que aconteceram. Um barramento recebe eventos, uma regra identifica correspondências nos campos e um destino recebe eventos correspondentes. Um barramento personalizado separa os eventos desta aplicação do barramento padrão. Uma fila SQS mantém as entregas até que um consumidor as processe. Comece no diretório do projeto. Atribuições no shell salvam os identificadores retornados pela CLI; --query seleciona o campo necessário e --output text o torna utilizável pelo próximo comando.

cd /home/labex/project
BUS_NAME=labex-ev01-bus

Defina RULE_NAME para as operações seguintes:

RULE_NAME=labex-ev01-orders

Crie o barramento de eventos do exercício:

aws events create-event-bus --name "$BUS_NAME"

Salve o valor retornado em QUEUE_URL:

QUEUE_URL=$(aws sqs create-queue \
  --queue-name labex-ev01-jobs \
  --query QueueUrl \
  --output text)
echo "$QUEUE_URL"

Salve o valor retornado em QUEUE_ARN:

QUEUE_ARN=$(aws sqs get-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attribute-names QueueArn \
  --query Attributes.QueueArn \
  --output text)
echo "$QUEUE_ARN"

A resposta do barramento contém seu ARN, e QUEUE_URL identifica a fila para operações de mensagens. O ARN da fila a identifica em um destino ou em uma política de permissão. Esses identificadores têm finalidades diferentes.

Inspecione os dois recursos vazios:

aws events list-rules --event-bus-name "$BUS_NAME"

Confira os atributos da fila $QUEUE_URL:

aws sqs get-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible

Ainda não há regras, e a fila não tem mensagens disponíveis ou em processamento. AWS View mostra seu barramento personalizado e a fila vazia. Execute a verificação da preparação.

Identifique Pedidos Correspondentes e Autorize uma Regra

Nesta etapa, conecte uma regra de correspondência à fila e autorize apenas as entregas dessa regra.

Um padrão de eventos é um filtro sobre os campos dos eventos. source nomeia o produtor, enquanto detail-type nomeia a categoria do evento. Cada array abaixo lista os valores aceitos. Um here-document grava o JSON literal entre os marcadores JSON; colocar o marcador entre aspas impede a expansão pelo shell. file:// instrui a CLI a ler esse arquivo.

Os dois campos do padrão precisam corresponder: o produtor de pedidos sozinho não seleciona um cancelamento, e o tipo OrderPlaced sozinho não seleciona um evento de cobrança. O source do evento é um dado de roteamento; aws:SourceArn na política da fila identifica a regra autorizada a entregá-lo.

cat > order-pattern.json <<'JSON'
{"source":["labex.orders"],"detail-type":["OrderPlaced"]}
JSON

Salve o valor retornado em RULE_ARN:

RULE_ARN=$(aws events put-rule \
  --name "$RULE_NAME" \
  --event-bus-name "$BUS_NAME" \
  --event-pattern file://order-pattern.json \
  --state ENABLED \
  --query RuleArn \
  --output text)
echo "$RULE_ARN"

A regra está habilitada, mas uma correspondência, por si só, não autoriza a entrega. A política de recurso da fila deve permitir que o serviço EventBridge envie mensagens, com aws:SourceArn restrito a esta regra. Escreva uma política JSON comum; o shell insere os ARNs de sua fila e regra.

cat > queue-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Action": "sqs:SendMessage",
      "Resource": "$QUEUE_ARN",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "$RULE_ARN"
        }
      }
    }
  ]
}
EOF

Escreva a configuração em queue-attributes.json:

jq -n --rawfile policy queue-policy.json '{Policy:$policy}' > queue-attributes.json

Aplique os atributos à fila $QUEUE_URL:

aws sqs set-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attributes file://queue-attributes.json

A API de atributos armazena a política como uma string JSON, portanto --rawfile lê esse documento no atributo Policy. A permissão abrange uma fila e uma regra de origem.

Um destino é para onde a regra envia os eventos. Seu ID permite atualizar ou remover essa conexão depois:

cat > targets.json <<EOF
[
  {
    "Id": "order-queue",
    "Arn": "$QUEUE_ARN"
  }
]
EOF

Aplique os destinos de entrega da regra de eventos:

aws events put-targets \
  --rule "$RULE_NAME" \
  --event-bus-name "$BUS_NAME" \
  --targets file://targets.json

Confira o padrão de seleção da regra de eventos:

aws events describe-rule --name "$RULE_NAME" --event-bus-name "$BUS_NAME"

Confira os destinos de entrega da regra de eventos:

aws events list-targets-by-rule --rule "$RULE_NAME" --event-bus-name "$BUS_NAME"

FailedEntryCount é zero para a configuração do destino, a regra descrita tem o padrão pretendido e o ARN do destino é igual ao de sua fila. AWS View agora mostra a regra e sua fila de destino. Ainda não há evento para entregar. Execute a verificação da conexão.

Comprove os Limites de Correspondência e Entrega

Nesta etapa, publique eventos correspondentes e não relacionados e, depois, teste uma falha de permissão de origem sem adicionar uma nova mensagem à fila.

Um evento EventBridge tem campos de roteamento e um conteúdo detail. A API PutEvents aceita Detail como uma string codificada em JSON. Escreva três entradas legíveis: um pedido feito, um evento de cobrança e um cancelamento. jq converte cada objeto Detail na string exigida pela API.

cat > event-inputs.json <<EOF
[
  {
    "EventBusName": "$BUS_NAME",
    "Source": "labex.orders",
    "DetailType": "OrderPlaced",
    "Detail": {
      "id": "route-order",
      "quantity": 2
    }
  },
  {
    "EventBusName": "$BUS_NAME",
    "Source": "labex.billing",
    "DetailType": "OrderPlaced",
    "Detail": {
      "id": "billing-event",
      "quantity": 9
    }
  },
  {
    "EventBusName": "$BUS_NAME",
    "Source": "labex.orders",
    "DetailType": "OrderCancelled",
    "Detail": {
      "id": "cancelled-event",
      "quantity": 1
    }
  }
]
EOF

Escreva a configuração em events.json:

jq 'map(.Detail |= tojson)' event-inputs.json > events.json

Publique o lote de eventos fornecido:

aws events put-events --entries file://events.json

Confira os atributos da fila $QUEUE_URL:

aws sqs get-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible

A resposta da publicação informa zero entradas com falha e um ID de evento para cada entrada aceita. Apenas route-order corresponde aos dois campos, portanto a fila contém uma mensagem disponível. AWS View mostra seu envelope completo de evento: origem, tipo de detalhe, conta, região e detalhe.

Leia o corpo real visível para o consumidor. O recebimento normalmente oculta uma mensagem durante seu tempo limite de visibilidade; --visibility-timeout 0 faz essa inspeção tornar a mensagem visível novamente de imediato. A consulta imprime apenas seu ID e corpo, mantendo o identificador de recebimento fora da exibição. Essa inspeção não conclui o processamento de negócio nem confirma a mensagem.

fromjson torna cada corpo JSON legível, mantendo seu ID de mensagem SQS. Ele altera apenas a saída exibida.

aws sqs receive-message \
  --queue-url "$QUEUE_URL" \
  --max-number-of-messages 10 \
  --visibility-timeout 0 \
  --output json | jq '[.Messages[] | {MessageId, Body: (.Body | fromjson)}]'

O corpo tem detail.id igual a route-order e detail.quantity igual a 2. As entradas de cobrança e cancelamento não chegaram a esta fila.

Agora aponte a política da fila para um ARN de origem diferente, mantendo a regra e o destino habilitados:

jq --arg wrong "${RULE_ARN}-other" '.Statement[0].Condition.ArnEquals["aws:SourceArn"]=$wrong' queue-policy.json > wrong-source-policy.json

Escreva a configuração em wrong-source-attributes.json:

jq -n --rawfile policy wrong-source-policy.json '{Policy:$policy}' > wrong-source-attributes.json

Aplique os atributos à fila $QUEUE_URL:

aws sqs set-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attributes file://wrong-source-attributes.json

Escreva a definição fornecida em event-inputs.json:

cat > event-inputs.json <<EOF
[
  {
    "EventBusName": "$BUS_NAME",
    "Source": "labex.orders",
    "DetailType": "OrderPlaced",
    "Detail": {
      "id": "denied-order",
      "quantity": 4
    }
  }
]
EOF

Escreva a configuração em denied-event.json:

jq 'map(.Detail |= tojson)' event-inputs.json > denied-event.json

Publique o lote de eventos fornecido:

aws events put-events --entries file://denied-event.json

Confira os atributos da fila $QUEUE_URL:

aws sqs get-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible

O EventBridge aceita esse evento, mas a regra não tem a permissão necessária na fila. A mensagem original continua sendo o único evento na fila; denied-order está ausente. Distinga a aceitação do evento da entrega ao destino ao diagnosticar um fluxo. Este exercício não examina novas tentativas de entrega.

Restaure a permissão pretendida e inspecione novamente:

aws sqs set-queue-attributes \
  --queue-url "$QUEUE_URL" \
  --attributes file://queue-attributes.json

Leia as mensagens entregues na fila $QUEUE_URL:

aws sqs receive-message \
  --queue-url "$QUEUE_URL" \
  --max-number-of-messages 10 \
  --visibility-timeout 0 \
  --output json | jq '[.Messages[] | {MessageId, Body: (.Body | fromjson)}]'

Apenas o route-order original está presente. A política corrigida autoriza entregas subsequentes; este laboratório não depende de uma nova tentativa de um evento anteriormente negado. Execute a verificação do roteamento.

Remova o Fluxo de Eventos

Nesta etapa, remova seu destino, sua regra, seu barramento personalizado e sua fila descartável, preservando os recursos não relacionados.

Remova o destino antes de excluir sua regra. Depois, exclua o barramento personalizado e a fila. A exclusão da fila descarta o evento sintético mantido para inspeção do roteamento; nenhum resultado de negócio foi alegado para ele.

aws events remove-targets \
  --rule "$RULE_NAME" \
  --event-bus-name "$BUS_NAME" \
  --ids order-queue

Exclua apenas a regra de eventos do exercício:

aws events delete-rule --name "$RULE_NAME" --event-bus-name "$BUS_NAME"

Exclua apenas o barramento de eventos do exercício:

aws events delete-event-bus --name "$BUS_NAME"

Exclua a fila do exercício $QUEUE_URL:

aws sqs delete-queue --queue-url "$QUEUE_URL"

Consultas somente leitura bem-sucedidas comprovam o que permanece:

aws events list-event-buses

Confira as regras de eventos restantes:

aws events list-rules --event-bus-name default

Confira as filas SQS restantes:

aws sqs list-queues

Confira o registro de referência não relacionado ao exercício:

aws dynamodb scan --table-name labex-ev01-reference --query Items

Apenas o barramento padrão permanece, sua lista de regras está vazia, as URLs de fila estão ausentes e o item de referência diz keep unchanged. Erros de autenticação ou de rede não comprovam a exclusão. AWS View mostra as listas vazias de recursos personalizados e a referência preservada.

Remova os arquivos comuns que você criou:

rm -f event-inputs.json order-pattern.json queue-policy.json queue-attributes.json targets.json events.json wrong-source-policy.json wrong-source-attributes.json denied-event.json

Execute a verificação da limpeza antes de encerrar a VM.

Resumo

Você criou um barramento EventBridge personalizado, identificou eventos de criação de pedidos correspondentes e conectou uma fila de destino com uma permissão exata para a regra de origem. Os corpos reais das mensagens na fila mostraram quais eventos chegaram ao consumidor, e o teste de origem negada separou a aceitação do evento da entrega. Você removeu os recursos deste laboratório, preservando o barramento padrão e os dados de referência.

A próxima unidade transforma um envelope de evento no conteúdo menor de que um consumidor de fila precisa.

Para aprofundar o tema, consulte a documentação da AWS: Padrões de eventos e correspondência de campos; Políticas de recursos de destino e permissões de entrega.