Skip to content

Gerenciamento de Arquivos

Essa API faz o nosso gerenciamento de arquivos. Por ela, é possível fazer upload, busca com filtros e download de arquivos. Sua função é permitir o upload de arquivos para RAG a manutenção desses arquivos e recuperá-los para os usos, como criação de banco de dados vetorial.

Todos os endpoints possuem o prefixo /v1/ e o parâmetro {workspace_id} no caminho. Este último serve para indicar o workspace relacionado à API Key do usuário, para autenticação, e também é usado para prefixar as keys dos arquivos dessa upload. Por exemplo, se feito o upload de um arquivo passando workspace_id=1234, a chave do arquivo será no formato 1234/pasta_opcional/uuid.extensao

Presigned URL

Esta API trabalha com o conceito de presigned URL, ou seja, os arquivos não passam pelo servidor. O gerenciamento é feito pela API, mas o upload e download são feitos diretamente com o Amazon S3. Serviços de nuvem como o Amazon S3 oferecem a funcionalidade de gerar um URL pré-assinado (presigned URL) por um tempo limite, para o acesso de um usuário final ou de uma aplicação cliente que não possuam as credenciais do serviço de armazenamento.

Você pode usar URLs pré-assinados para dar acesso temporário a arquivos no Amazon S3 sem mudar a política do bucket. Esses URLs permitem baixar ou enviar arquivos usando as credenciais de quem gerou o URL. Eles são válidos até a data e hora de expiração e podem ser reutilizados várias vezes até expirar.

Upload

Para realização do upload de um arquivo, são necessárias três etapas: a criação de um pre-signed URL, o post do arquivo para o S3 e a confirmação do upload.

Criação de presigned URL

Para a criação do presigned URL, é necessário chamar o endpoint da nossa API

GET Criar presigned URL

/v1/{workspace_id}/presigned/url

Parâmetros de Query:

  • expires_in (int): O tempo para a URL gerada expirar, em segundos. Por padrão é 3600.

Resposta:

Código 201 

{
  "url": "string, amazon s3 bucket URL",
  "fields": {
    "key": "string, key onde o upload será feito",
    "AWSAccessKeyId": "string",
    "policy": "string",
    "signature": "string"
  }
}

Upload para S3

O próximo passo é realizar o upload do arquivo diretamente no S3 para uma chave TEMPORÁRIA, utilizando os parâmetros retornados no passo anterior. Deve-se realizar um POST para a URL retornada, passando fields como data e o arquivo a ser enviado. Um exemplo de código python tendo a response JSON acima: 

requests.post(response["url"], data=response['fields'], files=files)

Resposta:

Código 204

Confirmar o Upload

Essa é uma etapa NECESSÁRIA! Após o POST para a URL do bucket, é necessário chamar o endpoint da connectors-api POST /v1/{workspace_id}/upload/confirm para salvar os metadados do arquivo no banco de dados e para mover o arquivo de sua chave temporária para a chave final.

POST Confirmar Upload

/v1/{workspace_id}/upload/confirm

Parâmetros no Body:

Um JSON ou dicionário com os seguintes campos, onde tags, categories, summary, slots e access são opcionais e temp_key e name são parâmetros obrigatórios: 

{ 
  "temp_key": "string, chave temporária do arquivo",
  "folder": "string, pasta para o arquivo. Opcional.",
  "document_metadata": {
    "name": "string, nome do arquivo com a extensão (.pdf por exemplo)", 
    "tags": [ "string", "tags", "do", "arquivo" ], 
    "categories": [ "string", "categorias" ], 
    "summary": "string, resumo do conteúdo. Opcional.", 
    "slots": {"chave": "valor"},
    "access": { 
      "curators": ["email do curador 1", "curador 2"]
    } 
  }
}

Resposta:

Código 201

JSON com metadados do arquivo enviado: 

{
    "owner_id": "018d5b84-052a-77f6-8b51-72f8bb8a43cf",
    "name": "test.txt",
    "s3_url": "url que aponta para o arquivo",
    "created_at": "2024-07-18T13:07:25.782418Z",
    "file_size": 22,
    "file_type": "txt",
    "tags": [
        "tag1",
        "teste"
    ],
    "categories": [
        "teste"
    ],
    "status": "private",
    "file_hash": "7068377a06d26fd2da3b873492366d64",
    "summary": "Resumo do teste",
    "access": {
        "curators": [
            "admin@aumo.ai"
        ]
    },
    "slots": {},
    "id": "51f61a6f-9e62-4ffe-a025-eb044921b172"
}

Busca

Também oferecemos um endpoint para busca de arquivos. Essa busca pode ser feita com base nos atributos de metadados dos arquivos, como nome, tamanho e data de criação. Esse endpoint fornece paginação, ao indicar o tamanho de cada página e qual página deve ser buscada, e ordenação por algum atributo (com o padrão sendo a data de criação).

GET Buscar Documento

/v1/filter/{workspace_id}

Atributos de metadados

Para a busca, os seguintes atributos podem ser usados para filtrar a resposta:

  • id (uuid): Identificador único do arquivo
  • owner_id (uuid): Id do usuário que fez o upload do arquivo
  • name (string): Nome do arquivo
  • s3_url (string): URL do arquivo no S3
  • created_at (datetime): Data de criação, no formato ISO8601, por exemplo → created_at=gt:2024-07-05T11:50:30-03:00
  • file_size (int): Tamanho do arquivo em bytes
  • file_type (string): Extensão do arquivo, por exemplo txt ou pdf
  • tags (array[string]): Lista das tags do arquivo
  • categories (array[string]): Lista das categorias do arquivo
  • status (string): Se o arquivo é "public", "private" ou "deleted"
  • file_hash (string): Hash md5 do conteúdo do arquivo
  • summary (string): Resumo do conteúdo
  • access (dict): Dicionário com informações sobre autorização e acesso
  • slots (dict): Dicionário genérico para metadados extras

Para detalhes de quais operações estão suportadas para cada atributo, acesse o endpoint /docs da API. https://aumo-connectors-api-url.com/docs

Parâmetros de Query:

  • order_by (array[string]): Critérios para ordenação. A string deve ser o nome do atributo e, opcionalmente, espaço e 'ASC' ou 'DESC'. O valor padrão é created_by.
  • pag (int): Índice da página a ser retornada. A primeira página tem índice 1
  • size (int): Número máximo de entradas em cada página. Padrão 50, máximo 100.

Além desses, existem os parâmetros de query de filtro. Eles seguem o seguinte formato: atributo=operação:valor. Opcionalmente, nos campos de tipo dict (access e slots), é possível adicionar a chave de dicionário a ser buscada com atributo=operação:chave->valor. Por exemplo, access=any:curators->admin@aumo.ai retorna todos os docs em que admin@aumo.ai é um dos curadores.

Por exemplo, a query a seguir irá buscar os arquivos com id igual a 1234, nome que contém a string 'test' e que possua a categoria 'categoria1': - id=eq:1234&name=contains:test&categories=any:categoria1

Resposta:

Código 200

Lista com metadados dos arquivos que obedecem os critérios: 

{
  "items": [
    {
      "owner_id": "string",
      "name": "string",
      "s3_url": "string",
      "created_at": "2024-07-18T13:07:25.782418Z",
      "file_size": 22,
      "file_type": "txt",
      "tags": [
        "tag1",
        "tag2",
        "teste"
      ],
      "categories": [
        "teste"
      ],
      "status": "private",
      "file_hash": "7068377a06d26fd2da3b873492366d64",
      "summary": "Resumo do teste",
      "access": {
        "curators": [
          "email@aumo.ai"
        ]
      },
      "slots": {},
      "id": "string"
    },
  ...
  ],
  "total": "int, número total de documentos que correspondem aos parâmetros de busca",
  "page": 1,
  "size": 50,
  "pages": 1
}

Download

Para o download dos arquivos já enviados, também usamos o conceito de presigned URL. Primeiro, chama-se a api de conectores para gerar um link de download temporário para o arquivo desejado. Depois, é feito um GET no URL retornado. O endpoint a ser chamado para geração da URL é:

GET Gerar URL de Download

/v1/{workspace_id}/file/{file_id}/download/url

Com o path parameter file_id sendo o identificador único do arquivo a ser baixado.

Parâmetros de Query:

  • expires_in (int): O tempo para a URL gerada expirar, em segundos. Por padrão é 3600, e o máximo é 7 dias.

Resposta:

Código 200

Retorna uma string com a URL pré-assinada.

Com a URL gerada, é possível baixar o download colando a URL em um navegador, ou realizando um GET.