S3 Storage

Saiba mais sobre o conector S3 Storage e como utilizá-lo na Plataforma de Integração Digibee.

O S3 Storage se conecta ao AWS S3 e realiza as seguintes operações no armazenamento: List, Download, Upload, Delete e Move.

Parâmetros

Configure o conector utilizando os parâmetros abaixo. Os campos que suportam expressões Double Braces estão marcados na coluna Suporta DB.

General

Parâmetro	Descrição	Tipo de dado	Suporta DB	Valor padrão	Visível quando
Use Dynamic Account	Se habilitado, o conector usa a conta de forma dinâmica via o conector Store Account; caso contrário, usa a conta estática configurada em Contas na Plataforma.	Boolean	❌	false	—
Scoped	Se habilitado, isola a conta armazenada de outros subprocessos. Não é suportado para contas usadas em headers ou body. Para saber mais, consulte a documentação de Dynamic Accounts.	Boolean	❌	false	Use Dynamic Account está habilitado
Account Name	Nome da conta definida no conector Store Account.	String	✅	N/A	Use Dynamic Account está habilitado
Account	Conta usada pelo conector. Deve ser do tipo de conta AWS V4, configurada em Contas na Plataforma. É necessário fornecer o client ID e a secret key do console da AWS.	String	❌	N/A	Use Dynamic Account está desabilitado
Operation	Define a operação a ser executada: List, Download, Upload, Delete ou Move.	String	❌	Upload	—
Region	Região da AWS onde o bucket S3 está localizado.	String	❌	South America (Sao Paulo)	—
Bucket Name	Nome do bucket S3.	String	✅	digibee-amazon-s3-connector-test	—
Bucket Name - Move	Nome do bucket de onde o arquivo será movido.	String	✅	N/A	Operation é Move
File Name	Nome ou caminho completo do arquivo local a ser usado na operação (ex.: tmp/processed/file.txt).	String	✅	file.csv	Operation é Download ou Upload
Remote File Name	Nome ou caminho completo do arquivo no S3 a ser usado na operação (ex.: tmp/processed/file.txt).	String	✅	test.csv	Operation é Download, Upload, Delete ou Move
Remote File Name - Move	Novo nome a ser atribuído ao arquivo remoto após ser movido.	String	✅	N/A	Operation é Move
Remote Directory	Diretório remoto no S3 a ser usado em uma operação de Download, Upload ou Delete.	String	❌	upload/	—
Remote Directory - Move	Nome do diretório remoto que contém o arquivo a ser movido.	String	❌	N/A	Operation é Move
Page Size	Número de itens a serem retornados por página. O valor padrão é 1000. Para recuperar mais itens do que o tamanho da página, use o nextToken retornado na resposta com o parâmetro Next Page Token.	Integer	❌	1000	Operation é List
Next Page Token	Token usado para solicitar a próxima página de resultados. A próxima página retorna o número de itens definido em Page Size.	String	❌	N/A	Operation é List
Generate Download Link	Se habilitado, gera um link público de download para o arquivo.	Boolean	❌	false	Operation é Upload
Expiration Timestamp (in ms)	Tempo de expiração do link de download, em milissegundos. Informe o timestamp atual somado à duração desejada (ex.: timestamp atual + 600000 para um link de 10 minutos). Se não for informado, o link expira 15 minutos após o timestamp atual.	Number	❌	N/A	Operation é Upload e Generate Download Link está habilitado
Include user metadata on upload	Se habilitado, anexa ao objeto no S3 os metadados configurados em Metadata ou Metadata file. Se desabilitado, o objeto é enviado sem metadados de usuário, mesmo que Metadata ou Metadata file estejam configurados.	Boolean	❌	false	Operation é Upload
Metadata (JSON)	Objeto JSON contendo pares chave-valor personalizados a serem anexados ao objeto no S3. Quando configurado, o conector retorna os metadados na resposta do step. É ignorado quando Metadata file resolve para um caminho não vazio.	JSON Object	✅	N/A	Operation é Upload e Include user metadata on upload está habilitado
Metadata file path	Caminho relativo para um arquivo JSON no diretório de trabalho do pipeline (ex.: orders-report.csv.metadata.json). Quando esse campo resolve para um caminho não vazio, o conector lê o conteúdo do arquivo e o utiliza como metadados do objeto, ignorando qualquer valor definido em Metadata. Se o campo estiver ausente, em branco ou resolver para um valor vazio, o conector utiliza o valor de Metadata.	String	✅	N/A	Operation é Upload e Include user metadata on upload está habilitado
Path-style access	Se habilitado, usa o formato de URL path-style para acessar o S3. Útil ao se conectar a armazenamentos compatíveis com S3 que exigem acesso path-style, como um endpoint personalizado.	Boolean	❌	false	—
Fail on error	Se habilitado, interrompe a execução do pipeline quando ocorre um erro. Caso contrário, a execução prossegue e o resultado retorna false para a propriedade "success".	Boolean	❌	false	—
Custom Endpoint	Se habilitado, permite o uso de uma URL de endpoint personalizada para o S3.	Boolean	❌	false	—
Endpoint URL	URL do endpoint personalizado.	String	✅	N/A	Custom Endpoint está habilitado

A manipulação de arquivos dentro de um pipeline é realizada em uma área protegida. Todos os arquivos são acessíveis somente por meio de um diretório temporário, e cada chave de pipeline fornece acesso ao seu próprio conjunto de arquivos.

Documentation

Parâmetro	Description	Tipo de dado	Suporta DB	Valor padrão
Documentation	Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.	String	❌	N/A

Fluxo de mensagens

Input

O conector só requer uma mensagem de entrada se um campo estiver configurado com uma expressão Double Braces. Caso contrário, nenhuma entrada específica é esperada; basta configurar os campos para a operação selecionada.

Output

O conector retorna um objeto JSON contendo o resultado da operação. Os campos retornados variam de acordo com a operação.

List

{
  "success": true,
  "content": [
    {
      "bucketName": "digibee-amazon-s3-connector-test",
      "key": "list/test.csv",
      "size": 9,
      "lastModified": 1596139663000,
      "storageClass": "STANDARD",
      "owner": null,
      "etag": "59587d0fd956dee6905d423bfda2acaf"
    }
  ],
  "count": 1,
  "nextToken": "1kWwy…..."
}

Campos de saída:

• success: retorna true se a operação foi bem-sucedida, ou false se falhou.

• content: array contendo as informações do arquivo.

• bucketName: nome do bucket.

• key: caminho do diretório e nome do arquivo.

• size: tamanho do arquivo.

• lastModified: data da última modificação feita no arquivo.

• storageClass: classe de armazenamento configurada no S3.

• owner: proprietário do arquivo.

• etag: entity tag, um hash gerado pelo S3 para o arquivo.

• count: número de objetos retornados.

• nextToken: token usado para paginar os itens restantes. Retornado somente quando há mais objetos a serem listados.

Download

{
  "success": true,
  "fileName": "test.file",
  "remoteDirectory": "pagination_folder/",
  "remoteFileName": "c4b88b6b-83bb-42b0-9de6-0371389db585.csv",
  "bucketName": "digibee-amazon-s3-connector-test"
}

Campos de saída:

• success: retorna true se a operação foi bem-sucedida, ou false se falhou.

• fileName: nome do arquivo baixado para o diretório do pipeline.

• remoteDirectory: nome do diretório remoto no S3.

• remoteFileName: nome do arquivo remoto no S3.

• bucketName: nome do bucket S3.

Upload

{
  "success": true,
  "fileName": "test.file",
  "remoteDirectory": "pagination_folder/",
  "remoteFileName": "test.file",
  "urlGenerated": "https://digibee-amazon-s3-connector-test.s3.sa-east-1.amazonaws.com/pagination_folder/test.file?....",
  "bucketName": "digibee-amazon-s3-connector-test"
}

Quando Metadata ou Metadata file está configurado e Include user metadata está habilitado, a resposta também inclui os metadados anexados ao objeto:

{
  "success": true,
  "fileName": "test.file",
  "remoteDirectory": "pagination_folder/",
  "remoteFileName": "test.file",
  "urlGenerated": "https://digibee-amazon-s3-connector-test.s3.sa-east-1.amazonaws.com/pagination_folder/test.file?....",
  "bucketName": "digibee-amazon-s3-connector-test",
  "metadata": {
    "source": "orders-pipeline",
    "environment": "production"
  }
}

Campos de saída:

• success: retorna true se a operação foi bem-sucedida, ou false se falhou.

• fileName: nome do arquivo local enviado a partir do diretório do pipeline.

• remoteDirectory: nome do diretório remoto no S3.

• remoteFileName: nome do arquivo remoto no S3.

• bucketName: nome do bucket S3.

• urlGenerated: link público de download do arquivo. Retornado somente quando Generate Download Link está habilitado.

• metadata: pares chave-valor anexados ao objeto como metadados de usuário. Retornado somente quando os metadados são aplicados.

Move

{
  "success": true,
  "remoteDirectory": "pagination_folder/",
  "remoteFileName": "c4b88b6b-83bb-42b0-9de6-0371389db585.csv",
  "remoteFileNameMove": "abc.file",
  "remoteDirectoryMove": "list/",
  "bucketName": "digibee-amazon-s3-connector-test",
  "bucketNameMove": "digibee-amazon-s3-connector-test"
}

Campos de saída:

• success: retorna true se a operação foi bem-sucedida, ou false se falhou.

• remoteDirectory: nome do diretório remoto original no S3.

• remoteFileName: nome do arquivo remoto original no S3.

• bucketName: nome do bucket S3 original.

• bucketNameMove: nome do bucket de destino.

• remoteDirectoryMove: nome do diretório remoto de destino.

• remoteFileNameMove: novo nome atribuído ao arquivo após ser movido.

Delete

{
  "success": true,
  "remoteDirectory": "list/",
  "remoteFileName": "abc.file",
  "bucketName": "digibee-amazon-s3-connector-test"
}

Campos de saída:

• success: retorna true se a operação foi bem-sucedida, ou false se falhou.

• remoteDirectory: nome do diretório remoto no S3.

• remoteFileName: nome do arquivo remoto excluído do S3.

• bucketName: nome do bucket S3.

Error

{
  "success": false,
  "message": "Could no issue the operation: download in the AWS S3 Storage",
  "error": "com.amazonaws.services.s3.model.AmazonS3Exception: The specified key does not exist. (Service: Amazon S3; Status Code: 404; Error Code: NoSuchKey; ...)"
}

Campos de saída:

• success: retorna false quando a operação falha.

• message: descrição do erro fornecida pelo conector.

• error: mensagem de erro retornada pelo servidor do S3.