Pular para conteúdo

AWS S3 LIST - Listar Objetos no Bucket

O que é este Node?

O AWS S3 LIST é o node responsável por listar arquivos e pastas armazenados em buckets do Amazon S3 com filtros por prefixo e limite de resultados.

Por que este Node existe?

Consultar o que existe no bucket é fundamental para gerenciar arquivos. O S3 LIST existe para:

  1. Descobrir arquivos: Ver o que está armazenado no bucket
  2. Filtrar por pasta: Listar apenas arquivos de uma pasta específica (prefixo)
  3. Auditoria: Verificar se arquivos foram enviados corretamente
  4. Processar em lote: Listar arquivos para processamento sequencial
  5. Validação: Checar existência de arquivos antes de operações

Como funciona internamente?

Quando o S3 LIST é executado, o sistema:

  1. Recebe as credenciais AWS: Access Key ID, Secret Access Key e região
  2. Aplica filtros: Usa prefix para filtrar (como "pasta/")
  3. Define limite: MaxKeys limita quantos resultados retornar
  4. Lista objetos: Chama listObjectsV2 do S3
  5. Retorna metadados: Key, Size, LastModified de cada arquivo
  6. Salva em variável: Lista disponível para próximos nodes

Código interno (aws-executors.service.ts:49-59): 

case 'list':
  const listResult = await s3.listObjectsV2({
    Bucket: data.bucketName,
    Prefix: data.prefix,
    MaxKeys: data.maxKeys || 1000,
  }).promise();
  return {
    success: true,
    objects: listResult.Contents,
    count: listResult.KeyCount,
  };

Quando você DEVE usar este Node?

Use S3 LIST sempre que precisar consultar arquivos no S3:

Casos de uso

  1. Listar documentos do cliente: "Mostrar todos RGs enviados"
  2. Verificar existência: "Checar se arquivo foi enviado"
  3. Processar backups: Listar todos backups para processar
  4. Relatórios: Contar quantos arquivos existem por pasta
  5. Limpeza seletiva: Listar para depois deletar seletivamente

Quando NÃO usar S3 LIST

  • Buckets gigantes (milhões de arquivos): Use S3 Inventory
  • Busca por conteúdo: LIST só mostra metadados, não conteúdo
  • Tempo real: LIST pode ter delay (eventual consistency)

Parâmetros Detalhados

accessKeyId (string, obrigatório)

O que é: Sua AWS Access Key ID (credencial de autenticação).

Onde conseguir: IAM Console → Users → Security credentials → Create access key

Flow completo para testar:

{
  "name": "Teste S3 List - Access Key",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar S3",
        "parameters": {
          "operation": "list",
          "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
          "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
          "region": "us-east-1",
          "bucketName": "meu-bucket"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Resultado",
        "parameters": {
          "message": "Encontrados {{s3_count}} arquivos no bucket!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "s3_1" },
    { "source": "s3_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Substitua pelos seus dados reais. Retorna lista de arquivos.

secretAccessKey (string, obrigatório)

O que é: Sua AWS Secret Access Key (senha da credencial).

Segurança: NUNCA exponha essa chave! Use variáveis de ambiente.

region (string, obrigatório)

O que é: Região AWS onde está o bucket S3.

Valores comuns: - us-east-1 (Norte da Virgínia) - us-west-2 (Oregon) - sa-east-1 (São Paulo) - eu-west-1 (Irlanda)

Flow completo para testar:

{
  "name": "Teste S3 List - Região",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar Brasil",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "sa-east-1",
          "bucketName": "bucket-brasil",
          "prefix": "uploads/"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "{{s3_count}} uploads encontrados na região São Paulo!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "s3_1" },
    { "source": "s3_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

bucketName (string, obrigatório)

O que é: Nome do bucket S3 para listar.

Flow completo para testar:

{
  "name": "Teste S3 List - Bucket",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar Documentos",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "us-east-1",
          "bucketName": "documentos-clientes"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Total",
        "parameters": {
          "message": "Total de documentos: {{s3_count}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "s3_1" },
    { "source": "s3_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

prefix (string, opcional)

O que é: Filtro por "pasta" (prefixo da key). Lista apenas arquivos que começam com este prefixo.

Padrão: "" (vazio = lista tudo)

Exemplos: - "uploads/" - Lista apenas arquivos em uploads/ - "rg/" - Lista apenas RGs - "backups/2025/01/" - Lista backups de janeiro/2025

Flow completo para testar:

{
  "name": "Teste S3 List - Prefix",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Pasta",
        "parameters": {
          "message": "Qual pasta deseja listar? (Ex: rg/, cpf/, uploads/)",
          "variable": "pasta"
        }
      }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Listar Pasta",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "us-east-1",
          "bucketName": "documentos",
          "prefix": "{{pasta}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "Pasta '{{pasta}}': {{s3_count}} arquivos encontrados"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "s3_1" },
    { "source": "s3_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite "rg/" → lista apenas arquivos em rg/

maxKeys (number, opcional)

O que é: Número máximo de objetos a retornar.

Padrão: 1000 (máximo padrão do S3)

Range: 1 a 1000

Flow completo para testar:

{
  "name": "Teste S3 List - MaxKeys",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar Primeiros 10",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "us-east-1",
          "bucketName": "uploads",
          "maxKeys": 10
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Top 10",
        "parameters": {
          "message": "Mostrando os {{s3_count}} primeiros arquivos (limite: 10)"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "s3_1" },
    { "source": "s3_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Retorna no máximo 10 resultados, mesmo que existam mais.

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "list"
accessKeyId string Sim AWS Access Key ID
secretAccessKey string Sim AWS Secret Access Key
region string Sim Região AWS (ex: us-east-1)
bucketName string Sim Nome do bucket S3
prefix string Não Filtro por prefixo (padrão: "")
maxKeys number Não Máximo de resultados (padrão: 1000)

Exemplo 1: Listar Documentos do Cliente

Objetivo: Mostrar todos documentos enviados por um cliente específico.

JSON para Importar

{
  "name": "Listar Documentos do Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Boas-vindas",
        "parameters": {
          "message": "Vou consultar seus documentos enviados..."
        }
      }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Listar Docs",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "sa-east-1",
          "bucketName": "documentos-clientes",
          "prefix": "documentos/{{phone}}/"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Tem Documentos?",
        "parameters": {
          "variable": "s3_count",
          "operator": "greater_than",
          "value": "0"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Mostrar Docs",
        "parameters": {
          "message": "Você tem {{s3_count}} documento(s) enviado(s):\n\n{{s3_objects}}"
        }
      }
    },
    {
      "id": "message_3",
      "type": "message",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Sem Docs",
        "parameters": {
          "message": "Você ainda não enviou nenhum documento."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "s3_1" },
    { "source": "s3_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_2", "label": "true" },
    { "source": "condition_1", "target": "message_3", "label": "false" },
    { "source": "message_2", "target": "end_1" },
    { "source": "message_3", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Vou consultar seus documentos enviados...
Sistema: Você tem 3 documento(s) enviado(s):

[Lista de documentos]

Exemplo 2: Contar Backups por Mês

Objetivo: Relatório de quantos backups foram feitos em cada mês.

JSON para Importar

{
  "name": "Relatório de Backups Mensais",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Iniciar",
        "parameters": {
          "message": "Gerando relatório de backups..."
        }
      }
    },
    {
      "id": "s3_1",
      "type": "aws_s3",
      "position": { "x": 500, "y": 50 },
      "data": {
        "label": "Janeiro",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "us-east-1",
          "bucketName": "backups",
          "prefix": "2025/01/"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Salvar Jan",
        "parameters": {
          "variable": "backups_jan",
          "value": "{{s3_count}}"
        }
      }
    },
    {
      "id": "s3_2",
      "type": "aws_s3",
      "position": { "x": 500, "y": 150 },
      "data": {
        "label": "Fevereiro",
        "parameters": {
          "operation": "list",
          "accessKeyId": "SUA_ACCESS_KEY",
          "secretAccessKey": "SUA_SECRET_KEY",
          "region": "us-east-1",
          "bucketName": "backups",
          "prefix": "2025/02/"
        }
      }
    },
    {
      "id": "variable_2",
      "type": "variable",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Salvar Fev",
        "parameters": {
          "variable": "backups_fev",
          "value": "{{s3_count}}"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Relatório",
        "parameters": {
          "message": "RELATÓRIO DE BACKUPS 2025\n\nJaneiro: {{backups_jan}} backups\nFevereiro: {{backups_fev}} backups\n\nTotal: {{total}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "s3_1" },
    { "source": "s3_1", "target": "variable_1" },
    { "source": "variable_1", "target": "s3_2" },
    { "source": "s3_2", "target": "variable_2" },
    { "source": "variable_2", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Gerando relatório de backups...
Sistema: RELATÓRIO DE BACKUPS 2025

Janeiro: 45 backups
Fevereiro: 38 backups

Total: 83

Resposta do Node

{
  "success": true,
  "objects": [
    {
      "Key": "uploads/documento1.pdf",
      "Size": 1024576,
      "LastModified": "2025-01-15T10:30:00.000Z",
      "ETag": "\"abc123def456\"",
      "StorageClass": "STANDARD"
    },
    {
      "Key": "uploads/imagem.jpg",
      "Size": 524288,
      "LastModified": "2025-01-15T11:00:00.000Z",
      "ETag": "\"xyz789\"",
      "StorageClass": "STANDARD"
    }
  ],
  "count": 2
}

Variáveis criadas: - {{s3_objects}} - Array com lista de objetos - {{s3_count}} - Quantidade de objetos encontrados

Estrutura de cada objeto: - Key - Caminho completo do arquivo - Size - Tamanho em bytes - LastModified - Data de última modificação - ETag - Hash MD5 do arquivo - StorageClass - Classe de armazenamento

Configuração AWS

Permissões IAM Necessárias

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::seu-bucket"
    }
  ]
}

IMPORTANTE: Permissão é no BUCKET (não /*), diferente de Get/Put/Delete!

Boas Práticas

Performance

SIM: - Use prefix para filtrar (mais rápido que listar tudo) - Limite maxKeys para evitar timeouts - Para buckets grandes, use S3 Inventory ao invés - Cache resultados se listar frequentemente

NÃO: - Não liste buckets com milhões de objetos sem prefix - Não use LIST em loop para verificar existência (use HeadObject) - Não liste todo bucket se só precisa de uma pasta

Organização

SIM: - Organize arquivos em "pastas" lógicas (prefixos) - Use padrão consistente: ano/mes/dia/arquivo - Facilita filtragem com prefix

Padrão recomendado: 

documentos/
  cliente-123/
    rg.jpg
    cpf.jpg
  cliente-456/
    rg.jpg
backups/
  2025/
    01/
      backup-2025-01-15.json

Paginação

SIM: - Para >1000 resultados, implemente paginação - Use ContinuationToken retornado - Processe em lotes

NÃO: - Não tente listar milhões de objetos de uma vez

Dicas

Prefix vs Delimiter: Use prefix para filtrar, delimiter para simular "pastas".

IsTruncated: Se true, existem mais resultados. Use ContinuationToken para próxima página.

Size: Útil para calcular total de armazenamento usado.

LastModified: Ordene por data para encontrar mais recentes/antigos.

StorageClass: STANDARD, GLACIER, etc. Útil para lifecycle policies.

Verificar existência: Para checar se 1 arquivo existe, use HeadObject (mais rápido que LIST).

S3 Inventory: Para buckets grandes (>1M objetos), use S3 Inventory Report ao invés de LIST.

Próximo Node

→ S3 UPLOAD - Enviar arquivo para S3 → S3 DOWNLOAD - Baixar arquivo do S3 → S3 DELETE - Deletar arquivo do S3