Przejdź do głównej treści
Polski— Wybierz język
Menu

Zarządzaj swoimi plikami: lista, pobieranie, usuwanie

Lekcja 3 z 16 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Co się dzieje po setnym przesłaniu
  2. Sporządź inwentarz
  3. Zweryfikuj konkretny plik
  4. Usuwanie i co sprawdzić przed naciśnięciem spustu
  5. Utrzymuj porządek w magazynie
  6. Kluczowe wnioski

Co się dzieje po setnym przesłaniu

Przesłanie pliku zajmuje trzy sekundy; znalezienie tego, który wysłałeś sześć tygodni temu, trwa znacznie dłużej, jeśli nie zaplanowałeś tego wcześniej. Po początkowych testach na koncie gromadzą się dziesiątki, a następnie setki dokumentów. Niektóre są nieaktualne, inne zduplikowane, a jeszcze inne są używane przez nadal działające aplikacje. Files API udostępnia trzy operacje do zarządzania tym zasobem: listowanie, pobieranie i usuwanie. Wydają się one drugorzędne, gdy wolumen jest niski, ale później stają się niezbędne.

Sporządź inwentarz

GET /v1/files zwraca wszystkie pliki przesłane na Twoje konto:

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

Odpowiedź to stronicowana lista, gdzie każdy wpis powtarza metadane widoczne podczas przesyłania:

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

Widok ten rozwiązuje trzy bardzo konkretne sytuacje: odzyskanie file_id, którego nie zapisałeś w momencie przesyłania, sprawdzenie rzeczywistego rozmiaru dokumentu, który wydaje się nienormalnie duży, oraz wykrycie kandydatów do usunięcia poprzez sortowanie po created_at. To również jedyne miejsce, gdzie jednym rzutem oka zobaczysz, że ten sam raport został wysłany trzy razy pod trzema różnymi nazwami.

Zweryfikuj konkretny plik

Gdy już znasz identyfikator, GET /v1/files/{file_id} odpytuje pojedynczy dokument:

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

Odzyskujesz te same informacje co przy przesyłaniu: identyfikator, nazwę, rozmiar, datę utworzenia i cel. Najbardziej przydatnym zastosowaniem tego wywołania jest działanie prewencyjne. Przed uruchomieniem procesu odwołującego się do file_id przechowywanego od dawna w Twojej bazie danych, sprawdzenie trwające kilka milisekund uchroni Cię przed błędem w środku łańcucha płatnych żądań.

Usuwanie i co sprawdzić przed naciśnięciem spustu

Usunięcia dokonuje się za pomocą DELETE /v1/files/{file_id}, a odpowiedź potwierdza operację:

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

Przed naciśnięciem spustu wymagane są dwie kontrole. Po pierwsze, plik może być referencjonowany w kolekcji – koncepcję tę szczegółowo omówimy w nadchodzących lekcjach. Usunięcie go przez Files API nie usuwa go automatycznie z kolekcji, pozostawiając martwą referencję w Twoim indeksie: najpierw usuń go z kolekcji, a następnie z magazynu. Po drugie, plik może być używany przez aktywne przepływy pracy; każda aplikacja przechowująca ten file_id w swojej bazie danych otrzyma błędy natychmiast po wykonaniu usunięcia, często w środowisku produkcyjnym i rzadko w momencie, gdy monitorujesz logi.

Utrzymuj porządek w magazynie

Nazywanie to Twoje pierwsze narzędzie zarządzania, ponieważ oryginalna nazwa jest zachowywana w metadanych i stanowi jedyny czytelny znacznik na liście stu wpisów. rapport-q1-2026.pdf będzie dla Ciebie coś znaczyć za osiem miesięcy; document.pdf – nigdy. To samo rozumowanie dotyczy api-specs-v2.json w kontraście do data.json. Wyrób sobie ten nawyk podczas przygotowywania pliku na dysku, a nie w momencie przesyłania: to nazwa lokalna jest transmitowana.

Przesłane pliki pozostają przechowywane w nieskończoność, bez automatycznego wygasania. Kwartalna rutina czyszczenia wystarczy, aby uniknąć chaosu, w trzech krokach:

  1. Wylistuj swoje pliki za pomocą GET /v1/files
  2. Zidentyfikuj te, które nie są już używane, po dacie utworzenia lub nazwie
  3. Usuń je za pomocą DELETE /v1/files/{file_id}

W tych operacjach pojawiają się trzy kody błędów, które diagnozuje się natychmiast. 404 sygnalizuje plik nieistniejący lub już usunięty, co jest typowym przypadkiem skryptu czyszczącego uruchomionego dwukrotnie. 401 wynika z brakującego lub nieprawidłowego klucza API, często ze zmiennej środowiskowej niezaładowanej w bieżącej powłoce. 413 wskazuje, że plik przekracza dozwolone 48 MB i występuje podczas przesyłania, a nie podczas zarządzania.

Kluczowe wnioski

  • GET /v1/files wyświetla listę wszystkich Twoich plików wraz z ich metadanymi
  • GET /v1/files/{id} pobiera konkretny plik
  • DELETE /v1/files/{id} trwale usuwa plik
  • Nadawaj plikom wyraźne nazwy, aby ułatwić zarządzanie
  • Sprawdź zależności (kolekcje, przepływy pracy) przed usunięciem