Halda oma faile: loetle, laadi alla, kustuta
Sellel lehel
Mis juhtub pärast sajandat üleslaadimist
Faili üleslaadimine võtab kolm sekundit; kuus nädalat tagasi saadetud faili leidmine võtab palju kauem aega, kui sa pole ette planeerinud. Pärast esialgseid teste koguneb kontole kümneid ja seejärel sadu dokumente. Mõned on iganenud, teised dubleeritud ja kolmandaid kasutavad endiselt töötavad rakendused. Files API pakub selle inventuuri haldamiseks kolme toimingut: loetlemine, päring ja kustutamine. Kui maht on väike, tunduvad need teisejärgulised, kuid hiljem muutuvad hädavajalikuks.
Tee inventuur
GET /v1/files tagastab kõik sinu kontole üles laaditud failid:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Vastus on lehekülgedeks jagatud loend, kus iga kirje kordab üleslaadimisel nähtud metaandmeid:
{
"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"
}
]
}
See vaade lahendab kolm väga konkreetset olukorda: taastad file_id, mida sa üleslaadimise ajal ei salvestanud; kontrollid dokumendi tegelikku suurust, mis tundub ebanormaalselt mahukas; ja tuvastad kustutamiskandidaadid, sorteerides tulemused välja created_at järgi. See on ka ainus koht, kus näed esmapilgul, et sama aruanne saadeti kolm korda kolme erineva nime all.
Kontrolli konkreetset faili
Kui identifikaator on juba teada, päring GET /v1/files/{file_id} toob välja ühe kindla dokumendi:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Saad sama teabe, mis üleslaadimisel: identifikaator, nimi, suurus, loomiskuupäev ja otstarve. Selle päringu kõige kasulikum rakendus on ennetav. Enne protsessi käivitamist, mis viitab sinu andmebaasis pikka aega hoitud file_id-le, säästab mõni millisekund kestev kontroll sind veast keset tasuliste päringute ahelat.
Kustutamine ja mida enne kontrollida
Kustutamine toimub käsuga DELETE /v1/files/{file_id} ja vastus kinnitab toimingu:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Enne päästiku vajutamist on vaja teha kaks kontrolli. Esiteks võib fail olla viidatud kollektsioonis – mõiste, mida lähitundides täpsemalt käsitleme. Selle kustutamine Files API kaudu ei eemalda seda automaatselt kollektsioonist, jättes sinu indeksisse surnud viite: eemalda see kõigepealt kollektsioonist ja alles seejärel salvestusruumist. Teiseks võib faili kasutada aktiivsed töövood; iga rakendus, mis hoiab seda file_id-d oma andmebaasis, saab niipea, kui kustutamine on tehtud, veateateid. See juhtub sageli tootmiskeskkonnas ja harva ajal, kui sa parajasti logisid jälgid.
Hoia oma salvestusruum puhtana
Nimetus on sinu esimene haldusvahend, sest algne nimi säilib metaandmetes ja moodustab ainsa loetava markeri sajast kirjest koosnevas loendis. rapport-q1-2026.pdf ütleb sulle kaheksa kuu pärast midagi; document.pdf mitte kunagi. Sama loogika kehtib paaride api-specs-v2.json versus data.json puhul. Tee sellest harjumus faili oma kettal ette valmistades, mitte üleslaadimise hetkel: edasi saadetakse just kohalik nimi.
Üles laaditud failid jäävad määramata ajaks salvestatuks, automaatset aegumist ei ole. Kvartaalne puhastusrutiin on piisav, et vältida mahukuse kasvu, ja koosneb kolmest sammust:
- Loetle oma failid käsuga
GET /v1/files - Tuvasta mittekasutatavad failid loomiskuupäeva või nime põhjal
- Kustuta need käsuga
DELETE /v1/files/{file_id}
Nendes toimingutes tuleb ette kolm veakoodi, mida on lihtne diagnoosida. 404 annab märku olematust või juba kustutatud failist, mis on tüüpiline juhtum, kui puhastusskripti on käivitatud kaks korda. 401 tuleneb puuduvast või vigasest API-võtmest, sageli on tegu keskkonnamuutujaga, mida praeguses shellis ei laaditud. 413 näitab, et fail ületab lubatud 48 MB piiri, ja see tekib üleslaadimisel, mitte haldamise käigus.
Peamised punktid
GET /v1/filesloetleb kõik sinu failid koos nende metaandmetegaGET /v1/files/{id}toob välja konkreetse failiDELETE /v1/files/{id}kustutab faili jäädavalt- Nimeta oma failid selgelt, et haldust lihtsustada
- Enne kustutamist kontrolli sõltuvusi (kollektsioonid, töövood)