Διαχείριση αρχείων: λίστα, ανάκτηση, διαγραφή
Σε αυτήν τη σελίδα
Τι συμβαίνει μετά την εκατοστή μεταφόρτωση
Η μεταφόρτωση ενός αρχείου διαρκεί τρία δευτερόλεπτα· η εύρεση εκείνου που στείλατε πριν από έξι εβδομάδες παίρνει πολύ περισσότερο χρόνο αν δεν έχετε κάνει τον κατάλληλο σχεδιασμό. Μετά τις αρχικές δοκιμές, ένας λογαριασμός συσσωρεύει δεκάδες και στη συνέχεια εκατοντάδες έγγραφα. Κάποια είναι ξεπερασμένα, άλλα διπλότυπα και άλλα χρησιμοποιούνται ακόμη από εφαρμογές που εκτελούνται. Το Files API παρέχει τρεις λειτουργίες για τη διαχείριση αυτού του αποθέματος: λίστα, ανάκτηση και διαγραφή. Φαίνονται δευτερεύουσες όταν ο όγκος είναι μικρός, αλλά γίνονται απαραίτητες αργότερα.
Απογραφή αποθήκευσης
Το GET /v1/files επιστρέφει όλα τα αρχεία που έχουν μεταφορτωθεί στον λογαριασμό σας:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Η απόκριση είναι μια σελιδοποιημένη λίστα, όπου κάθε καταχώριση επαναλαμβάνει τα μεταδεδομένα που είδατε κατά τη μεταφόρτωση:
{
"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"
}
]
}
Αυτή η προβολή λύνει τρεις πολύ συγκεκριμένες καταστάσεις: την ανάκτηση ενός file_id που δεν αποθηκεύσατε κατά τη μεταφόρτωση, τον έλεγχο του πραγματικού μεγέθους ενός εγγράφου που φαίνεται ασυνήθιστα βαρύ και τον εντοπισμό υποψηφίων για διαγραφή ταξινομώντας με βάση το created_at. Είναι επίσης το μόνο μέρος όπου θα δείτε με μια ματιά ότι η ίδια αναφορά στάλθηκε τρεις φορές με τρία διαφορετικά ονόματα.
Επαλήθευση συγκεκριμένου αρχείου
Όταν γνωρίζετε ήδη το αναγνωριστικό, το GET /v1/files/{file_id} κάνει ερώτημα για ένα μόνο έγγραφο:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Ανακτάτε τις ίδιες πληροφορίες όπως κατά τη μεταφόρτωση: αναγνωριστικό, όνομα, μέγεθος, ημερομηνία δημιουργίας και σκοπό. Η πιο χρήσιμη χρήση αυτής της κλήσης είναι αμυντική. Πριν ξεκινήσετε μια διαδικασία που αναφέρεται σε ένα file_id αποθηκευμένο για μεγάλο χρονικό διάστημα στη βάση δεδομένων σας, ένας έλεγχος που διαρκεί λίγα χιλιοστά του δευτερολέπτου σας γλιτώνει από ένα σφάλμα στη μέση μιας αλυσίδας χρεώσιμων αιτημάτων.
Διαγραφή και τι να ελέγξετε πριν
Η διαγραφή γίνεται με το DELETE /v1/files/{file_id} και η απόκριση επιβεβαιώνει την ενέργεια:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Απαιτούνται δύο έλεγχοι πριν πατήσετε τη σκανδάλη. Πρώτον, το αρχείο μπορεί να αναφέρεται σε μια συλλογή—μια έννοια που θα αναλύσουμε στα επόμενα μαθήματα. Η διαγραφή του μέσω του Files API δεν το αφαιρεί αυτόματα από τη συλλογή, αφήνοντάς σας με μια νεκρή αναφορά στον ευρετήριό σας: αφαιρέστε το πρώτα από τη συλλογή και μετά από τον χώρο αποθήκευσης. Δεύτερον, το αρχείο μπορεί να χρησιμοποιείται από ενεργές ροές εργασίας· οποιαδήποτε εφαρμογή διατηρεί αυτό το file_id στη βάση δεδομένων της θα λάβει σφάλματα μόλις πραγματοποιηθεί η διαγραφή, συχνά σε περιβάλλον παραγωγής και σπάνια ενώ παρακολουθείτε τα αρχεία καταγραφής.
Διατηρήστε τον χώρο αποθήκευσής σας καθαρό
Η ονομασία είναι το πρώτο σας εργαλείο διαχείρισης, επειδή το αρχικό όνομα διατηρείται στα μεταδεδομένα και αποτελεί τον μοναδικό αναγνώσιμο δείκτη σε μια λίστα εκατοντάδων καταχωρίσεων. Το rapport-q1-2026.pdf θα σημαίνει κάτι για εσάς σε οκτώ μήνες· το document.pdf ποτέ. Ο ίδιος συλλογισμός ισχύει για το api-specs-v2.json έναντι του data.json. Κάντε το αυτό συνήθεια όταν προετοιμάζετε το αρχείο στον δίσκο σας, όχι κατά τη μεταφόρτωση: είναι το τοπικό όνομα που μεταδίδεται.
Τα μεταφορτωμένα αρχεία παραμένουν αποθηκευμένα επ’ αόριστον, χωρίς αυτόματη λήξη. Μια τριμηνιαία ρουτίνα καθαρισμού αρκεί για να αποφύγετε την απόκλιση, σε τρία βήματα:
- Καταγράψτε τα αρχεία σας με το
GET /v1/files - Εντοπίστε εκείνα που δεν χρησιμοποιούνται πλέον, με βάση την ημερομηνία δημιουργίας ή το όνομα
- Διαγράψτε τα με το
DELETE /v1/files/{file_id}
Τρεις κωδικοί σφάλματος εμφανίζονται σε αυτές τις λειτουργίες και διαγιγνώσκονται άμεσα. Ένα 404 σηματοδοτεί ένα ανύπαρκτο ή ήδη διαγραμμένο αρχείο, μια τυπική περίπτωση εκτέλεσης ενός σεναρίου καθαρισμού δύο φορές. Ένα 401 προέρχεται από ένα missing ή μη έγκυρο κλειδί API, συχνά μια μεταβλητή περιβάλλοντος που δεν φορτώθηκε στο τρέχον κέλυφος. Ένα 413 υποδεικνύει ότι το αρχείο υπερβαίνει τα επιτρεπόμενα 48 MB και συμβαίνει κατά τη μεταφόρτωση, όχι κατά τη διαχείριση.
Βασικά σημεία
- Το
GET /v1/filesκαταγράφει όλα τα αρχεία σας με τα μεταδεδομένα τους - Το
GET /v1/files/{id}ανακτά ένα συγκεκριμένο αρχείο - Το
DELETE /v1/files/{id}διαγράφει οριστικά ένα αρχείο - Ονομάζετε τα αρχεία σας ρητά για να διευκολύνετε τη διαχείριση
- Ελέγχετε τις εξαρτήσεις (συλλογές, ροές εργασίας) πριν τη διαγραφή