Tvarkykite savo failus: sąrašas, gavimas, šalinimas
Šiame puslapyje
Kas nutinka po šimtojo įkėlimo
Failo įkėlimas trunka tris sekundes, tačiau prieš šešias savaites įkeltos failo paieška užtrunka daug ilgiau, jei iš anksto nesuplanavote savo veiksmų. Po pradinių testų paskyroje kaupiasi dešimtys, o vėliau ir šimtai dokumentų. Kai kurie iš jų yra pasenę, kiti dubliuojasi, o dar kiti yra naudojami vis dar veikiančių programų. „Files API“ suteikia tris operacijas šiam inventoriui tvarkyti: sąrašo sudarymą, gavimą ir šalinimą. Kol apimtys mažos, jos gali atrodyti antraeilės, tačiau vėliau tampa nepakeičiamos.
Inventorizacija
GET /v1/files grąžina visus į jūsų paskyrą įkeltus failus:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Atsakymas yra puslapiuojamas sąrašas, kuriame kiekvienas įrašas kartoja įkėlimo metu matytus metaduomenis:
{
"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 vaizdas išsprendžia tris labai konkrečias situacijas: atkuriate file_id, kurio neišsaugojote įkėlimo metu; patikrinate faktinį dokumento, kuris atrodo neįprastai didelis, dydį; ir nustatote kandidatus šalinimui rūšiuodami pagal created_at. Tai taip pat vienintelė vieta, kur vienu žvilgsniu pamatysite, kad ta pati ataskaita buvo išsiųsta tris kartus trimis skirtingais pavadinimais.
Konkrečio failo patikrinimas
Kai jau žinote identifikatorių, GET /v1/files/{file_id} užklausa vieną konkretų dokumentą:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Gaunate tą pačią informaciją, kurią matėte įkeldami: identifikatorių, pavadinimą, dydį, sukūrimo datą ir paskirtį. Naudingiausias šio kvietimo būdas yra prevencinis. Prieš paleisdami procesą, kuris naudoja jūsų duomenų bazėje ilgą laiką saugomą file_id, keliomis milisekundėmis trunkantis patikrinimas apsaugo jus nuo klaidos mokamų užklausų grandinės viduryje.
Šalinimas ir ką reikia patikrinti prieš tai
Šalinimas atliekamas naudojant DELETE /v1/files/{file_id}, o atsakymas patvirtina operaciją:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Prieš spaudžiant gaiduką būtina atlikti du patikrinimus. Pirma, failas gali būti nurodytas kolekcijoje – šią sąvoką detaliai nagrinėsime kitose pamokose. Ištrynus jį per „Files API“, jis automatiškai nepašalinamas iš kolekcijos, todėl jūsų indekse lieka negaliojanti nuoroda: pirmiausia pašalinkite jį iš kolekcijos, tik tada iš saugyklos. Antra, failas gali būti naudojamas aktyviuose darbo eigose; bet kuri programa, savo duomenų bazėje turinti šį file_id, gaus klaidas iškart po ištrynimo, dažnai gamybinėje aplinkoje ir retai tuo metu, kai stebite žurnalus.
Išlaikykite savo saugyklą švarią
Pavadinimų suteikimas yra jūsų pirmoji valdymo priemonė, nes originalus pavadinimas išsaugomas metaduomenyse ir yra vienintelis skaitomas žymeklis šimto įrašų sąraše. rapport-q1-2026.pdf jums ką nors reikš ir po aštuonių mėnesių; document.pdf – niekada. Tas pats pasakytina apie api-specs-v2.json lyginant su data.json. Padarykite tai įpročiu ruošdami failą savo diske, o ne įkėlimo metu: būtent vietinis pavadinimas yra perduodamas.
Įkelti failai saugomi neribotą laiką, be automatinio galiojimo pabaigos. Ketvirtinė valymo rutina yra pakankama, kad išvengtumėte nukrypimų, ir ją sudaro trys žingsniai:
- Sudarykite savo failų sąrašą naudodami
GET /v1/files - Nustatykite nenaudojamus failus pagal sukūrimo datą arba pavadinimą
- Ištrinkite juos naudodami
DELETE /v1/files/{file_id}
Šių operacijų metu pasitaiko trys klaidų kodai, kuriuos galima nedelsiant diagnozuoti. 404 rodo, kad failas neegzistuoja arba jau buvo ištrintas – tai tipiškas atvejis, kai valymo scenarijus paleidžiamas du kartus. 401 kyla dėl trūkstamo arba neteisingo API rakto, dažnai tai būna aplinkos kintamasis, neįkeltas į dabartinę apvalkalą (shell). 413 rodo, kad failas viršija leidžiamą 48 MB ribą, ir tai įvyksta įkėlimo metu, o ne valdymo fazėje.
Svarbiausi punktai
GET /v1/filespateikia visų jūsų failų sąrašą su jų metaduomenimisGET /v1/files/{id}gauna konkretų failąDELETE /v1/files/{id}visam laikui ištrina failą- Suteikite failams aiškius pavadinimus, kad palengvintumėte jų valdymą
- Prieš šalindami patikrinkite priklausomybes (kolekcijas, darbo eigas)