POST/v1/uploads/{upload_id}/complete

Üleslaadimise lõpetamine

complete_upload

Kui kõik osad on vastu võetud, paneb Sursa faili kokku, võrdleb kogu faili SHA-256 väärtust kehas oleva väljaga sha256 ja teeb samad kontrollid nagu ühe päringuga üleslaadimisel: vorming sisu signatuuri järgi ja viirusskannimine. Tulemus on ready või rejected koos väljaga reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Iga vormingu- või viirusekontrolli tagasilükkamine kirjutatakse auditilogisse kujul file.rejected.

Vastus 200 tähendab, et tulemus on valmis; 202 tähendab, et faili alles kontrollitakse (processing), ja tulemus tuleb päringuga GET /v1/uploads/{upload_id}. Kui olek naaseb väärtusele pending (API eksemplari taaskäivitus katkestas kontrolli), saatke complete uuesti. complete kordamine pärast tulemust tagastab sama tulemuse. Puuduvad osad tagastavad 409 uploads.incomplete (details.missing). Kui sha256 erineb loomisel deklareeritust või parts[].etag erineb vastuvõetud osast, tagastatakse 422 uploads.checksum_mismatch. Valmis üleslaadimine, mida ei kasutata, kehtib 24 tundi. Lisatud versioonis 1.62.0.

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Teeparameetrid

upload_idstringkohustuslik
Üleslaadimise ID (upl_, millele järgneb 32 kuueteistkümnendmärki).
length ≤ 64

Päiseparameetrid

Idempotency-Keystring
Võti kirjutamistoimingu turvaliseks kordamiseks: 1–255 prinditavat ASCII-märki; soovitatav on UUID v4 iga loogilise toimingu kohta. Kordus sama võtmega 24 tunni jooksul ei käivita toimingut uuesti: tagastatakse salvestatud vastus (olek, päised ja keha) päisega Idempotency-Replayed: true. Sama võti teise meetodi, tee, Content-Type või kehaga tagastab 409 api.idempotency_mismatch; kuni esimene päring veel töötab, tagastatakse 409 api.idempotency_in_progress koos päisega Retry-After: 1. Pärast vastust 5xx või 429 võti vabastatakse ja kordus käivitab toimingu uuesti. Võti kehtib organisatsiooni ja päringu tegija piires (API-võti, kasutaja või kohandatud allika võti).
length ≥ 1, length ≤ 255

Päringu keha

application/json

Objekt: UploadComplete

sha256stringkohustuslik
Kogu faili SHA-256.
partsarray of UploadPartRef
Valikuline osade kontroll: iga osa ETag, nagu selle tagastas PUT …/parts/{n}.
items ≤ 1000

Vastused

200Tulemus on valmis: `ready` või `rejected`.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.
Idempotency-Replayed
true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: Upload

idstringkohustuslik
Üleslaadimise ID (upl_, millele järgneb 32 kuueteistkümnendmärki).
purposeUploadPurposekohustuslik
filenamestringkohustuslik
Faili nimi (ilma kaustadeta).
content_typestringkohustuslik
Deklareeritud sisutüüp; tühi, kui seda ei deklareeritud.
sizeinteger (int64)kohustuslik
Faili suurus baitides.
sha256string | nullkohustuslik
Faili SHA-256, mis deklareeriti loomisel või toimingus complete; null, kui see pole veel teada.
statusUploadStatuskohustuslik
part_sizeinteger (int64)kohustuslik
Iga osa suurus peale viimase (5–100 MiB).
part_countintegerkohustuslik
Osade arv.
≥ 1, ≤ 1000
parts_receivedintegerkohustuslik
Vastu võetud osade arv.
≥ 0
partsarray of UploadPartkohustuslik
Vastu võetud osad numbri järgi (vastuses POST /v1/uploads tühi).
reject_reasonstring | nullkohustuslik
Tagasilükkamise põhjus (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Loend võib täieneda; null, kui üleslaadimist tagasi ei lükatud.
reject_detailsobject | nullkohustuslik
Tagasilükkamise üksikasjad (laiend, deklareeritud ja tuvastatud vorming, kontrollsummad); null, kui üleslaadimist tagasi ei lükatud.
created_atstring (date-time)kohustuslik
Üleslaadimise loomise aeg.
expires_atstring (date-time)kohustuslik
Tähtaeg üleslaadimise lõpetamiseks ja, kui see on valmis, selle kasutamiseks.
completed_atstring (date-time) | nullkohustuslik
Kontrolli lõppemise aeg (ready või rejected).
consumed_atstring (date-time) | nullkohustuslik
Üleslaadimise kasutamise aeg (kaardi, arhiivi või impordi poolt).

202Faili alles kontrollitakse (`processing`).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.
Idempotency-Replayed
true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: Upload

idstringkohustuslik
Üleslaadimise ID (upl_, millele järgneb 32 kuueteistkümnendmärki).
purposeUploadPurposekohustuslik
filenamestringkohustuslik
Faili nimi (ilma kaustadeta).
content_typestringkohustuslik
Deklareeritud sisutüüp; tühi, kui seda ei deklareeritud.
sizeinteger (int64)kohustuslik
Faili suurus baitides.
sha256string | nullkohustuslik
Faili SHA-256, mis deklareeriti loomisel või toimingus complete; null, kui see pole veel teada.
statusUploadStatuskohustuslik
part_sizeinteger (int64)kohustuslik
Iga osa suurus peale viimase (5–100 MiB).
part_countintegerkohustuslik
Osade arv.
≥ 1, ≤ 1000
parts_receivedintegerkohustuslik
Vastu võetud osade arv.
≥ 0
partsarray of UploadPartkohustuslik
Vastu võetud osad numbri järgi (vastuses POST /v1/uploads tühi).
reject_reasonstring | nullkohustuslik
Tagasilükkamise põhjus (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Loend võib täieneda; null, kui üleslaadimist tagasi ei lükatud.
reject_detailsobject | nullkohustuslik
Tagasilükkamise üksikasjad (laiend, deklareeritud ja tuvastatud vorming, kontrollsummad); null, kui üleslaadimist tagasi ei lükatud.
created_atstring (date-time)kohustuslik
Üleslaadimise loomise aeg.
expires_atstring (date-time)kohustuslik
Tähtaeg üleslaadimise lõpetamiseks ja, kui see on valmis, selle kasutamiseks.
completed_atstring (date-time) | nullkohustuslik
Kontrolli lõppemise aeg (ready või rejected).
consumed_atstring (date-time) | nullkohustuslik
Üleslaadimise kasutamise aeg (kaardi, arhiivi või impordi poolt).

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

404Objekti ei ole olemas või see ei ole teile kättesaadav. API ei kinnita piiratud juurdepääsuga objekti olemasolu.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

409Objekti olek ei võimalda toimingut, näiteks duplikaat, käimasolev indekseerimine või juba töödeldud töö.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

410Objekt oli olemas, kuid ei ole enam kättesaadav: link on kasutatud või selle kehtivus on lõppenud või fail kustutati säilitusaja lõpus.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

Retry-After
Sekundite arv, mida oodata enne päringu kordamist.
RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← uploads · API teatmik

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Proovi

API-võti

Võti jääb ainult selle vahekaardi mällu ja see saadetakse üksnes aadressile https://api.sursa.com.

Päringud muudavad teie organisatsiooni päris andmeid.

Idempotency-Key header

upload_id path *

Idempotency-Key

Kui väli on tühi, luuakse iga päringu jaoks uus võti.

Päringu keha (JSON)