Gå til indholdet
Sursa Developers

POST/v1/uploads

Start en multipart-upload

create_upload

Åbner en uploadsession for en stor fil (op til installationens grænse for multipart-upload, som standard 5 GB): navnet, indholdstypen, størrelsen og purpose, der angiver, hvad uploaden skal bruges til: card_file (POST /v1/cards), archive (POST /v1/cards/archive) eller import_attachment (en vedhæftet fil til et dokument i en brugerdefineret kilde). Svaret indeholder id (upl_ efterfulgt af 32 hexadecimale tegn), delstørrelsen part_size og antallet af dele part_count. Hver del undtagen den sidste er præcis part_size bytes (fra 5 til 100 MiB), og den sidste del er resten. En ufuldstændig upload lever i 24 timer (expires_at).

En filnavnsendelse uden for formålets formater returnerer 415 uploads.unsupported_format (en vedhæftet fil til import accepterer enhver endelse). En fil, der er større end installationens grænse eller organisationens samlede lagerplads i prisplanen, returnerer 413 uploads.too_large. Er der ikke nok lagerplads tilbage, når organisationens ufuldstændige uploads regnes med, returneres 402 limits.storage.

Delene går gennem Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) og krypteres med organisationens nøgle i fillageret; der er ingen direkte links til lageret. Kun den API-nøgle eller bruger, der oprettede uploaden, kan se og bruge den. Tilføjet i 1.62.0.

Autentificering

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

Headerparametre

  • Idempotency-Keystring

    Nøgle til et sikkert nyt forsøg på en skrivning: 1 til 255 printbare ASCII-tegn; en UUID v4 pr. logisk operation anbefales. Et nyt forsøg med samme nøgle inden for 24 timer udfører ikke operationen igen: det returnerer det gemte svar (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøgle med en anden metode, sti, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første anmodning stadig kører, 409 api.idempotency_in_progress med Retry-After: 1. Efter et 5xx- eller 429-svar frigives nøglen, og et nyt forsøg udfører operationen igen. Nøglen gælder for organisationen og den kaldende part (API-nøgle, bruger eller nøgle til en brugerdefineret kilde).

    length ≥ 1, length ≤ 255

Anmodningens brødtekst

application/json

Objekt: UploadCreate

  • filenamestringpåkrævet

    Filnavnet med filtypenavn; filtypenavnet bestemmer formatet.

    length ≥ 1, length ≤ 255

  • content_typestring

    Den angivne indholdstype (MIME); den sammenlignes med filens signatur.

    length ≤ 255

  • sizeinteger (int64)påkrævet

    Filens størrelse i byte.

    ≥ 1

  • purposeUploadPurposepåkrævet
  • sha256string

    Filens SHA-256, hvis den kendes på forhånd; complete sammenligner filens kontrolsum med den.

Svar

201Uploadsessionen er oprettet.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

  • Idempotency-Replayed

    true betyder, at svaret blev afspillet igen fra det gemte svar for denne Idempotency-Key: operationen blev ikke udført igen.

application/json

Objekt: Upload

  • idstringpåkrævet

    Uploadens id (upl_ efterfulgt af 32 hexadecimale tegn).

  • purposeUploadPurposepåkrævet
  • filenamestringpåkrævet

    Filnavnet (uden mapper).

  • content_typestringpåkrævet

    Den angivne indholdstype; tom, hvis den ikke er angivet.

  • sizeinteger (int64)påkrævet

    Filens størrelse i byte.

  • sha256string | nullpåkrævet

    Filens SHA-256, angivet ved oprettelsen eller ved complete; null, hvis den endnu ikke kendes.

  • statusUploadStatuspåkrævet
  • part_sizeinteger (int64)påkrævet

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

  • part_countintegerpåkrævet

    Antal dele.

    ≥ 1, ≤ 1000

  • parts_receivedintegerpåkrævet

    Antal modtagne dele.

    ≥ 0

  • partsarray of UploadPartpåkrævet

    De modtagne dele efter nummer (tom i svaret på POST /v1/uploads).

  • reject_reasonstring | nullpåkrævet

    Årsagen til afvisningen (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Listen kan blive udvidet; null, hvis uploaden ikke er afvist.

  • reject_detailsobject | nullpåkrævet

    Detaljer om afvisningen (filtypenavnet, det angivne og det registrerede format, kontrolsummer); null, hvis uploaden ikke er afvist.

  • created_atstring (date-time)påkrævet

    Tidspunkt for oprettelsen af uploaden.

  • expires_atstring (date-time)påkrævet

    Fristen for at afslutte uploaden og, når den er klar, for at bruge den.

  • completed_atstring (date-time) | nullpåkrævet

    Tidspunkt, hvor kontrollen blev afsluttet (ready eller rejected).

  • consumed_atstring (date-time) | nullpåkrævet

    Tidspunkt, hvor uploaden blev brugt (af et kort, et arkiv eller en import).

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

402Organisationen har nået en grænse i prisplanen (kort, lagerplads eller brugere). `error.details` indeholder `kind`, `limit` og `used`.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

413Anmodningens brødtekst overskrider den tilladte størrelse.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

415Filformatet understøttes ikke.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

  • Retry-After

    Antal sekunder, du skal vente, før du prøver anmodningen igen.

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← uploads · API-reference