Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Halda oma faile: loetle, laadi alla, kustuta

Õppetund 3 / 16 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Mis juhtub pärast sajandat üleslaadimist
  2. Tee inventuur
  3. Kontrolli konkreetset faili
  4. Kustutamine ja mida enne kontrollida
  5. Hoia oma salvestusruum puhtana
  6. Peamised punktid

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:

  1. Loetle oma failid käsuga GET /v1/files
  2. Tuvasta mittekasutatavad failid loomiskuupäeva või nime põhjal
  3. 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/files loetleb kõik sinu failid koos nende metaandmetega
  • GET /v1/files/{id} toob välja konkreetse faili
  • DELETE /v1/files/{id} kustutab faili jäädavalt
  • Nimeta oma failid selgelt, et haldust lihtsustada
  • Enne kustutamist kontrolli sõltuvusi (kollektsioonid, töövood)