Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Hallinnoi tiedostojasi: listaa, nouda, poista

Oppitunti 3 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Mitä tapahtuu sadannen latauksen jälkeen
  2. Tee inventaario
  3. Varmista tietty tiedosto
  4. Poista ja mitä tarkistaa ennen sitä
  5. Pidä tallennustilasi siistinä
  6. Keskeiset asiat

Mitä tapahtuu sadannen latauksen jälkeen

Tiedoston lataaminen kestää kolme sekuntia; kuusi viikkoa sitten lähettämäsi tiedoston löytäminen vie paljon kauemmin, jos et ole suunnitellut asiaa etukäteen. Alkuvaiheen testien jälkeen tilille kertyy kymmeniä ja sitten satoja dokumentteja. Osa on vanhentuneita, osa on kaksoiskappaleita ja osaa käyttävät edelleen käynnissä olevat sovellukset. Files API tarjoaa kolme operaatiota tämän varaston hallintaan: listaus, nouto ja poisto. Ne vaikuttavat toissijaisilta volyymin ollessa pieni, mutta muuttuvat myöhemmin välttämättömiksi.

Tee inventaario

GET /v1/files palauttaa kaikki tilillesi ladatut tiedostot:

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

Vastaus on sivutettu lista, jossa jokainen merkintä toistaa lataushetkellä nähdyn metatiedon:

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

Tämä näkymä ratkaisee kolme hyvin konkreettista tilannetta: sellaisen file_id:n etsimisen, jota et tallentanut latausvaiheessa, epänormaalin raskaalta vaikuttavan dokumentin todellisen koon tarkistamisen ja poistokohteiden tunnistamisen lajittelemalla tulokset created_at-kentän perusteella. Se on myös ainoa paikka, jossa näet yhdellä silmäyksellä, että sama raportti on lähetetty kolme kertaa kolmella eri nimellä.

Varmista tietty tiedosto

Kun tunnistat tunnisteet ennestään, GET /v1/files/{file_id} hakee yksittäisen dokumentin:

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

Saat samat tiedot kuin latauksen yhteydessä: tunnisteen, nimen, koon, luontipäivämäärän ja käyttötarkoituksen. Tämän kutsun hyödyllisin käyttötapa on puolustava. Ennen kuin käynnistät prosessin, joka viittaa tietokantaasi pitkään säilytettyyn file_id:hen, muutama millisekunti kestävä tarkistus säästää sinut virheeltä laskutettujen pyyntöjen ketjun keskellä.

Poista ja mitä tarkistaa ennen sitä

Poisto suoritetaan komennolla DELETE /v1/files/{file_id} ja vastaus vahvistaa operaation:

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

Ennen liipaisimen vetämistä tarvitaan kaksi tarkistusta. Ensinnäkin tiedosto voi olla viitattuna kokoelmaan – käsitteeseen, jota tarkastelemme yksityiskohtaisesti tulevissa oppitunneissa. Sen poistaminen Files API:n kautta ei poista sitä automaattisesti kokoelmasta, jolloin indeksiisi jää kuollut viittaus: poista se ensin kokoelmasta ja vasta sitten tallennustilasta. Toiseksi tiedostoa voivat käyttää aktiiviset työkulut; mikä tahansa sovellus, joka pitää tätä file_id:tä tietokannassaan, saa virheitä heti poiston suorittamisen jälkeen, usein tuotantoympäristössä ja harvoin silloin, kun valvot lokeja.

Pidä tallennustilasi siistinä

Nimeäminen on ensimmäinen hallintatyökalusi, sillä alkuperäinen nimi säilyy metatiedoissa ja muodostaa ainoan luettavan merkin sadan merkinnän listalla. rapport-q1-2026.pdf merkitsee sinulle jotain kahdeksan kuukauden kuluttua; document.pdf ei koskaan. Sama päättely pätee tiedostoihin api-specs-v2.json versus data.json. Tee tästä tapa valmistellessasi tiedostoa levylläsi, älä latausvaiheessa: paikallinen nimi on se, joka välitetään eteenpäin.

Ladatut tiedostot pysyvät tallennettuina toistaiseksi ilman automaattista vanhenemista. Neljännesvuosittainen siivousrutiini riittää estämään ajautumisen, ja se etenee kolmessa vaiheessa:

  1. Listaa tiedostosi komennolla GET /v1/files
  2. Tunnista käyttämättömät tiedostot luontipäivämäärän tai nimen perusteella
  3. Poista ne komennolla DELETE /v1/files/{file_id}

Näissä operaatioissa tulee vastaan kolme virhekoodia, jotka diagnosoidaan välittömästi. 404 ilmoittaa olemattomasta tai jo poistetusta tiedostosta, mikä on tyypillistä kahdesti ajetulle siivousskriptille. 401 johtuu puuttuvasta tai virheellisestä API-avaimesta, usein kyse on ympäristömuuttujasta, jota ei ole ladattu nykyiseen shelliin. 413 kertoo tiedoston ylittävän sallitun 48 Mt:n rajan ja esiintyy latausvaiheessa, ei hallinnan aikana.

Keskeiset asiat

  • GET /v1/files listaa kaikki tiedostosi niiden metatietoineen
  • GET /v1/files/{id} noutaa tietyn tiedoston
  • DELETE /v1/files/{id} poistaa tiedoston pysyvästi
  • Nimeä tiedostosi eksplisiittisesti hallinnan helpottamiseksi
  • Tarkista riippuvuudet (kokoelmat, työkulut) ennen poistamista