Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Spravujte své soubory: výpis, získání, smazání

Lekce 3 z 16 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Co se děje po stovce nahraných souborů
  2. Proveďte inventuru
  3. Ověření konkrétního souboru
  4. Smazání a co zkontrolovat předem
  5. Udržujte své úložiště čisté
  6. Klíčové poznatky

Co se děje po stovce nahraných souborů

Nahrání souboru trvá tři sekundy; nalezení toho, který jste odeslali před šesti týdny, zabere mnohem více času, pokud jste to předem neplánovali. Po počátečních testech se na účtu hromadí desítky a poté stovky dokumentů. Některé jsou zastaralé, jiné duplicitní a další jsou stále využívány běžícími aplikacemi. Files API nabízí tři operace pro správu tohoto inventáře: výpis, získání a smazání. Zatímco je objem nízký, zdají se být druhořadé, ale později se stanou nepostradatelnými.

Proveďte inventuru

GET /v1/files vrátí všechny soubory nahrané na váš účet:

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

Odpovědí je stránkovaný seznam, kde každá položka opakuje metadata viděná při nahrávání:

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

Tento pohled řeší tři velmi konkrétní situace: získání file_id, které jste si při nahrávání neuložili, ověření skutečné velikosti dokumentu, který se zdá abnormálně velký, a identifikaci kandidátů ke smazání seřazením podle created_at. Je to také jediné místo, kde na první pohled uvidíte, že stejná zpráva byla odeslána třikrát pod třemi různými názvy.

Ověření konkrétního souboru

Pokud již znáte identifikátor, GET /v1/files/{file_id} dotazuje jediný dokument:

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

Získáte stejné informace jako při nahrávání: identifikátor, název, velikost, datum vytvoření a účel. Nejužitečnějším využitím tohoto volání je prevence chyb. Před spuštěním procesu, který odkazuje na file_id dlouhodobě uložený ve vaší databázi, vás kontrola trvající několik milisekund ušetří chyby uprostřed řetězce zpoplatněných požadavků.

Smazání a co zkontrolovat předem

Smazání se provádí pomocí DELETE /v1/files/{file_id} a odpověď operaci potvrzuje:

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

Před stiskem spouště jsou nutné dvě kontroly. Zaprvé, soubor může být odkazován v kolekci – koncept, který podrobně rozebereme v nadcházejících lekcích. Jeho smazání přes Files API jej automaticky neodstraní z kolekce, což ve vašem indexu zanechá nefunkční odkaz: nejprve jej odstraňte z kolekce a až poté z úložiště. Zadruhé, soubor může být využíván aktivními pracovními postupy; jakákoli aplikace, která má toto file_id ve své databázi, začne ihned po smazání dostávat chyby, často v produkčním prostředí a zřídka v době, kdy sledujete logy.

Udržujte své úložiště čisté

Pojmenovávání je vaším prvním nástrojem pro správu, protože původní název zůstává v metadatech a představuje jediný čitelný marker v seznamu stovek položek. rapport-q1-2026.pdf vám bude něco říkat i za osm měsíců; document.pdf nikdy. Stejná logika platí pro api-specs-v2.json oproti data.json. Udělejte z toho zvyk při přípravě souboru na disku, nikoliv až v době nahrávání: přenáší se totiž lokální název.

Nahrané soubory zůstávají uloženy na dobu neurčitou bez automatického vypršení platnosti. Čtvrtletní rutina čištění stačí k tomu, aby se věci nevymkly kontrole, a to ve třech krocích:

  1. Vypište své soubory pomocí GET /v1/files
  2. Identifikujte ty, které se již nepoužívají, podle data vytvoření nebo názvu
  3. Smažte je pomocí DELETE /v1/files/{file_id}

Při těchto operacích se vyskytují tři chybové kódy, které lze okamžitě diagnostikovat. 404 signalizuje neexistující nebo již smazaný soubor, což je typický případ spuštění čistícího skriptu dvakrát. 401 vzniká kvůli chybějícímu nebo neplatnému API klíči, často jde o proměnnou prostředí, která není v aktuálním shellu načtena. 413 indikuje, že soubor překračuje povolených 48 MB, k čemuž dochází při nahrávání, nikoliv během správy.

Klíčové poznatky

  • GET /v1/files vypíše všechny vaše soubory s jejich metadaty
  • GET /v1/files/{id} získá konkrétní soubor
  • DELETE /v1/files/{id} trvale smaže soubor
  • Pojmenovávejte soubory explicitně pro usnadnění správy
  • Před smazáním zkontrolujte závislosti (kolekce, pracovní postupy)