Hopp til innholdet
Sursa Developers

POST/v1/uploads

Start en flerdelt opplasting

create_upload

Åpner en opplastingsøkt for en stor fil (opptil installasjonens grense for flerdelt opplasting, 5 GB som standard): navnet, innholdstypen, størrelsen og purpose, som angir hva som skal bruke opplastingen: card_file (POST /v1/cards), archive (POST /v1/cards/archive) eller import_attachment (et vedlegg til et dokument i en egendefinert kilde). Svaret inneholder id (upl_ etterfulgt av 32 heksadesimale tegn), delstørrelsen part_size og antall deler part_count. Alle deler unntatt den siste er nøyaktig part_size byte (fra 5 til 100 MiB), og den siste delen er resten. En ufullført opplasting lever i 24 timer (expires_at).

En filtype i filnavnet utenfor formatene for formålet returnerer 415 uploads.unsupported_format (et importvedlegg godtar alle filtyper). En fil som er større enn installasjonens grense eller organisasjonens samlede lagringsplass i prisplanen, returnerer 413 uploads.too_large. Hvis det ikke er nok lagringsplass igjen, medregnet organisasjonens ufullførte opplastinger, returneres 402 limits.storage.

Delene går gjennom Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) og krypteres med organisasjonens nøkkel i fillagringen; det finnes ingen direkte lenker til lagringen. Bare API-nøkkelen eller brukeren som opprettet opplastingen, kan se og bruke den. Lagt til i 1.62.0.

Autentisering

Send en API-nøkkel i headeren Authorization: Authorization: Bearer <nøkkel>.

Headerparametere

  • Idempotency-Keystring

    Nøkkel for et trygt nytt forsøk på en skriveoperasjon: 1 til 255 utskrivbare ASCII-tegn; en UUID v4 per logisk operasjon anbefales. Et nytt forsøk med samme nøkkel innen 24 timer kjører ikke operasjonen på nytt: det returnerer det lagrede svaret (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøkkel med en annen metode, bane, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første forespørselen fortsatt kjører, 409 api.idempotency_in_progress med Retry-After: 1. Etter et 5xx- eller 429-svar frigjøres nøkkelen, og et nytt forsøk kjører operasjonen på nytt. Nøkkelen gjelder per organisasjon og per kaller (API-nøkkel, bruker eller nøkkel for en egendefinert kilde).

    length ≥ 1, length ≤ 255

Forespørselens brødtekst

application/json

Objekt: UploadCreate

  • filenamestringobligatorisk

    Filnavnet med filtypen; filtypen bestemmer formatet.

    length ≥ 1, length ≤ 255

  • content_typestring

    Den oppgitte innholdstypen (MIME); den sammenlignes med filsignaturen.

    length ≤ 255

  • sizeinteger (int64)obligatorisk

    Filstørrelsen i byte.

    ≥ 1

  • purposeUploadPurposeobligatorisk
  • sha256string

    Filens SHA-256, hvis den er kjent på forhånd; complete sammenligner sjekksummen med den.

Svar

201Opplastingsøkten er opprettet.

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

  • Idempotency-Replayed

    true betyr at svaret ble gjentatt fra det lagrede svaret for denne Idempotency-Key: operasjonen ble ikke kjørt på nytt.

application/json

Objekt: Upload

  • idstringobligatorisk

    Opplastingens ID (upl_ etterfulgt av 32 heksadesimale tegn).

  • purposeUploadPurposeobligatorisk
  • filenamestringobligatorisk

    Filnavnet (uten mapper).

  • content_typestringobligatorisk

    Den oppgitte innholdstypen; tom hvis den ikke er oppgitt.

  • sizeinteger (int64)obligatorisk

    Filstørrelsen i byte.

  • sha256string | nullobligatorisk

    Filens SHA-256, oppgitt ved opprettelsen eller ved complete; null hvis den ikke er kjent ennå.

  • statusUploadStatusobligatorisk
  • part_sizeinteger (int64)obligatorisk

    Størrelsen på hver del unntatt den siste (fra 5 til 100 MiB).

  • part_countintegerobligatorisk

    Antall deler.

    ≥ 1, ≤ 1000

  • parts_receivedintegerobligatorisk

    Antall mottatte deler.

    ≥ 0

  • partsarray of UploadPartobligatorisk

    De mottatte delene etter nummer (tom i svaret på POST /v1/uploads).

  • reject_reasonstring | nullobligatorisk

    Årsaken til avvisningen (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enumen kan utvides; null hvis opplastingen ikke er avvist.

  • reject_detailsobject | nullobligatorisk

    Detaljer om avvisningen (filtypen, det oppgitte og det oppdagede formatet, sjekksummer); null hvis opplastingen ikke er avvist.

  • created_atstring (date-time)obligatorisk

    Når opplastingen ble opprettet.

  • expires_atstring (date-time)obligatorisk

    Fristen for å fullføre opplastingen og, når den er klar, for å bruke den.

  • completed_atstring (date-time) | nullobligatorisk

    Når kontrollen ble fullført (ready eller rejected).

  • consumed_atstring (date-time) | nullobligatorisk

    Når opplastingen ble brukt (av et kort, et arkiv eller en import).

401Ingen påloggingsinformasjon ble sendt (verken øktinformasjonskapsel eller API-nøkkel), eller nøkkelen ble ikke funnet.

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

402Organisasjonen har nådd en grense i prisplanen (kort, lagring eller brukere). `error.details` inneholder `kind`, `limit` og `used`.

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

403Handlingen er ikke tillatt: rollen er utilstrekkelig, det finnes ingen tilgang til samlingen eller kortet, forespørselen kjører i modusen «View as», eller organisasjonen er suspendert eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

413Forespørselens brødtekst overskrider tillatt størrelse.

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

415Filformatet støttes ikke.

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

422Valideringsfeil: brødteksten eller parameterne samsvarer ikke med skjemaet (`detail` er en liste over valideringsfeil), eller en parameterverdi er utenfor tillatt område (`detail` er en melding).

Headere i svaret

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

429For mange forespørsler (`api.rate_limited`), organisasjonens kvote for minuttet, døgnet eller måneden er brukt opp (`api.quota_exceeded`; `error.details` inneholder `quota`, `limit` og `reset_at`), organisasjonens grense er nådd, eller svartjenesten er opptatt (`answers.engine_busy`). Vent så lenge som headeren `Retry-After` angir.

Headere i svaret

  • Retry-After

    Antall sekunder du skal vente før du prøver forespørselen på nytt.

  • RateLimit-Policy

    Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.

  • RateLimit

    Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).

  • X-RateLimit-Remaining

    Gjenværende forespørsler under den strengeste grensen.

  • X-RateLimit-Reset

    Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

Feilkoder

Kodene denne operasjonen kan returnere i error.code, i tillegg til de generelle kodene for alle forespørsler.

Trygge nye forsøk

Send en Idempotency-Key-header (for eksempel en UUID) med hver POST og PATCH. Et nytt forsøk med samme nøkkel innen 24 timer returnerer det lagrede svaret i stedet for å kjøre forespørselen på nytt.

Hastighetsgrenser

Svarene har headerne RateLimit og RateLimit-Policy og de eldre X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og prøv på nytt.

← uploads · API-referanse