O blog da AWS

Implementando rastreamento de progresso reativo para AWS Step Functions

Por Alexey Paramonov, Solutions Architect, ISV e Maximilian Schellhorn, Solutions Architect ISV.

Esta publicação do blog foi escrito por Alexey Paramonov, Solutions Architect, ISV e Maximilian Schellhorn, Solutions Architect ISV

Esta publicação do blog demonstra uma solução baseada em AWS Step Functions e Amazon API Gateway WebSockets para rastrear o progresso de execução de um fluxo de trabalho de longa duração. A solução atualiza o frontend regularmente e os usuários podem acompanhar o progresso e receber mensagens de status detalhadas.

Sites com processos de longa duração frequentemente não fornecem feedback aos usuários, levando a uma experiência ruim do cliente. Você pode ter experimentado isso ao reservar ingressos, procurar hotéis ou comprar produtos online. Esses sites frequentemente chamam múltiplos endpoints de backend e de terceiros e agregam os resultados para completar sua solicitação, causando o atraso. Nesses cenários de longa duração, uma solução transparente de rastreamento de progresso pode criar uma melhor experiência do usuário.

Visão geral

O exemplo fornecido usa:

  • AWS Serverless Application Model (AWS SAM) para implantação: um framework de código aberto para construir aplicações Serverless.
  • AWS Step Functions para orquestrar o fluxo de trabalho.
  • AWS Lambda para simular processos de longa duração.
  • API Gateway para fornecer uma API WebSocket para comunicações bidirecionais entre clientes e o backend.
  • Amazon DynamoDB para armazenar IDs de conexão dos clientes.

O exemplo fornece diferentes opções para relatar o progresso de volta à conexão WebSocket usando integração SDK do Step Functions, integrações Lambda ou Amazon EventBridge.

O diagrama a seguir descreve o exemplo:

  1. O usuário abre uma conexão com a API WebSocket. As funções Lambda OnConnect e OnDisconnect na seção “WebSocket Connection Management” persistem esta conexão no DynamoDB (veja a documentação). A conexão é bidirecional, o que significa que o usuário pode enviar solicitações através da conexão aberta e o backend pode responder com um novo status de progresso sempre que estiver disponível.
  2. O usuário envia um novo pedido através da API WebSocket. O API Gateway roteia a solicitação para a função AWS Lambda “OnOrder”, que inicia a execução da máquina de estados.
  3. À medida que a solicitação se propaga através da máquina de estados, enviamos atualizações de progresso de volta ao usuário via API WebSocket usando integrações de serviço AWS SDK.
  4. Para respostas de status mais personalizadas, podemos usar uma função AWS Lambda centralizada “ReportProgress” que atualiza a API WebSocket.

Como responder ao cliente?

Para enviar as atualizações de status de volta ao cliente via API WebSocket, três opções são exploradas:

Opção 1: Integração AWS SDK com invocação do API Gateway

Como o diagrama mostra, as tarefas de fluxo de trabalho do API Gateway começando com o prefixo “Report:” enviam respostas diretamente ao cliente via API WebSocket. Este é um exemplo da definição da máquina de estados para este passo:

          'Report: Workflow started':
            Type: Task
            Resource: arn:aws:states:::apigateway:invoke
            ResultPath: $.Params
            Parameters:
              ApiEndpoint: !Join [ '.',[ !Ref ProgressTrackingWebsocket, execute-api, !Ref 'AWS::Region', amazonaws.com ] ]
              Method: POST
              Stage: !Ref ApiStageName
              Path.$: States.Format('/@connections/{}', $.ConnectionId)
              RequestBody:
                Message: ???? Workflow started
                Progress: 10
              AuthType: IAM_ROLE
            Next: 'Mock: Inventory check'

Esta opção relata o progresso diretamente sem usar nenhuma função Lambda adicional. Isso limita a complexidade do sistema, reduz a latência entre a atualização de progresso e a resposta entregue ao cliente, e potencialmente reduz custos ao diminuir a duração de execução do Lambda. Uma desvantagem potencial é a personalização limitada da resposta e a familiarização com a linguagem de definição.

Opção 2: Usando uma função Lambda para relatar o status de progresso

Para personalizar ainda mais a lógica de resposta, crie uma função Lambda para relatórios. Como mostrado no ponto 4 do diagrama, você também pode invocar uma função “ReportProgress” diretamente da máquina de estados. Este trecho de código Python relata o status de progresso de volta à API WebSocket:

apigw_management_api_client = boto3.client('apigatewaymanagementapi', endpoint_url=api_url)
apigw_management_api_client.post_to_connection(
            ConnectionId=connection_id,
            Data=bytes(json.dumps(event), 'utf-8')
        )

Esta opção permite mais personalizações e integração na lógica de negócios de outras funções Lambda para rastrear o progresso com mais detalhes. Por exemplo, execução de loops e relatórios em cada iteração. A contrapartida é que você deve lidar com exceções e tentativas em seu código. Também aumenta a complexidade geral do sistema e custos adicionais associados à execução do Lambda.

Opção 3: Usando EventBridge

Você pode combinar a opção 2 com o EventBridge para fornecer uma solução centralizada para relatar o status de progresso. A solução também lida com tentativas com recuo se a função “ReportProgress” não puder se comunicar com a API WebSocket.

Você também pode usar integrações AWS SDK da máquina de estados para o EventBridge em vez de usar o API Gateway. Isso tem o benefício adicional de um sistema fracamente acoplado e resiliente, mas você pode experimentar maior latência devido aos serviços adicionais usados. A combinação de EventBridge e a função Lambda adiciona uma latência mínima, mas pode não ser aceitável para fluxos de trabalho de curta duração. No entanto, se o fluxo de trabalho leva dezenas de segundos para completar e envolve numerosas etapas, a opção 3 pode ser mais adequada.

Esta é a arquitetura:

  1. Como antes.
  2. Como antes.
  3. A integração AWS SDK envia a mensagem de status para o EventBridge.
  4. A mensagem se propaga para a função Lambda “ReportProgress”.
  5. A função Lambda envia a mensagem processada através da API WebSocket de volta ao cliente.

Implantando o exemplo

Pré-requisitos

Certifique-se de que você pode gerenciar recursos AWS do seu terminal.

  • AWS CLI e AWS SAM CLI instalados.
  • Você tem uma conta AWS. Caso contrário, visite esta página.
  • Seu usuário tem permissões suficientes para gerenciar recursos AWS.
  • Git está instalado.
  • NPM está instalado (apenas para implantação local do frontend).

Para visualizar o código-fonte e a documentação, visite o repositório GitHub. Este contém tanto o código do frontend quanto do backend.

Para implantar:

  1. Clone o repositório: 
    git clone "https://github.com/aws-samples/aws-step-functions-progress-tracking.git"
  2. Navegue até a raiz do repositório.
  3. Construa e implante o template AWS SAM: 
    sam build && sam deploy --guided
  4. Copie o valor de WebSocketURL na saída para uso posterior.
  5. O backend agora está em execução. Para testá-lo, use um frontend hospedado.

Alternativamente, você pode implantar o frontend baseado em React em sua máquina local:

  1. Navegue até “progress-tracker-frontend/”: 
    cd progress-tracker-frontend
  2. Inicie o aplicativo react: 
    npm start
  3. O comando abre o aplicativo React em seu navegador padrão. Se não acontecer automaticamente, navegue até http://localhost:3000/ manualmente.

Agora o aplicativo está pronto para testar.

Testando o aplicativo de exemplo

  1. A página web solicita uma URL WebSocket – este é o valor da implantação do template AWS SAM. Cole-o em Enter WebSocket URL no navegador e escolha Connect.
  2. Na próxima página, escolha Send Order e observe como o progresso muda.

    Isso envia a nova solicitação de pedido para a máquina de estados. À medida que progride, você recebe mensagens de status de volta através da API WebSocket.
  3. Opcionalmente, você pode inspecionar as mensagens brutas chegando ao cliente. Abra as Ferramentas do desenvolvedor em seu navegador e navegue até a aba Network. Filtre por WS (significa WebSocket) e atualize a página. Especifique a URL WebSocket, escolha Connect e depois escolha Send Order.

Limpeza

Os serviços usados nesta solução são elegíveis para o AWS Free Tier. Para limpar os recursos, no diretório raiz do repositório execute:

sam delete

Isso remove todos os recursos provisionados pelo arquivo template.yml.

Conclusão

Nesta publicação, você aprende como aumentar seus fluxos de trabalho do Step Functions com rastreamento de progresso de baixa latência via WebSockets do API Gateway. Considere adicionar o rastreamento de progresso aos seus fluxos de trabalho de longa duração para melhorar a experiência do cliente e fornecer uma aparência reativa para sua aplicação.

Navegue até o repositório GitHub e revise a implementação para ver como sua solução pode se tornar mais amigável e responsiva. Comece examinando o template.yml e a definição da máquina de estados e veja como o frontend lida com a comunicação WebSocket e a visualização de mensagens.

Para mais recursos de aprendizado Serverless, visite  Serverless Land.

Este conteúdo foi traduzido do post original do blog, que pode ser encontrado aqui.

Tradutores

Nicolas Tarzia é Senior Technical Account Manager na AWS, com mais de 13 anos de experiência, com ampla experiência em arquitetura cloud, engenharia e design de software. Sua área de interesse são tecnologias serverless.
https://www.linkedin.com/in/nicolastarzia
Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.
https://www.linkedin.com/in/danielabib/