Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gestisci i tuoi file: elenca, recupera, elimina

Lezione 3 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Cosa succede dopo il centesimo caricamento
  2. Fai l’inventario
  3. Verifica un file specifico
  4. Elimina e cosa controllare prima
  5. Mantieni pulito il tuo archivio
  6. Punti chiave

Cosa succede dopo il centesimo caricamento

Caricare un file richiede tre secondi; trovare quello inviato sei settimane fa richiede molto più tempo se non hai pianificato per tempo. Dopo i test iniziali, un account accumula decine e poi centinaia di documenti. Alcuni sono obsoleti, altri duplicati e altri ancora sono referenziati da applicazioni ancora in esecuzione. La Files API espone tre operazioni per gestire questo inventario: elencare, recuperare ed eliminare. Sembrano secondarie quando il volume è basso, ma diventano indispensabili in seguito.

Fai l’inventario

GET /v1/files restituisce tutti i file caricati sul tuo account:

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

La risposta è un elenco paginato, dove ogni voce ripete i metadati visti al momento del caricamento:

{
  "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"
    }
  ]
}

Questa vista risolve tre situazioni molto concrete: recuperare un file_id che non hai salvato al momento del caricamento, verificare la dimensione effettiva di un documento che sembra anormalmente pesante e individuare i candidati all’eliminazione ordinando per created_at. È anche l’unico luogo in cui vedrai a colpo d’occhio che lo stesso rapporto è stato inviato tre volte con tre nomi diversi.

Verifica un file specifico

Quando conosci già l’identificatore, GET /v1/files/{file_id} interroga un singolo documento:

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

Recuperi le stesse informazioni del caricamento: identificatore, nome, dimensione, data di creazione e scopo. L’utilità principale di questa chiamata è difensiva. Prima di avviare un processo che fa riferimento a un file_id archiviato da tempo nel tuo database, una verifica che dura pochi millisecondi ti evita un errore nel mezzo di una catena di richieste a pagamento.

Elimina e cosa controllare prima

L’eliminazione avviene con DELETE /v1/files/{file_id} e la risposta conferma l’operazione:

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

Sono necessari due controlli prima di premere il grilletto. Innanzitutto, il file potrebbe essere referenziato in una collezione, un concetto che dettagliamo nelle prossime lezioni. Eliminarlo tramite la Files API non lo rimuove automaticamente dalla collezione, lasciandoti con un riferimento morto nel tuo indice: rimuovilo prima dalla collezione, poi dall’archivio. Inoltre, il file potrebbe essere utilizzato da flussi di lavoro attivi; qualsiasi applicazione che mantiene questo file_id nel suo database riceverà errori non appena avviene l’eliminazione, spesso in produzione e raramente mentre stai monitorando i log.

Mantieni pulito il tuo archivio

La denominazione è il tuo primo strumento di gestione, perché il nome originale viene conservato nei metadati e costituisce l’unico marcatore leggibile in un elenco di cento voci. rapport-q1-2026.pdf avrà un significato per te tra otto mesi; document.pdf mai. Lo stesso ragionamento vale per api-specs-v2.json rispetto a data.json. Fanne un’abitudine quando prepari il file sul tuo disco, non al momento del caricamento: è il nome locale che viene trasmesso.

I file caricati rimangono archiviati a tempo indeterminato, senza scadenza automatica. Una routine di pulizia trimestrale è sufficiente per evitare derive, in tre passaggi:

  1. Elenca i tuoi file con GET /v1/files
  2. Identifica quelli non più in uso, per data di creazione o nome
  3. Eliminali con DELETE /v1/files/{file_id}

Tre codici di errore emergono in queste operazioni e vengono diagnosticati immediatamente. Un 404 segnala un file inesistente o già eliminato, caso tipico di uno script di pulizia eseguito due volte. Un 401 deriva da una chiave API mancante o non valida, spesso una variabile d’ambiente non caricata nella shell corrente. Un 413 indica che il file supera i 48 MB consentiti e si verifica al caricamento, non durante la gestione.

Punti chiave

  • GET /v1/files elenca tutti i tuoi file con i relativi metadati
  • GET /v1/files/{id} recupera un file specifico
  • DELETE /v1/files/{id} elimina definitivamente un file
  • Assegna nomi espliciti ai file per facilitarne la gestione
  • Verifica le dipendenze (collezioni, flussi di lavoro) prima di eliminare