Pereiti prie turinio
Sursa Developers

POST/v1/uploads/{upload_id}/complete

Užbaigti įkėlimą

complete_upload

Gavusi visas dalis, Sursa sujungia failą, palygina viso failo SHA-256 su turinio lauku sha256 ir atlieka tas pačias patikras kaip įkeliant viena užklausa: formatą pagal turinio signatūrą ir antivirusinę patikrą. Rezultatas – ready arba rejected su reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Kiekvienas formato ar antivirusinės patikros atmetimas įrašomas į audito žurnalą kaip file.rejected.

Atsakas 200 reiškia, kad rezultatas paruoštas; 202 – failas dar tikrinamas (processing), o rezultatas gaunamas per GET /v1/uploads/{upload_id}. Jei būsena grįžta į pending (patikrą nutraukė API kopijos paleidimas iš naujo), siųskite complete dar kartą. Pakartojus complete po rezultato, grąžinamas tas pats rezultatas. Trūkstamos dalys grąžina 409 uploads.incomplete (details.missing). sha256, besiskiriantis nuo deklaruoto kuriant, arba parts[].etag, besiskiriantis nuo gautos dalies, grąžina 422 uploads.checksum_mismatch. Paruoštas, bet nepanaudotas įkėlimas galioja 24 valandas. Pridėta 1.62.0 versijoje.

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Kelio parametrai

  • upload_idstringprivalomas

    Įkėlimo ID (upl_ ir 32 šešioliktainiai simboliai).

    length ≤ 64

Antraštės parametrai

  • Idempotency-Keystring

    Raktas saugiam rašymo operacijos pakartojimui: nuo 1 iki 255 spausdinamų ASCII simbolių; rekomenduojamas atskiras UUID v4 kiekvienai loginei operacijai. Pakartojus užklausą su tuo pačiu raktu per 24 valandas, operacija iš naujo nevykdoma: grąžinamas išsaugotas atsakas (būsena, antraštės ir turinys) su antrašte Idempotency-Replayed: true. Tas pats raktas su kitu metodu, keliu, Content-Type ar turiniu grąžina 409 api.idempotency_mismatch; kol pirmoji užklausa dar vykdoma – 409 api.idempotency_in_progress su Retry-After: 1. Po 5xx ar 429 atsako raktas atlaisvinamas, ir pakartojimas operaciją vykdo iš naujo. Raktas galioja organizacijos ir iškvietėjo (API rakto, naudotojo arba pasirinktinio šaltinio rakto) ribose.

    length ≥ 1, length ≤ 255

Užklausos turinys

application/json

Objektas: UploadComplete

  • sha256stringprivalomas

    Viso failo SHA-256.

  • partsarray of UploadPartRef

    Neprivaloma dalių patikra: kiekvienos dalies ETag, kurį grąžino PUT …/parts/{n}.

    items ≤ 1000

Atsakai

200Rezultatas paruoštas: `ready` arba `rejected`.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

  • Idempotency-Replayed

    true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: Upload

  • idstringprivalomas

    Įkėlimo ID (upl_ ir 32 šešioliktainiai simboliai).

  • purposeUploadPurposeprivalomas
  • filenamestringprivalomas

    Failo pavadinimas (be aplankų).

  • content_typestringprivalomas

    Deklaruotas turinio tipas; tuščias, jei nedeklaruotas.

  • sizeinteger (int64)privalomas

    Failo dydis baitais.

  • sha256string | nullprivalomas

    Failo SHA-256, deklaruotas kuriant arba per complete; null, jei dar nežinomas.

  • statusUploadStatusprivalomas
  • part_sizeinteger (int64)privalomas

    Kiekvienos dalies, išskyrus paskutinę, dydis (nuo 5 iki 100 MiB).

  • part_countintegerprivalomas

    Dalių skaičius.

    ≥ 1, ≤ 1000

  • parts_receivedintegerprivalomas

    Gautų dalių skaičius.

    ≥ 0

  • partsarray of UploadPartprivalomas

    Gautos dalys pagal numerį (atsake į POST /v1/uploads sąrašas tuščias).

  • reject_reasonstring | nullprivalomas

    Atmetimo priežastis (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Išvardijimas gali būti papildytas; null, jei neatmesta.

  • reject_detailsobject | nullprivalomas

    Atmetimo informacija (plėtinys, deklaruotas ir nustatytas formatas, kontrolinės sumos); null, jei neatmesta.

  • created_atstring (date-time)privalomas

    Kada įkėlimas sukurtas.

  • expires_atstring (date-time)privalomas

    Terminas, iki kurio reikia užbaigti įkėlimą, o kai jis paruoštas, – jį panaudoti.

  • completed_atstring (date-time) | nullprivalomas

    Kada baigta patikra (ready arba rejected).

  • consumed_atstring (date-time) | nullprivalomas

    Kada įkėlimas panaudotas (kortelei, archyvui ar importui).

202Failas dar tikrinamas (`processing`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

  • Idempotency-Replayed

    true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: Upload

  • idstringprivalomas

    Įkėlimo ID (upl_ ir 32 šešioliktainiai simboliai).

  • purposeUploadPurposeprivalomas
  • filenamestringprivalomas

    Failo pavadinimas (be aplankų).

  • content_typestringprivalomas

    Deklaruotas turinio tipas; tuščias, jei nedeklaruotas.

  • sizeinteger (int64)privalomas

    Failo dydis baitais.

  • sha256string | nullprivalomas

    Failo SHA-256, deklaruotas kuriant arba per complete; null, jei dar nežinomas.

  • statusUploadStatusprivalomas
  • part_sizeinteger (int64)privalomas

    Kiekvienos dalies, išskyrus paskutinę, dydis (nuo 5 iki 100 MiB).

  • part_countintegerprivalomas

    Dalių skaičius.

    ≥ 1, ≤ 1000

  • parts_receivedintegerprivalomas

    Gautų dalių skaičius.

    ≥ 0

  • partsarray of UploadPartprivalomas

    Gautos dalys pagal numerį (atsake į POST /v1/uploads sąrašas tuščias).

  • reject_reasonstring | nullprivalomas

    Atmetimo priežastis (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Išvardijimas gali būti papildytas; null, jei neatmesta.

  • reject_detailsobject | nullprivalomas

    Atmetimo informacija (plėtinys, deklaruotas ir nustatytas formatas, kontrolinės sumos); null, jei neatmesta.

  • created_atstring (date-time)privalomas

    Kada įkėlimas sukurtas.

  • expires_atstring (date-time)privalomas

    Terminas, iki kurio reikia užbaigti įkėlimą, o kai jis paruoštas, – jį panaudoti.

  • completed_atstring (date-time) | nullprivalomas

    Kada baigta patikra (ready arba rejected).

  • consumed_atstring (date-time) | nullprivalomas

    Kada įkėlimas panaudotas (kortelei, archyvui ar importui).

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

409Objekto būsena neleidžia atlikti veiksmo, pvz., dublikatas, vyksta indeksavimas arba darbas jau apdorotas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

410Objektas buvo, bet nebepasiekiamas: nuoroda jau panaudota arba nebegalioja, arba failas ištrintas pasibaigus jo saugojimo laikotarpiui.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

  • Retry-After

    Kiek sekundžių palaukti prieš kartojant užklausą.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← uploads · API žinynas