Armazenamento S3

Como os arquivos chegam ao bucket

O script pede; o worker faz. Quando o seu código chama s3.upload, os bytes saem do sandbox para o processo do worker ao lado, que assina a requisição com as chaves da conexão e envia ao S3. As chaves ficam nas variáveis secretas do projeto e na memória do worker — nunca no seu código, nos logs ou no registro da execução.

Toda função recebe um arquivo como um objeto S3 — { "s3": { "path": "…", "name": "…" } }, o que um upload devolve — ou como a string do caminho. Esse formato também é o que um passo devolve, então um script envia um arquivo e o passo seguinte de um flow consegue ler.

Conecte um bucket

1. 1
   Escolha Amazon S3

   Em Integrações, clique em Adicionar integração e escolha Amazon S3 no grupo Armazenamento.

2. 2
   Preencha o bucket e as chaves

   Informe um Nome, o Bucket e a Região dele (uma lista de regiões da AWS), um Access key ID e uma Secret access key de um usuário IAM com permissão de ler e gravar naquele bucket.

3. 3
   Defina um prefixo de upload (opcional)

   O Upload prefix coloca todo upload dentro de uma pasta, por exemplo waiso/, para o bucket poder ser compartilhado com outros sistemas. As barras nas pontas são ajustadas para você.

4. 4
   Salve e teste

   A confirmação lista as duas variáveis em que as chaves se transformam — uma conexão chamada files gera S3_FILES_ACCESS_KEY_ID e S3_FILES_SECRET_ACCESS_KEY. Depois, Testar conexão confere o bucket com essas chaves: um secret errado informa Falhou.

Envie pelo código

O upload recebe texto, bytes ou (Python, JavaScript) um stream legível, além de um name e um folder opcional. Um texto é sempre o conteúdo do arquivo, nunca um caminho em disco. O exemplo grava um CSV pequeno e cria um link válido por dez minutos:

from waiso import s3

def main(title: str = "Weekly stock"):
    csv = "sku,qty\nA1,3\nB2,5\n"
    obj = s3.upload(csv, name="stock.csv", folder="reports")
    link = s3.presign(obj, expires=600)
    return {"title": title, "path": obj.s3.path, "link": link}

{
  "title": "Weekly stock",
  "path": "reports/3f9a1c2e_stock.csv",
  "link": "https://my-bucket.s3.us-east-1.amazonaws.com/reports/3f9a1c2e_stock.csv?X-Amz-Expires=600&…"
}

Onde o arquivo fica

A chave gravada é <prefixo de upload><folder>/<8 hex aleatórios>_<name>. Com o prefixo waiso/, a chamada acima grava waiso/reports/3f9a1c2e_stock.csv. Guarde o path devolvido — é o único jeito de encontrar o arquivo de novo pelo código.

Baixe, inspecione e compartilhe

Ler faz o caminho inverso: download devolve os bytes, ou texto quando você informa um encoding. Este script conta as linhas de dados de um CSV cujo caminho chega como entrada:

from waiso import s3

def main(path: str):
    text = s3.download(path, encoding="utf-8")
    rows = [line for line in text.splitlines()[1:] if line]
    info = s3.stat(path)
    return {"rows": len(rows), "bytes": info.size}

{
  "rows": 2,
  "bytes": 18
}

upload_from_url (uploadFromUrl, waiso_s3_upload_from_url) copia um arquivo de outro endereço web direto para o bucket. Quem busca é o worker — o seu código continua sem rede — e ele recusa endereços privados em cada redirecionamento com host_not_allowed.

O navegador de arquivos

Em Integrações, o Navegar Arquivos do card S3 abre o Navegador de Arquivos. Ele percorre o bucket pasta por pasta a partir da Raiz do bucket, busca com Buscar arquivos…, filtra por tipo (Pastas, Imagens, Documentos, Dados, Compactados, Código, Outros) e ordena por nome, tamanho ou data. Enviar arquivo e Nova pasta funcionam na pasta em que você está; Copiar nome do bucket e Atualizar ficam ao lado. O painel lateral soma o bucket — Tamanho Total, Objetos, Maiores Arquivos — com estimativa acima de 100.000 objetos.

Clicar num arquivo abre os detalhes: Chave S3, Tipo do Conteúdo, MIME Detectado, Visibilidade, e as ações Baixar, Copiar URL Temporária, Tornar Público e Tornar Privado — esta última pede confirmação, porque a URL permanente para de funcionar na hora.

Limites e erros

• s3:credential_missing — as variáveis das chaves da conexão foram excluídas. Abra a conexão e informe as chaves de novo.
• S3AclBlockedError (C: WAISO_ERR_ACL_BLOCKED) — o bucket está com Block Public Access ligado, então um arquivo não pode ficar público. S3AclNotSupportedError (WAISO_ERR_ACL_NOT_SUPPORTED) — o bucket está com as ACLs desligadas. Use presign.
• Os downloads são lidos para a memória; o s3::toBytes do C++ lê até 64 MB, e em C dá para ler um arquivo grande em pedaços de 64 KB com waiso_s3_download_stream.
• Uploads acima de 5 MB vão em partes de 10 MB por padrão (chunk_size).