POST/v1/uploads/{upload_id}/complete
Ολοκλήρωση μεταφόρτωσης
complete_upload
Όταν ληφθούν όλα τα τμήματα, η Sursa συναρμολογεί το αρχείο, συγκρίνει το SHA-256 ολόκληρου του αρχείου με το sha256 στο σώμα και εκτελεί τους ίδιους ελέγχους όπως για μια μεταφόρτωση με ένα αίτημα: τη μορφή βάσει της υπογραφής του περιεχομένου και τον έλεγχο για ιούς. Το αποτέλεσμα είναι ready ή rejected με reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Κάθε απόρριψη από τον έλεγχο μορφής ή τον έλεγχο για ιούς καταγράφεται στο αρχείο ελέγχου ως file.rejected.
Η απόκριση 200 σημαίνει ότι το αποτέλεσμα είναι έτοιμο· το 202 σημαίνει ότι το αρχείο ελέγχεται ακόμη (processing), και το αποτέλεσμα έρχεται από το GET /v1/uploads/{upload_id}. Αν η κατάσταση επιστρέψει σε pending (μια επανεκκίνηση μιας παρουσίας του API διέκοψε τον έλεγχο), στείλτε ξανά το complete. Η επανάληψη του complete μετά το αποτέλεσμα επιστρέφει το ίδιο αποτέλεσμα. Τα τμήματα που λείπουν επιστρέφουν 409 uploads.incomplete (details.missing). Ένα sha256 που διαφέρει από αυτό που δηλώθηκε κατά τη δημιουργία ή ένα parts[].etag που διαφέρει από ένα τμήμα που λήφθηκε επιστρέφει 422 uploads.checksum_mismatch. Μια έτοιμη μεταφόρτωση που δεν χρησιμοποιείται διατηρείται για 24 ώρες. Προστέθηκε στην έκδοση 1.62.0.
Έλεγχος ταυτότητας
Στείλτε ένα κλειδί API στην κεφαλίδα Authorization: Authorization: Bearer <κλειδί>.
Παράμετροι διαδρομής
upload_idstringυποχρεωτικόID της μεταφόρτωσης (
upl_και ακολουθούν 32 δεκαεξαδικοί χαρακτήρες).length ≤ 64
Παράμετροι κεφαλίδας
Idempotency-KeystringΚλειδί για ασφαλή επανάληψη μιας εγγραφής δεδομένων: 1 έως 255 εκτυπώσιμοι χαρακτήρες ASCII· συνιστάται ένα UUID v4 ανά λογική λειτουργία. Επανάληψη με το ίδιο κλειδί εντός 24 ωρών δεν εκτελεί ξανά τη λειτουργία: επιστρέφει την αποθηκευμένη απόκριση (κατάσταση, κεφαλίδες και σώμα) με την κεφαλίδα
Idempotency-Replayed: true. Το ίδιο κλειδί με διαφορετική μέθοδο, διαδρομή,Content-Typeή σώμα επιστρέφει409 api.idempotency_mismatch· όσο το πρώτο αίτημα εκτελείται ακόμη –409 api.idempotency_in_progressμεRetry-After: 1. Μετά από απόκριση 5xx ή 429 το κλειδί αποδεσμεύεται, και η επανάληψη εκτελεί ξανά τη λειτουργία. Το κλειδί ισχύει στο πλαίσιο του οργανισμού και του πελάτη που καλεί το API (κλειδί API, χρήστης ή κλειδί προσαρμοσμένης πηγής).length ≥ 1, length ≤ 255
Σώμα αιτήματος
application/json
sha256stringυποχρεωτικόΤο SHA-256 ολόκληρου του αρχείου.
partsarray of UploadPartRefΠροαιρετικός έλεγχος τμημάτων: το ETag κάθε τμήματος, όπως το επέστρεψε το
PUT …/parts/{n}.items ≤ 1000
Αποκρίσεις
200Το αποτέλεσμα είναι έτοιμο: `ready` ή `rejected`.
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
Idempotency-ReplayedΤο
trueσημαίνει ότι η απόκριση επαναλήφθηκε από την αποθηκευμένη για αυτό τοIdempotency-Key: η λειτουργία δεν εκτελέστηκε ξανά.
application/json
idstringυποχρεωτικόΤο ID της μεταφόρτωσης (
upl_και 32 δεκαεξαδικοί χαρακτήρες).filenamestringυποχρεωτικόΤο όνομα του αρχείου (χωρίς φακέλους).
content_typestringυποχρεωτικόΟ δηλωμένος τύπος περιεχομένου· κενό, αν δεν δηλώθηκε.
sizeinteger (int64)υποχρεωτικόΤο μέγεθος του αρχείου σε byte.
sha256string | nullυποχρεωτικόΤο SHA-256 του αρχείου, δηλωμένο κατά τη δημιουργία ή κατά το
complete·null, αν δεν είναι ακόμη γνωστό.part_sizeinteger (int64)υποχρεωτικόΤο μέγεθος κάθε τμήματος εκτός από το τελευταίο (από 5 έως 100 MiB).
part_countintegerυποχρεωτικόΟ αριθμός των τμημάτων.
≥ 1, ≤ 1000
parts_receivedintegerυποχρεωτικόΟ αριθμός των τμημάτων που ελήφθησαν.
≥ 0
Τα τμήματα που ελήφθησαν, ανά αριθμό (κενό στην απόκριση του
POST /v1/uploads).reject_reasonstring | nullυποχρεωτικόΟ λόγος απόρριψης (
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. Η απαρίθμηση μπορεί να επεκταθεί·null, αν δεν απορρίφθηκε.reject_detailsobject | nullυποχρεωτικόΛεπτομέρειες της απόρριψης (η επέκταση, η δηλωμένη και η ανιχνευμένη μορφή, αθροίσματα ελέγχου)·
null, αν δεν απορρίφθηκε.created_atstring (date-time)υποχρεωτικόΠότε δημιουργήθηκε η μεταφόρτωση.
expires_atstring (date-time)υποχρεωτικόΗ προθεσμία για την ολοκλήρωση της μεταφόρτωσης και, μόλις είναι έτοιμη, για τη χρήση της.
completed_atstring (date-time) | nullυποχρεωτικόΠότε ολοκληρώθηκε ο έλεγχος (
readyήrejected).consumed_atstring (date-time) | nullυποχρεωτικόΠότε χρησιμοποιήθηκε η μεταφόρτωση (από μια κάρτα, ένα αρχείο ZIP ή μια εισαγωγή).
202Το αρχείο ελέγχεται ακόμη (`processing`).
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
Idempotency-ReplayedΤο
trueσημαίνει ότι η απόκριση επαναλήφθηκε από την αποθηκευμένη για αυτό τοIdempotency-Key: η λειτουργία δεν εκτελέστηκε ξανά.
application/json
idstringυποχρεωτικόΤο ID της μεταφόρτωσης (
upl_και 32 δεκαεξαδικοί χαρακτήρες).filenamestringυποχρεωτικόΤο όνομα του αρχείου (χωρίς φακέλους).
content_typestringυποχρεωτικόΟ δηλωμένος τύπος περιεχομένου· κενό, αν δεν δηλώθηκε.
sizeinteger (int64)υποχρεωτικόΤο μέγεθος του αρχείου σε byte.
sha256string | nullυποχρεωτικόΤο SHA-256 του αρχείου, δηλωμένο κατά τη δημιουργία ή κατά το
complete·null, αν δεν είναι ακόμη γνωστό.part_sizeinteger (int64)υποχρεωτικόΤο μέγεθος κάθε τμήματος εκτός από το τελευταίο (από 5 έως 100 MiB).
part_countintegerυποχρεωτικόΟ αριθμός των τμημάτων.
≥ 1, ≤ 1000
parts_receivedintegerυποχρεωτικόΟ αριθμός των τμημάτων που ελήφθησαν.
≥ 0
Τα τμήματα που ελήφθησαν, ανά αριθμό (κενό στην απόκριση του
POST /v1/uploads).reject_reasonstring | nullυποχρεωτικόΟ λόγος απόρριψης (
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. Η απαρίθμηση μπορεί να επεκταθεί·null, αν δεν απορρίφθηκε.reject_detailsobject | nullυποχρεωτικόΛεπτομέρειες της απόρριψης (η επέκταση, η δηλωμένη και η ανιχνευμένη μορφή, αθροίσματα ελέγχου)·
null, αν δεν απορρίφθηκε.created_atstring (date-time)υποχρεωτικόΠότε δημιουργήθηκε η μεταφόρτωση.
expires_atstring (date-time)υποχρεωτικόΗ προθεσμία για την ολοκλήρωση της μεταφόρτωσης και, μόλις είναι έτοιμη, για τη χρήση της.
completed_atstring (date-time) | nullυποχρεωτικόΠότε ολοκληρώθηκε ο έλεγχος (
readyήrejected).consumed_atstring (date-time) | nullυποχρεωτικόΠότε χρησιμοποιήθηκε η μεταφόρτωση (από μια κάρτα, ένα αρχείο ZIP ή μια εισαγωγή).
401Δεν στάλθηκαν διαπιστευτήρια (ούτε cookie συνεδρίας ούτε κλειδί API) ή το κλειδί δεν βρέθηκε.
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
403Η ενέργεια δεν επιτρέπεται: ο ρόλος δεν επαρκεί, δεν υπάρχει πρόσβαση στη συλλογή ή στην κάρτα, το αίτημα εκτελείται στη λειτουργία «View as» ή ο οργανισμός έχει ανασταλεί ή διαγραφεί (το `detail` είναι αντικείμενο με `code: org_suspended | org_deleted`).
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
404Το αντικείμενο δεν υπάρχει ή δεν είναι διαθέσιμο σε εσάς. Το API δεν επιβεβαιώνει ότι υπάρχει ένα αντικείμενο περιορισμένης πρόσβασης.
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
409Η κατάσταση του αντικειμένου δεν επιτρέπει την ενέργεια, για παράδειγμα διπλότυπο, ευρετηρίαση σε εξέλιξη ή εργασία που έχει ήδη υποβληθεί σε επεξεργασία.
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
410Το αντικείμενο υπήρχε, αλλά δεν είναι πλέον διαθέσιμο: ο σύνδεσμος χρησιμοποιήθηκε ή έληξε, ή το αρχείο διαγράφηκε στο τέλος της περιόδου διατήρησής του.
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
422Σφάλμα επικύρωσης: το σώμα ή οι παράμετροι δεν αντιστοιχούν στο σχήμα (το `detail` είναι λίστα σφαλμάτων επικύρωσης) ή η τιμή μιας παραμέτρου είναι εκτός εύρους (το `detail` είναι μήνυμα).
Κεφαλίδες απόκρισης
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
429Πάρα πολλά αιτήματα (`api.rate_limited`), η ποσόστωση του οργανισμού για το λεπτό, την ημέρα ή τον μήνα εξαντλήθηκε (`api.quota_exceeded`· το `error.details` περιέχει τα `quota`, `limit` και `reset_at`), ο οργανισμός έφτασε στο όριό του ή η υπηρεσία απαντήσεων είναι απασχολημένη (`answers.engine_busy`). Περιμένετε τον χρόνο που δίνει η κεφαλίδα `Retry-After`.
Κεφαλίδες απόκρισης
Retry-AfterΑριθμός δευτερολέπτων αναμονής πριν επαναλάβετε το αίτημα.
RateLimit-PolicyΤα όρια σε ισχύ, στη μορφή του προσχεδίου IETF
draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα"<name>";q=<quota>;w=<window in seconds>. Τοkeyείναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναιuser, χωρίς διαπιστευτήριαip)· ταminute,dayκαιmonthείναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.RateLimitΤι απομένει από κάθε όριο του
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitΌριο της αυστηρότερης εγγραφής του
RateLimit-Policy(εκείνης με τα λιγότερα εναπομείναντα αιτήματα).X-RateLimit-RemainingΑιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-ResetΔευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
application/json
Κωδικοί σφαλμάτων
Κωδικοί που μπορεί να επιστρέψει αυτό το τελικό σημείο στο error.code, εκτός από τους γενικούς κωδικούς κάθε αιτήματος.
Ασφαλείς επαναλήψεις
Στείλτε μια κεφαλίδα Idempotency-Key (για παράδειγμα ένα UUID) με κάθε POST και PATCH. Μια επανάληψη με το ίδιο κλειδί εντός 24 ωρών επιστρέφει την αποθηκευμένη απόκριση αντί να εκτελέσει ξανά το αίτημα.
Όρια ρυθμού
Οι αποκρίσεις περιέχουν τις κεφαλίδες RateLimit και RateLimit-Policy, καθώς και τις παλαιότερες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απόκριση 429 έχει την κεφαλίδα Retry-After σε δευτερόλεπτα: περιμένετε και επαναλάβετε το αίτημα.