Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Upravljajte svoje datoteke: izpis, pridobivanje, brisanje

Lekcija 3 od 16 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Kaj se zgodi po stoti nalaganju
  2. Naredite inventuro
  3. Preverite določeno datoteko
  4. Brisanje in kaj preveriti pred tem
  5. Ohranite svojo shrambo čisto
  6. Ključne ugotovitve

Kaj se zgodi po stoti nalaganju

Nalaganje datoteke traja tri sekunde; iskanje tiste, ki ste jo poslali pred šestimi tedni, pa traja veliko dlje, če niste načrtovali vnaprej. Po začetnih testih račun nabere ducate, nato pa stotine dokumentov. Nekateri so zastareli, drugi podvojeni, tretje pa še vedno uporabljajo delujoče aplikacije. API za datoteke (Files API) ponuja tri operacije za upravljanje tega inventarja: izpis, pridobivanje in brisanje. Dokler je količina majhna, se zdijo drugotne, kasneje pa postanejo nepogrešljive.

Naredite inventuro

GET /v1/files vrne vse datoteke, naložene v vaš račun:

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

Odgovor je oštevilčen seznam, kjer vsak vnos ponavlja metapodatke, vidne ob nalaganju:

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

Ta pogled rešuje tri zelo konkretne situacije: pridobitev file_id, ki ga ob nalaganju niste shranili, preverjanje dejanske velikosti dokumenta, ki se zdi nenormalno težak, in prepoznavanje kandidatov za brisanje s razvrščanjem po created_at. To je tudi edino mesto, kjer boste na prvi pogled videli, da je bilo isto poročilo poslano trikrat pod tremi različnimi imeni.

Preverite določeno datoteko

Ko že poznate identifikator, poizvedba GET /v1/files/{file_id} pridobi posamezen dokument:

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

Pridobite iste informacije kot ob nalaganju: identifikator, ime, velikost, datum ustvarjanja in namen. Najkoristnejša uporaba tega klica je obrambna narava. Preden zaženete proces, ki se sklicuje na file_id, dolgo shranjen v vaši zbirki podatkov, vas preverjanje, ki traja nekaj milisekund, obvaruje pred napako sredi verige zaračunanih zahtevkov.

Brisanje in kaj preveriti pred tem

Brisanje poteka z DELETE /v1/files/{file_id}, odgovor pa operacijo potrdi:

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

Preden pritisnete sprožilec, sta potrebni dve preverjanji. Prvič, datoteka je lahko referencirana v zbirki (kolekciji) – koncept, ki ga bomo podrobneje opisali v prihajajočih lekcijah. Če jo izbrišete prek API-ja za datoteke, se samodejno ne odstrani iz zbirke, kar pusti v vašem indeksu mrtvo referenco: najprej jo odstranite iz zbirke, šele nato iz shrambe. Drugič, datoteko lahko uporabljajo aktivni delovni tokovi; vsaka aplikacija, ki ima ta file_id v svoji zbirki podatkov, bo takoj po brisanju prejela napake, pogosto v proizvodnem okolju in redko medtem, ko spremljate dnevnike.

Ohranite svojo shrambo čisto

Poimenovanje je vaše prvo orodje za upravljanje, saj se prvotno ime ohrani v metapodatkih in predstavlja edino berljivo oznako na seznamu sto vnosov. rapport-q1-2026.pdf vam bo čez osem mesecev nekaj pomenilo; document.pdf vam nikoli ne bo. Enako razmišljanje velja za api-specs-v2.json v nasprotju z data.json. Naj vam to postane navada, ko datoteko pripravljate na svojem disku, ne šele ob nalaganju: preneseno je lokalno ime.

Naložene datoteke ostanejo shranjene nedoločen čas, brez samodejnega poteka. Četrtletni postopek čiščenja zadostuje za preprečevanje odstopanj, in sicer v treh korakih:

  1. Izpišite svoje datoteke z GET /v1/files
  2. Identificirajte tiste, ki se ne uporabljajo več, glede na datum ustvarjanja ali ime
  3. Izbrišite jih z DELETE /v1/files/{file_id}

Pri teh operacijah se pojavijo tri kode napak, ki jih je mogoče takoj diagnosticirati. 404 signalizira neobstoječo ali že izbrisano datoteko, kar je tipičen primer dvakrat zagnanega skripta za čiščenje. 401 izvira iz manjkajočega ali neveljavnega ključa API, pogosto zaradi spremenljivke okolja, ki ni naložena v trenutni lupini. 413 kaže, da datoteka presega dovoljenih 48 MB, kar se zgodi ob nalaganju, ne med upravljanjem.

Ključne ugotovitve

  • GET /v1/files izpiše vse vaše datoteke z njihovimi metapodatki
  • GET /v1/files/{id} pridobi določeno datoteko
  • DELETE /v1/files/{id} trajno izbriše datoteko
  • Datoteke poimenujte eksplicitno, da olajšate upravljanje
  • Pred brisanjem preverite odvisnosti (zbirke, delovne tokove)