Aprimoramento do compartilhamento de arquivos usando o Amazon S3 e o AWS Step Functions

Este blog post mostra um exemplo de aplicativo que pode fornecer essa funcionalidade extra usando os serviços Serverless da AWS.

Visão geral

O código incluído neste exemplo usa uma variedade de serviços Serverless:

• O Amazon API Gateway recebe todas as solicitações recebidas dos usuários e autoriza o acesso usando o Amazon Cognito.
• O AWS Step Functions coordena atividades de compartilhamento e download de arquivos, como validação de usuários, verificação de elegibilidade para download, gravação de eventos, roteamento de solicitações e formatação de respostas.
• O AWS Lambda implementa atividades administrativas, como recuperação de metadados, listagem de arquivos e exclusão.
• O Amazon DynamoDB armazena permissões para garantir que os usuários tenham acesso somente aos arquivos que foram compartilhados com eles.
• O Amazon S3 fornece armazenamento durável para que os usuários façam upload e download de arquivos.
• O Amazon Athena fornece uma maneira eficiente de consultar os registros de acesso do S3 para extrair o download e o uso da largura de banda.
• O Amazon QuickSight fornece um painel visual para visualizar análises de download e largura de banda.

O AWS Cloud Development Kit (AWS CDK) implanta os recursos da AWS e pode se conectar ao seu processo preferido de CI/CD.

Visão geral da arquitetura

1. Interface do usuário: O front-end é um aplicativo estático de página única (SPA) em React hospedado no S3 e servido via Amazon CloudFront. A interface do usuário usa componentes de design do AWS NorthStar e do Cloudscape. A interface do usuário do Amplify simplifica as interações com o Amazon Cognito, fornecendo a capacidade de fazer login, cadastrar-se e realizar verificação de e-mail.
2. API Gateway: os usuários interagem por meio de uma API REST do API Gateway.
3. Autenticação: o Amazon Cognito gerencia as identidades e o acesso dos usuários. Os usuários se inscrevem usando o endereço de e-mail e depois verificam o endereço de e-mail. As solicitações para a API incluem um token de acesso, que é verificado usando um autorizador do Amazon Cognito.
4. Microsserviços: as operações principais são criadas com o Lambda. Os fluxos de trabalho primários permitem que os usuários compartilhem e baixem arquivos, e o Step Functions organiza várias etapas do processo. Isso pode incluir a validação de solicitações, a autorização de que os usuários tenham as permissões corretas para acessar arquivos, o envio de notificações, a auditoria e o controle de quem está acessando os arquivos.
5. Armazenamento de permissões: o DynamoDB armazena informações essenciais sobre arquivos, como detalhes de propriedade e permissões para compartilhamento. Ele rastreia quem possui um arquivo e quem teve acesso para baixá-lo.
6. Armazenamento de arquivos: um bucket do S3 é o repositório central de arquivos. Cada usuário tem uma pasta dedicada no bucket do S3 para armazenar arquivos.
7. Notificações: a solução usa o Amazon Simple Notification Service (SNS) para enviar notificações por e-mail aos destinatários quando um arquivo é compartilhado.
8. Análise: os registros de acesso do S3 são gerados sempre que os usuários baixam ou carregam arquivos no bucket de armazenamento de arquivos. O Amazon Athena filtra esses registros para gerar um relatório de download, extraindo informações importantes (como a identidade dos usuários que baixaram os arquivos e a largura de banda total consumida durante os downloads).
9. Relatórios: o Amazon QuickSight fornece uma interface para os administradores visualizarem relatórios e painéis de download.

Passo a passo

Como pré-requisitos, você precisa:

• Node.js versão 16+.
• AWS CLI versão 2+.
• Uma conta da AWS e um perfil configurados no seu computador.

Siga as instruções no repositório de código para implantar o exemplo em sua conta da AWS. Depois que o aplicativo for implantado, você poderá acessar a interface do usuário.

Neste exemplo, você percorre as etapas para criar, carregar um arquivo e compartilhá-lo com um destinatário:

1. O exemplo exige que os usuários se identifiquem usando um endereço de e-mail. Escolha Criar conta e, em seguida, faça login com suas credenciais.
   
2. Selecione Compartilhar um arquivo.
   
3. Selecione Escolher arquivo para navegar e selecione o arquivo para compartilhar. Escolha Avançar.
   
4. Você deve preencher pelo menos um destinatário. Escolha Adicionar destinatário para adicionar mais destinatários. Escolha Avançar.
   
5. Defina a data de expiração e limite de downloads para configurar a data de expiração do compartilhamento e limitar o número de downloads permitidos. Escolha Avançar.
   
6. Revise os detalhes da solicitação de compartilhamento. Você pode navegar até as telas anteriores para modificar. Escolha Enviar quando terminar.
   
7. Escolha Meus arquivos para ver seu arquivo compartilhado.
   

Estendendo a solução

O exemplo usa Step Functions para permitir que você estenda e personalize os fluxos de trabalho. Isso implementa um fluxo de trabalho padrão, oferecendo a capacidade de substituir a lógica ou introduzir novas etapas para atender às suas necessidades.

Esta seção mostra o comportamento padrão dos fluxos de trabalho das Funções de Etapa de Compartilhar Arquivo e Baixar Arquivo.

O fluxo de trabalho de compartilhamento de arquivos

O fluxo de trabalho de compartilhamento de arquivos consiste nas seguintes etapas:

1. Validar: verifique se a solicitação de compartilhamento contém todos os campos obrigatórios.
2. Obter informações do usuário: recupere as informações do usuário conectado, como nome e endereço de e-mail, do Amazon Cognito.
3. Autorizar: verifique as permissões armazenadas no DynamoDB para verificar se o usuário é proprietário do arquivo e tem permissão para compartilhá-lo.
4. Auditoria: registre a tentativa de compartilhamento para fins de auditoria.
5. Processo: atualize o armazenamento de permissões no DynamoDB.
6. Enviar notificações: envie notificações por e-mail aos destinatários para que eles saibam que um novo arquivo foi compartilhado com eles.

O fluxo de trabalho de download do arquivo

O fluxo de trabalho do arquivo de download consiste nas seguintes etapas:

1. Validar: verifique se a solicitação de download contém os campos obrigatórios (por exemplo, ID do usuário e ID do arquivo).
2. Obter informações do usuário: recupere as informações do usuário do Amazon Cognito, como nome e endereço de e-mail.
3. Autorizar: verifique o armazenamento de permissões no DynamoDB para verificar se o usuário é proprietário do arquivo ou se é um destinatário válido com permissões para fazer o download do arquivo.
4. Auditoria: registre a tentativa de download.
5. Processo: gere um URL de download pré-assinado do S3 de curta duração e retorne ao usuário.

Mapeamento de dados da API Step Functions

O exemplo usa mapeamentos de dados de solicitação e resposta do API Gateway para permitir que a API REST se comunique diretamente com o Step Functions. Esta seção mostra como personalizar o mapeamento com base no seu caso de uso.

Solicitar mapeamento de dados

A API REST do API Gateway usa modelos Apache VTL para transformar e criar solicitações para o serviço subjacente. Essa solução resume a construção desses modelos usando uma construção CDK:

api.root
.addResource('share')
.addResource('{fileId}')
.addMethod(
  'POST',
   StepFunctionApiIntegration(shareStepFunction, [
      { name: 'fileId', sourceType: 'params' },
      { name: 'recipients', sourceType: 'body' },
      /* your custom input fields */
   ]),
   authorizerSettings,
);

A construção StepFunctionApiIntegration realiza o mapeamento da solicitação, permitindo que você extraia campos da solicitação de API recebida e os transmita como entradas para um fluxo de trabalho do Step Functions. Isso gera o seguinte modelo de VTL:

{
  "name": "$context.requestId",
  "input": "{\"userId\":\"$context.authorizer.claims.sub\",\"fileId\":\"$util.escap eJavaScript($input.params('fileId'))\",\"recipients\":$util.escapeJavaScript($input.json('$.recipients'))}",
  "stateMachineArn": "...stateMachineArn"
}

Nesse cenário, os campos são extraídos dos parâmetros, do corpo e do cabeçalho de autorização da solicitação da API e passados para o fluxo de trabalho. Você pode personalizar a configuração para atender às suas necessidades.

Mapeamento de dados de resposta

O exemplo tem modelos de mapeamento de resposta usando o Apache VTL. A saída da última etapa em um fluxo de trabalho é mapeada como uma resposta JSON e retornada ao usuário por meio do API Gateway. A resposta também inclui cabeçalhos CORS:

#set($context.responseOverride.header.Access-Control-Allow-Headers = '*')
#set($context.responseOverride.header.Access-Control-Allow-Origin = '*')
#set($context.responseOverride.header.Access-Control-Allow-Methods = '*')
#if($input.path('$.status').toString().equals("FAILED"))
#set($context.responseOverride.status = 500)
{
  "error": "$input.path('$.error')",
  "cause": "$input.path('$.cause')"
}
#else
  $input.path('$.output')
#end

Você pode personalizar esse modelo de resposta para atender às suas necessidades. Por exemplo, você pode fornecer um comportamento personalizado para diferentes códigos de resposta.

Conclusão

Nesta postagem do blog, você aprende como compartilhar arquivos com segurança com terceiros autorizados e rastrear seu acesso usando os serviços Serverless da AWS.

O aplicativo de exemplo apresentado usa o Step Functions para permitir que você estenda e personalize os fluxos de trabalho para atender aos requisitos do seu caso de uso.

Para saber mais sobre os conceitos discutidos, visite:

• O repositório GitHub do aplicativo de exemplo
• Compartilhamento de objetos com URLs pré-assinados
• Usando o AWS Step Functions com outros serviços
• Sistema de design Cloudscape para a nuvem
• Referência do utilitário do modelo de mapeamento

Para obter mais recursos de aprendizado sem servidor, visite Serverless Land. Saiba mais sobre o processamento de dados no Step Functions lendo o guia: Introdução ao mapa distribuído para processamento de dados sem servidor.