Salt la conținutul principal
Română— Alege o limbă
Meniu

Gestionarea fișierelor: listare, preluare, ștergere

Lecția 3 din 16 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Ce se întâmplă după al o sutalea încărcare
  2. Realizarea inventarului
  3. Verificarea unui fișier specific
  4. Ștergerea și ce trebuie verificat înainte
  5. Menținerea curățeniei în stocare
  6. Puncte cheie

Ce se întâmplă după al o sutalea încărcare

Încărcarea unui fișier durează trei secunde; găsirea celui trimis acum șase săptămâni durează mult mai mult dacă nu ați planificat din timp. După testele inițiale, un cont acumulează zeci, apoi sute de documente. Unele sunt învechite, altele sunt duplicate, iar altele sunt referențiate de aplicații care rulează încă. Files API expune trei operațiuni pentru gestionarea acestui inventar: listare, preluare și ștergere. Acestea par secundare cât timp volumul este redus, dar devin indispensabile ulterior.

Realizarea inventarului

GET /v1/files returnează toate fișierele încărcate în contul dumneavoastră:

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

Răspunsul este o listă paginată, fiecare intrare repetând metadatele văzute la încărcare:

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

Această vizualizare rezolvă trei situații foarte concrete: recuperarea unui file_id pe care nu l-ați salvat la momentul încărcării, verificarea dimensiunii reale a unui document care pare anormal de greu și identificarea candidaților pentru ștergere prin sortarea după created_at. Este, de asemenea, singurul loc unde puteți vedea dintr-o privire că același raport a fost trimis de trei ori sub trei nume diferite.

Verificarea unui fișier specific

Atunci când cunoașteți deja identificatorul, GET /v1/files/{file_id} interoghează un singur document:

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

Preluați aceleași informații ca la încărcare: identificator, nume, dimensiune, data creării și scopul. Cel mai util caz de utilizare al acestui apel este cel defensiv. Înainte de a lansa un proces care face referire la un file_id stocat de mult timp în baza de date, o verificare ce durează câteva milisecunde vă scutește de o eroare în mijlocul unui lanț de cereri facturate.

Ștergerea și ce trebuie verificat înainte

Ștergerea se face cu DELETE /v1/files/{file_id}, iar răspunsul confirmă operațiunea:

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

Sunt necesare două verificări înainte de a apăsa pe trăgaci. În primul rând, fișierul poate fi referențiat într-o colecție – un concept pe care îl vom detalia în lecțiile următoare. Ștergerea acestuia prin Files API nu îl elimină automat din colecție, lăsându-vă cu o referință moartă în index: eliminați-l mai întâi din colecție, apoi din stocare. În al doilea rând, fișierul poate fi utilizat de fluxuri de lucru active; orice aplicație care păstrează acest file_id în baza sa de date va primi erori imediat după efectuarea ștergerii, adesea în producție și rareori în timp ce monitorizați jurnalele.

Menținerea curățeniei în stocare

Denumirea este primul dumneavoastră instrument de gestionare, deoarece numele original este păstrat în metadate și constituie singurul marker lizibil într-o listă de o sută de intrări. rapport-q1-2026.pdf va însemna ceva pentru dumneavoastră peste opt luni; document.pdf nu va însemna niciodată nimic. Același raționament se aplică pentru api-specs-v2.json față de data.json. Faceți din aceasta un obicei atunci când pregătiți fișierul pe discul local, nu la momentul încărcării: numele local este cel transmis.

Fișierele încărcate rămân stocate la nesfârșit, fără expirare automată. O rutină trimestrială de curățare este suficientă pentru a evita derivarea, în trei pași:

  1. Listați fișierele cu GET /v1/files
  2. Identificați-le pe cele care nu mai sunt utilizate, după data creării sau nume
  3. Ștergeți-le cu DELETE /v1/files/{file_id}

Trei coduri de eroare apar în aceste operațiuni și sunt diagnosticate imediat. Un 404 semnalează un fișier inexistent sau deja șters, un caz tipic al unui script de curățare rulat de două ori. Un 401 provine dintr-o cheie API lipsă sau invalidă, adesea o variabilă de mediu neîncărcată în shell-ul curent. Un 413 indică faptul că fișierul depășește limita permisă de 48 MB și apare la încărcare, nu în timpul gestionării.

Puncte cheie

  • GET /v1/files listează toate fișierele dumneavoastră cu metadatele lor
  • GET /v1/files/{id} preia un fișier specific
  • DELETE /v1/files/{id} șterge permanent un fișier
  • Denumiți fișierele în mod explicit pentru a facilita gestionarea
  • Verificați dependențele (colecții, fluxuri de lucru) înainte de ștergere