Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Tvarkykite savo failus: sąrašas, gavimas, šalinimas

Paskaita 3 iš 16 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Kas nutinka po šimtojo įkėlimo
  2. Inventorizacija
  3. Konkrečio failo patikrinimas
  4. Šalinimas ir ką reikia patikrinti prieš tai
  5. Išlaikykite savo saugyklą švarią
  6. Svarbiausi punktai

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:

  1. Sudarykite savo failų sąrašą naudodami GET /v1/files
  2. Nustatykite nenaudojamus failus pagal sukūrimo datą arba pavadinimą
  3. 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/files pateikia visų jūsų failų sąrašą su jų metaduomenimis
  • GET /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)