Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Fájljaid kezelése: listázás, lekérés, törlés

3. lecke 16 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Mi történik a századik feltöltés után
  2. Leltárkészítés
  3. Egy adott fájl ellenőrzése
  4. Törlés, és mit ellenőrizz előtte
  5. Tartsd tisztán a tárhelyedet
  6. Főbb megállapítások

Mi történik a századik feltöltés után

Egy fájl feltöltése három másodpercet vesz igénybe; annak a fájlnak a megtalálása, amit hat hete küldtél el, sokkal tovább tart, ha nem terveztél előre. A kezdeti tesztek után a fiókodban tucatnyi, majd száznyi dokumentum gyűlik össze. Egyesek elavultak, mások duplikáltak, megint másokat pedig még mindig futó alkalmazások hivatkoznak. A Files API három műveletet tesz elérhetővé ezen leltár kezelésére: listázás, lekérés és törlés. Alacsony mennyiség mellett ezek másodlagosnak tűnhetnek, de később nélkülözhetetlenné válnak.

Leltárkészítés

A GET /v1/files endpoint visszaadja a fiókodba feltöltött összes fájlt:

curl https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY"

A válasz egy lapozott lista, ahol minden bejegyzés megismétli a feltöltéskor látott metaadatokat:

{
  "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"
    }
  ]
}

Ez a nézet három nagyon konkrét helyzetet old meg: egy olyan file_id visszakeresését, amit feltöltéskor nem mentettél el; egy gyanúsan nagy méretű dokumentum tényleges méretének ellenőrzését; valamint a törlésre jelöltek azonosítását a created_at mező szerinti rendezéssel. Ez az egyetlen hely, ahol egy pillantással láthatod, hogy ugyanazt a jelentést három különböző néven küldted el háromszor.

Egy adott fájl ellenőrzése

Ha már ismered az azonosítót, a GET /v1/files/{file_id} lekérdez egy egyetlen dokumentumot:

curl https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

Ugyanazokat az információkat kapod vissza, mint feltöltéskor: azonosító, név, méret, létrehozás dátuma és cél. Ennek a hívásnak a leghasznosabb felhasználása a megelőzés. Mielőtt elindítanál egy folyamatot, amely egy régóta az adatbázisodban tárolt file_id-ra hivatkozik, egy néhány milliszekundumig tartó ellenőrzés megvéd attól, hogy hiba csússzon a számlázott kérések láncolatának közepébe.

Törlés, és mit ellenőrizz előtte

A törlést a DELETE /v1/files/{file_id} végzi, a válasz pedig megerősíti a műveletet:

curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"
{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

Két ellenőrzés kötelező, mielőtt meghúznád a ravaszt. Először is, a fájl hivatkozhat egy kollekcióra – ezt a fogalmat a következő leckékben részletezzük. Ha a Files API-n keresztül törlöd, az nem távolítja el automatikusan a kollekcióból, így halott hivatkozást hagysz az indexben: először távolítsd el a kollekcióból, majd csak utána a tárolóból. Másodszor, a fájlt aktív munkafolyamatok is használhatják; bármely alkalmazás, amely ezt a file_id-t tartja nyilván az adatbázisában, hibákat fog kapni a törlés végrehajtása után, gyakran éles környezetben és ritkán akkor, amikor éppen a naplókat figyeled.

Tartsd tisztán a tárhelyedet

A nevezés az első kezelési eszközöd, mert az eredeti név megmarad a metaadatokban, és ez az egyetlen olvasható jelölő száz bejegyzés listájában. A rapport-q1-2026.pdf jelenteni fog valamit neked nyolc hónap múlva; a document.pdf soha. Ugyanez az érvelés vonatkozik az api-specs-v2.json és a data.json összehasonlítására. Szoktasd rá magad erre, amikor előkészíted a fájlt a lemezen, nem pedig feltöltéskor: a helyi név kerül továbbításra.

A feltöltött fájlok határozatlan ideig tárolva maradnak, automatikus elévülés nélkül. Egy negyedéves tisztítási rutin elegendő az elcsúszás elkerülésére, három lépésben:

  1. Listázd a fájljaidat a GET /v1/files segítségével
  2. Azonosítsd a már nem használtakat létrehozás dátuma vagy név alapján
  3. Töröld őket a DELETE /v1/files/{file_id} paranccsal

Három hibakód fordul elő gyakran ezekben a műveletekben, és azonnal diagnosztizálható. A 404 nem létező vagy már törölt fájlt jelez, ami tipikus eset, ha kétszer futtatsz le egy tisztító szkriptet. A 401 hiányzó vagy érvénytelen API-kulcsból ered, gyakran azért, mert a környezeti változó nem töltődött be az aktuális shellben. A 413 azt jelzi, hogy a fájl meghaladja a megengedett 48 MB-ot, és feltöltéskor fordul elő, nem pedig kezelés közben.

Főbb megállapítások

  • A GET /v1/files listázza az összes fájlodat a metaadataikkal együtt
  • A GET /v1/files/{id} lekér egy adott fájlt
  • A DELETE /v1/files/{id} véglegesen töröl egy fájlt
  • Nevezd el explicit módon a fájljaidat a kezelés megkönnyítése érdekében
  • Törlés előtt ellenőrizd a függőségeket (kollekciók, munkafolyamatok)