Pārvaldi savus failus: saraksts, izgūšana, dzēšana
Šajā lapā
Kas notiek pēc simtās augšupielādes
Faila augšupielāde aizņem trīs sekundes; tā atrašana, kuru nosūtīji pirms sešām nedēļām, prasa daudz vairāk laika, ja neesi to iepriekš ieplānojis. Pēc sākotnējiem testiem kontā uzkrājas desmitiem, tad simtiem dokumentu. Daži ir novecojuši, citi dublēti, bet vēl citus joprojām izmanto darbojošās lietotnes. Files API piedāvā trīs operācijas šī inventāra pārvaldībai: saraksta iegūšanu, konkrēta faila izgūšanu un dzēšanu. Kamēr apjoms ir mazs, tās šķiet sekundāras, taču vēlāk kļūst neatņemamas.
Veic inventarizāciju
GET /v1/files atgriež visus tavā kontā augšupielādētos failus:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Atbilde ir lapots saraksts, kurā katra ieraksta metadati atkārto augšupielādes brīdī redzēto informāciju:
{
"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"
}
]
}
Šis skats atrisina trīs ļoti konkrētas situācijas: file_id atgūšanu, ja to neesi saglabājis augšupielādes brīdī, dokumenta faktiskā izmēra pārbaudi, ja tas šķiet neparasti liels, un dzēšanai paredzēto failu noteikšanu, kārtojot pēc created_at. Tā ir arī vienīgā vieta, kur uzreiz redzēsi, ka viens un tas pats pārskats nosūtīts trīs reizes ar trim dažādiem nosaukumiem.
Pārbaudi konkrētu failu
Ja identifikators jau ir zināms, GET /v1/files/{file_id} pieprasa vienu konkrētu dokumentu:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Tu saņem to pašu informāciju, kas bija pieejama augšupielādes brīdī: identifikatoru, nosaukumu, izmēru, izveides datumu un mērķi. Visnoderīgākais šī izsaukuma pielietojums ir preventīvs. Pirms palaid procesu, kas izmanto file_id, kurš ilgstoši glabāts tavā datubāzē, dažas milisekundes ilga pārbaude pasargā tevi no kļūdas vidū ķēdes, par kuru tiek iekasēta maksa.
Dzēšana un ko pārbaudīt pirms tās
Dzēšanu veic ar DELETE /v1/files/{file_id}, un atbilde apstiprina operāciju:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Pirms sprūda nospiešanas nepieciešamas divas pārbaudes. Pirmkārt, fails var būt atsaukts kolekcijā — jēdzienu, ko detalizēti aplūkosim nākamajās nodarbībās. Tā dzēšana, izmantojot Files API, automātiski to neizņem no kolekcijas, atstājot tev mirušu atsauces saiti indeksā: vispirms izņem to no kolekcijas, tad no krātuves. Otrkārt, fails var tikt izmantots aktīvos darba plūsmas procesos; jebkura lietotne, kas saglabājusi šo file_id savā datubāzē, saņems kļūdas tūlīt pēc dzēšanas veikšanas, bieži vien ražošanas vidē un reti brīdī, kad tu uzraugi žurnālus.
Uzturi savu krātuvi tīru
Nosaukumu došana ir tavs pirmais pārvaldības rīks, jo sākotnējais nosaukums tiek saglabāts metadatos un veido vienīgo lasāmo marķieri simtu ierakstu sarakstā. rapport-q1-2026.pdf tev nozīmēs kaut ko arī pēc astoņiem mēnešiem; document.pdf — nekad. Tas pats attiecas uz api-specs-v2.json salīdzinājumā ar data.json. Iepazīstini sevi ar šo ieradumu, sagatavojot failu savā diskā, nevis augšupielādes brīdī: tieši lokālais nosaukums tiek pārsūtīts.
Augšupielādētie faili tiek glabāti beztermiņa, bez automātiskas dzēšanas. Ceturkšņa tīrīšanas rutīna ir pietiekama, lai novērstu novirzes, un tā sastāv no trim soļiem:
- Iegūsti savu failu sarakstu ar
GET /v1/files - Identificē tos, kas vairs netiek izmantoti, pēc izveides datuma vai nosaukuma
- Dzēs tos ar
DELETE /v1/files/{file_id}
Šajās operācijās bieži rodas trīs kļūdu kodi, kurus var diagnosticēt uzreiz. 404 norāda uz neesošu vai jau dzēstu failu, kas ir tipisks gadījums, ja tīrīšanas skripts palaists divreiz. 401 rodas, ja trūkst API atslēgas vai tā ir nederīga, bieži vien tāpēc, ka vides mainīgais nav ielādēts pašreizējā čaulā. 413 norāda, ka fails pārsniedz atļauto 48 MB robežu, un tas notiek augšupielādes brīdī, nevis pārvaldības procesā.
Galvenās atziņas
GET /v1/filesparāda visu tavu failu sarakstu ar to metadatiemGET /v1/files/{id}izgūst konkrētu failuDELETE /v1/files/{id}neatgriezeniski dzēš failu- Dod failiem skaidrus nosaukumus, lai atvieglotu to pārvaldību
- Pirms dzēšanas pārbaudi atkarības (kolekcijas, darba plūsmas)