Siirry sisältöön
Sursa Developers

POST/v1/uploads/{upload_id}/complete

Viimeistele lataus

complete_upload

Kun kaikki osat on vastaanotettu, Sursa kokoaa tiedoston, vertaa koko tiedoston SHA-256-tiivistettä rungon sha256-kenttään ja tekee samat tarkistukset kuin yhden pyynnön latauksessa: muodon tunnistuksen sisällön tunnistetavuista ja virustarkistuksen. Tulos on ready tai rejected ja reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Jokainen muoto- tai virustarkistuksen hylkäys kirjataan tarkastuslokiin nimellä file.rejected.

Vastaus 200 tarkoittaa, että tulos on valmis; 202 tarkoittaa, että tiedostoa tarkistetaan vielä (processing), ja tulos saadaan kutsulla GET /v1/uploads/{upload_id}. Jos tila palaa arvoon pending (API-instanssin uudelleenkäynnistys keskeytti tarkistuksen), lähetä complete uudelleen. complete-kutsun toistaminen tuloksen jälkeen palauttaa saman tuloksen. Puuttuvat osat palauttavat 409 uploads.incomplete (details.missing). sha256, joka eroaa luonnin yhteydessä ilmoitetusta, tai parts[].etag, joka eroaa vastaanotetusta osasta, palauttaa 422 uploads.checksum_mismatch. Valmis lataus, jota ei käytetä, säilyy 24 tuntia. Lisätty versiossa 1.62.0.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Polkuparametrit

  • upload_idstringpakollinen

    Latauksen tunnus (upl_ ja 32 heksadesimaalimerkkiä).

    length ≤ 64

Otsakeparametrit

  • Idempotency-Keystring

    Avain kirjoituksen turvalliseen uusintayritykseen: 1–255 tulostettavaa ASCII-merkkiä; suositus on yksi UUID v4 jokaista loogista toimintoa kohden. Uusintayritys samalla avaimella 24 tunnin kuluessa ei suorita toimintoa uudelleen: se palauttaa tallennetun vastauksen (tila, otsakkeet ja runko) Idempotency-Replayed: true -otsakkeella. Sama avain eri metodilla, polulla, Content-Type-arvolla tai rungolla palauttaa 409 api.idempotency_mismatch; kun ensimmäinen pyyntö on vielä käynnissä, vastaus on 409 api.idempotency_in_progress ja Retry-After: 1. 5xx- tai 429-vastauksen jälkeen avain vapautuu, ja uusintayritys suorittaa toiminnon uudelleen. Avain on sidottu organisaatioon ja kutsujaan (API-avain, käyttäjä tai mukautetun lähteen avain).

    length ≥ 1, length ≤ 255

Pyynnön runko

application/json

Objekti: UploadComplete

  • sha256stringpakollinen

    Koko tiedoston SHA-256.

  • partsarray of UploadPartRef

    Valinnainen osien tarkistus: kunkin osan ETag sellaisena kuin PUT …/parts/{n} sen palautti.

    items ≤ 1000

Vastaukset

200Tulos on valmis: `ready` tai `rejected`.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

  • Idempotency-Replayed

    true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: Upload

  • idstringpakollinen

    Latauksen tunnus (upl_ ja sen perässä 32 heksadesimaalimerkkiä).

  • purposeUploadPurposepakollinen
  • filenamestringpakollinen

    Tiedoston nimi (ilman kansioita).

  • content_typestringpakollinen

    Ilmoitettu sisältötyyppi; tyhjä, jos sitä ei ole ilmoitettu.

  • sizeinteger (int64)pakollinen

    Tiedoston koko tavuina.

  • sha256string | nullpakollinen

    Tiedoston SHA-256, joka ilmoitettiin luonnissa tai complete-vaiheessa; null, jos sitä ei vielä tiedetä.

  • statusUploadStatuspakollinen
  • part_sizeinteger (int64)pakollinen

    Kunkin osan koko viimeistä lukuun ottamatta (5–100 MiB).

  • part_countintegerpakollinen

    Osien määrä.

    ≥ 1, ≤ 1000

  • parts_receivedintegerpakollinen

    Vastaanotettujen osien määrä.

    ≥ 0

  • partsarray of UploadPartpakollinen

    Vastaanotetut osat numeroittain (tyhjä POST /v1/uploads-vastauksessa).

  • reject_reasonstring | nullpakollinen

    Hylkäyksen syy (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Luettelo voi laajentua; null, jos latausta ei ole hylätty.

  • reject_detailsobject | nullpakollinen

    Hylkäyksen tiedot (tiedostotarkenne, ilmoitettu ja tunnistettu muoto, tarkistussummat); null, jos latausta ei ole hylätty.

  • created_atstring (date-time)pakollinen

    Latauksen luontiaika.

  • expires_atstring (date-time)pakollinen

    Määräaika, johon mennessä lataus on viimeisteltävä ja valmis lataus käytettävä.

  • completed_atstring (date-time) | nullpakollinen

    Milloin tarkistus päättyi (ready tai rejected).

  • consumed_atstring (date-time) | nullpakollinen

    Milloin lataus käytettiin (kortti, arkisto tai tuonti).

202Tiedostoa tarkistetaan vielä (`processing`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

  • Idempotency-Replayed

    true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: Upload

  • idstringpakollinen

    Latauksen tunnus (upl_ ja sen perässä 32 heksadesimaalimerkkiä).

  • purposeUploadPurposepakollinen
  • filenamestringpakollinen

    Tiedoston nimi (ilman kansioita).

  • content_typestringpakollinen

    Ilmoitettu sisältötyyppi; tyhjä, jos sitä ei ole ilmoitettu.

  • sizeinteger (int64)pakollinen

    Tiedoston koko tavuina.

  • sha256string | nullpakollinen

    Tiedoston SHA-256, joka ilmoitettiin luonnissa tai complete-vaiheessa; null, jos sitä ei vielä tiedetä.

  • statusUploadStatuspakollinen
  • part_sizeinteger (int64)pakollinen

    Kunkin osan koko viimeistä lukuun ottamatta (5–100 MiB).

  • part_countintegerpakollinen

    Osien määrä.

    ≥ 1, ≤ 1000

  • parts_receivedintegerpakollinen

    Vastaanotettujen osien määrä.

    ≥ 0

  • partsarray of UploadPartpakollinen

    Vastaanotetut osat numeroittain (tyhjä POST /v1/uploads-vastauksessa).

  • reject_reasonstring | nullpakollinen

    Hylkäyksen syy (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Luettelo voi laajentua; null, jos latausta ei ole hylätty.

  • reject_detailsobject | nullpakollinen

    Hylkäyksen tiedot (tiedostotarkenne, ilmoitettu ja tunnistettu muoto, tarkistussummat); null, jos latausta ei ole hylätty.

  • created_atstring (date-time)pakollinen

    Latauksen luontiaika.

  • expires_atstring (date-time)pakollinen

    Määräaika, johon mennessä lataus on viimeisteltävä ja valmis lataus käytettävä.

  • completed_atstring (date-time) | nullpakollinen

    Milloin tarkistus päättyi (ready tai rejected).

  • consumed_atstring (date-time) | nullpakollinen

    Milloin lataus käytettiin (kortti, arkisto tai tuonti).

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

409Objektin tila ei salli toimenpidettä, esimerkiksi kaksoiskappale, käynnissä oleva indeksointi tai jo käsitelty työ.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

410Objekti oli olemassa, mutta se ei ole enää saatavilla: linkki on jo käytetty tai sen voimassaolo on päättynyt, tai tiedosto poistettiin säilytysajan päättyessä.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

  • Retry-After

    Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← uploads · API-viite