Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Gerir os seus ficheiros: listar, obter, eliminar

Aula 3 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. O que acontece após o centésimo carregamento
  2. Fazer o inventário
  3. Verificar um ficheiro específico
  4. Eliminar e o que verificar antes
  5. Mantenha o seu armazenamento limpo
  6. Pontos-chave

O que acontece após o centésimo carregamento

Carregar um ficheiro demora três segundos; encontrar aquele que enviou há seis semanas demora muito mais tempo se não tiver planeado antecipadamente. Após os testes iniciais, uma conta acumula dezenas e depois centenas de documentos. Alguns estão desatualizados, outros estão duplicados e outros ainda são referenciados por aplicações em execução. A Files API expõe três operações para gerir este inventário: listar, obter e eliminar. Parecem secundárias enquanto o volume é baixo, mas tornam-se indispensáveis mais tarde.

Fazer o inventário

GET /v1/files devolve todos os ficheiros carregados na sua conta:

curl https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY"

A resposta é uma lista paginada, onde cada entrada repete os metadados vistos no momento do carregamento:

{
  "object": "list",
  "data": [
    {
      "id": "file_abc123",
      "object": "file",
      "bytes": 2458901,
      "created_at": 1710000000,
      "filename": "rapport-annuel.pdf",
      "purpose": "assistants"
    },
    {
      "id": "file_def456",
      "object": "file",
      "bytes": 15230,
      "created_at": 1710100000,
      "filename": "données-clients.csv",
      "purpose": "assistants"
    }
  ]
}

Esta vista resolve três situações muito concretas: recuperar um file_id que não guardou no momento do carregamento, verificar o tamanho real de um documento que parece anormalmente pesado e identificar candidatos à eliminação ordenando por created_at. É também o único local onde verá de relance que o mesmo relatório foi enviado três vezes sob três nomes diferentes.

Verificar um ficheiro específico

Quando já conhece o identificador, GET /v1/files/{file_id} consulta um único documento:

curl https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

Obtém as mesmas informações que no carregamento: identificador, nome, tamanho, data de criação e finalidade. A utilização mais útil desta chamada é preventiva. Antes de iniciar um processo que referencia um file_id armazenado há muito tempo na sua base de dados, uma verificação que dura alguns milissegundos poupa-o de um erro no meio de uma cadeia de pedidos faturados.

Eliminar e o que verificar antes

A eliminação é feita com DELETE /v1/files/{file_id} e a resposta confirma a operação:

curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"
{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

São necessárias duas verificações antes de acionar o gatilho. Primeiro, o ficheiro pode estar referenciado numa coleção — um conceito que detalharemos nas próximas lições. Eliminá-lo através da Files API não o remove automaticamente da coleção, deixando-o com uma referência morta no seu índice: remova-o primeiro da coleção e só depois do armazenamento. Em seguida, o ficheiro pode ser utilizado por fluxos de trabalho ativos; qualquer aplicação que mantenha este file_id na sua base de dados receberá erros assim que a eliminação for efetuada, muitas vezes em produção e raramente enquanto está a monitorizar os registos.

Mantenha o seu armazenamento limpo

A nomeação é a sua primeira ferramenta de gestão, porque o nome original é mantido nos metadados e constitui o único marcador legível numa lista de cem entradas. rapport-q1-2026.pdf significará algo para si daqui a oito meses; document.pdf nunca significará. O mesmo raciocínio se aplica a api-specs-v2.json versus data.json. Transforme isto num hábito quando prepara o ficheiro no seu disco, e não no momento do carregamento: é o nome local que é transmitido.

Os ficheiros carregados permanecem armazenados indefinidamente, sem expiração automática. Uma rotina de limpeza trimestral é suficiente para evitar desvios, em três passos:

  1. Liste os seus ficheiros com GET /v1/files
  2. Identifique os que já não estão em uso, pela data de criação ou nome
  3. Elimine-os com DELETE /v1/files/{file_id}

Três códigos de erro surgem nestas operações e são diagnosticados imediatamente. Um 404 sinaliza um ficheiro inexistente ou já eliminado, um caso típico de um script de limpeza executado duas vezes. Um 401 resulta de uma chave de API em falta ou inválida, muitas vezes uma variável de ambiente não carregada na shell atual. Um 413 indica que o ficheiro excede o limite permitido de 48 MB e ocorre no carregamento, não durante a gestão.

Pontos-chave

  • GET /v1/files lista todos os seus ficheiros com os respetivos metadados
  • GET /v1/files/{id} obtém um ficheiro específico
  • DELETE /v1/files/{id} elimina permanentemente um ficheiro
  • Nomeie os seus ficheiros explicitamente para facilitar a gestão
  • Verifique as dependências (coleções, fluxos de trabalho) antes de eliminar