Referentie: gedeelde multipart-upload

Meerdere upload-endpoints van de RealityConnect API delen hetzelfde onderliggende patroon: de upload initiëren, het bestand rechtstreeks uploaden (PUT) naar een of meer presigned URL’s, en het vervolgens voltooien. Deze pagina is de gedeelde referentie voor dat patroon, de regel voor deelnummering, en hoe u een upload vernieuwt, hervat en de voortgang volgt. Verwijs hiernaar vanuit elke endpoint-specifieke gids in plaats van het mechanisme te herhalen.

Welke endpoints dit patroon gebruiken

Flow	Initiëren	Voltooien	Opgedeeld in delen?	Refresh-endpoint?
Data Bundle-uploads	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	Ja	Ja
Objectbijlagen	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	Ja	Ja
Sitebestanden	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	Ja	Nee
Asset Library-modellen	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	Nee (één bestand)	Nee
Node-miniaturen	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	Nee (één bestand)	Nee

Het initiëren-uploaden-voltooien-patroon

sequenceDiagram
  participant Client as Client
  participant RCAPI as RCAPI
  participant S3 as S3

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + presigned URL('s)
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (met ETags)
  RCAPI-->>Client: upload voltooid

Initiëren: roep het initiëren-endpoint van de flow aan met de naam en grootte van het bestand (en eventuele flow-specifieke velden, zoals het type van een Data Bundle-bestand). De response geeft een identifier terug om te voltooien, plus een of meer presigned S3-url’s om het bestand naartoe te PUT-en.
Uploaden: PUT de bytes van het bestand rechtstreeks naar de geretourneerde URL(‘s). Bij deze requests wordt geen Authorization-header meegestuurd; de URL is al ondertekend. Bewaar de ETag-responseheader van elke PUT.
Voltooien: roep het voltooien-endpoint van de flow aan met de verzamelde ETag(‘s) om de upload af te ronden.

Asset Library-modellen en node-miniaturen accepteren momenteel slechts één bestand in één PUT, dus er is één URL, één ETag, en geen partNumber. Beschouw deze twee als het eenvoudige, uit één deel bestaande geval van hetzelfde patroon.

Deelnummering: `partNumber` versus `startIndex`

Dit geldt voor de twee flows die refresh ondersteunen.

Uitgewerkt voorbeeld. Initiëren geeft 3 delen terug:

{
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" },
    { "partNumber": 2, "url": "https://s3…/part-2?…" },
    { "partNumber": 3, "url": "https://s3…/part-3?…" }
  ]
}

Om te vernieuwen vanaf partNumber: 2, trekt u er 1 van af en roept u refresh aan met startIndex = 1:

GET {api_url}/.../refresh/1

De response geeft 1 terug in startIndex, en de urls bevatten opnieuw op 1 gebaseerde partNumber’s, beginnend bij 2:

{ "startIndex": 1, "urls": [ { "partNumber": 2, "url": "…" }, { "partNumber": 3, "url": "…" } ] }

Als u partNumber ongewijzigd (2 in plaats van 1) als startIndex doorgeeft, wordt deel 2 overgeslagen en wordt alleen vanaf deel 3 vernieuwd.

Verlopen presigned URL’s tijdens de upload vernieuwen

Presigned PUT-URL’s verlopen. Als een upload lang duurt en de PUT van een deel 403 begint terug te geven, roept u het refresh-endpoint aan voor het deel waar u gebleven was (als startIndex = partNumber - 1). Refresh geeft nieuwe URL’s terug voor dat deel en elk deel daarna, zodat u niet elk deel afzonderlijk hoeft te vernieuwen, en het bestand hoeft niet opnieuw te worden geïnitieerd.

Refresh is beschikbaar voor:

Data Bundle-uploads: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
Objectbijlagen: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

Sitebestanden, Asset Library-modellen en node-miniaturen hebben geen refresh-endpoint. Verloopt bij een van deze flows een URL halverwege de upload, initieer het bestand dan opnieuw om een nieuwe URL te krijgen.

Een gedeeltelijke upload hervatten en de voortgang volgen

Hoe u hervat en de voortgang controleert, hangt af van de flow:

Data Bundle-uploads volgen de voortgang op sessieniveau. Lijst de upload-sessies van een bundle op (GET /v1/bundles/{bundleId}/upload-sessions) en vergelijk finalizedFileCount met expectedFileCount. Om te hervatten, initieert en voltooit u alleen de bestanden die nog niet zijn voltooid, aan de hand van het type en de fileName die nog niet als voltooid verschijnen.
Objectbijlagen, sitebestanden, Asset Library-modellen en node-miniaturen zijn bewerkingen met één bestand, zonder sessie of lijst om te raadplegen. De voortgang is simpelweg of het voltooien al is gelukt voor de ontvangen fileId (of uploadId). Bij Asset Library-modellen komt dit ook tot uiting in het status-veld van het model zelf, dat uploading blijft totdat het voltooien is afgerond. Om een van deze flows te hervatten na een onderbreking, bewaart u de identifier die u bij het initiëren hebt gekregen en gaat u door met het uploaden van de resterende delen (waarbij u URL’s vernieuwt indien nodig, waar beschikbaar), of initieert u opnieuw als de identifier of de URL’s niet meer bruikbaar zijn.

Opslaglimieten en opnieuw uploaden van een bestaand bestand

Het initiëren van een upload kan al worden geweigerd voordat er ook maar één byte is verstuurd, als de aanvraag zelf ongeldig is, meestal StorageLimitExceeded wanneer de opslagquota van de organisatie al is overschreden, of FileAlreadyExists bij het opnieuw uploaden van een bestand dat al onder dezelfde identiteit bestaat. Dit zijn benoemde foutcodes in de responsebody, gecatalogiseerd met hun exacte statuscode per endpoint in Foutcodes: Bestandsuploads.

Wat is de volgende stap?

Foutcodes voor de volledige lijst van benoemde codes, inclusief StorageLimitExceeded en FileAlreadyExists per endpoint.
Data uploaden naar een Data Bundle voor het meest uitgewerkte voorbeeld van dit patroon, inclusief een hervatbare batch-upload.