Référence : téléversement multipart partagé

Plusieurs endpoints de téléversement de la RealityConnect API partagent le même schéma sous-jacent : initier le téléversement, téléverser (PUT) le fichier directement vers une ou plusieurs URL présignées, puis le finaliser. Cette page est la référence partagée pour ce schéma, sa règle de numérotation des parties, ainsi que la réémission, la reprise et le suivi d’un téléversement. Pointez vers cette page depuis tout guide spécifique à un endpoint plutôt que de répéter le mécanisme.

Quels endpoints utilisent ce schéma

Flux	Initier	Finaliser	Découpé en parties ?	Endpoint de réémission ?
Téléversements de Data Bundle	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	Oui	Oui
Pièces jointes d’objet	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	Oui	Oui
Fichiers de site	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	Oui	Non
Modèles de la bibliothèque d’actifs	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	Non (un seul fichier)	Non
Miniatures de nœud	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	Non (un seul fichier)	Non

Le schéma initier, téléverser, finaliser

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

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + URL(s) présignée(s)
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (avec les ETag)
  RCAPI-->>Client: téléversement terminé

Initier : appelez l’endpoint d’initiation du flux avec le nom et la taille du fichier (ainsi que les champs propres au flux, comme le type d’un fichier de Data Bundle). La réponse renvoie un identifiant pour finaliser, ainsi qu’une ou plusieurs url S3 présignées vers lesquelles envoyer le fichier en PUT.
Téléverser : envoyez les octets du fichier directement en PUT vers la ou les URL renvoyées. Aucun en-tête Authorization n’est envoyé sur ces requêtes ; l’URL est déjà signée. Conservez l’en-tête de réponse ETag de chaque PUT.
Finaliser : appelez l’endpoint de finalisation du flux avec le ou les ETag collectés pour terminer le téléversement.

Les modèles de la bibliothèque d’actifs et les miniatures de nœud n’acceptent actuellement qu’un seul fichier en un seul PUT : il n’y a donc qu’une URL, un ETag, et aucun partNumber. Considérez ces deux flux comme le cas simple, à une seule partie, du même schéma.

Numérotation des parties : `partNumber` vs `startIndex`

Cela concerne les deux flux qui prennent en charge la réémission.

Exemple détaillé. L’initiation renvoie 3 parties :

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

Pour réémettre à partir de partNumber: 2, soustrayez 1 et appelez la réémission avec startIndex = 1 :

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

La réponse renvoie 1 dans startIndex, et ses urls portent à nouveau des partNumber basés sur 1, à partir de 2 :

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

Passer partNumber sans le modifier (2 au lieu de 1) comme startIndex sauterait la partie 2 et ne réémettrait qu’à partir de la partie 3.

Réémettre des URL présignées expirées en cours de téléversement

Les URL PUT présignées expirent. Si un téléversement dure longtemps et que le PUT d’une partie commence à renvoyer 403, appelez l’endpoint de réémission pour la partie où vous vous êtes arrêté (sous la forme startIndex = partNumber - 1). La réémission renvoie des URL fraîches pour cette partie et toutes les suivantes ; inutile de réémettre chaque partie individuellement, et le fichier n’a pas besoin d’être réinitié.

La réémission est disponible pour :

Téléversements de Data Bundle : GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
Pièces jointes d’objet : GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

Les fichiers de site, les modèles de la bibliothèque d’actifs et les miniatures de nœud n’ont pas d’endpoint de réémission. Si une URL expire en cours de téléversement sur l’un de ces flux, réinitiez le fichier pour obtenir une URL fraîche.

Reprendre un téléversement partiel et suivre la progression

La façon de reprendre et de vérifier la progression dépend du flux :

Les téléversements de Data Bundle suivent la progression au niveau de la session. Listez les sessions de téléversement d’un bundle (GET /v1/bundles/{bundleId}/upload-sessions) et comparez finalizedFileCount à expectedFileCount. Pour reprendre, initiez et finalisez uniquement les fichiers qui ne sont pas encore terminés, en repérant le type et le fileName qui n’apparaissent pas encore comme finalisés.
Les pièces jointes d’objet, fichiers de site, modèles de la bibliothèque d’actifs et miniatures de nœud sont des opérations à fichier unique, sans session ni liste à consulter : la progression consiste simplement à savoir si la finalisation a réussi pour le fileId (ou uploadId) reçu. Pour les modèles de la bibliothèque d’actifs, cela se reflète aussi dans le champ status du modèle, qui reste à uploading jusqu’à ce que la finalisation soit terminée. Pour reprendre l’un de ces flux après une interruption, conservez l’identifiant renvoyé par l’initiation et continuez à téléverser les parties restantes (en réémettant les URL si besoin, lorsque c’est possible), ou réinitiez si l’identifiant ou ses URL ne sont plus utilisables.

Limites de stockage et retéléversement d’un fichier existant

L’initiation d’un téléversement peut être rejetée avant même l’envoi du moindre octet si la requête elle-même est invalide, le plus souvent StorageLimitExceeded lorsque le quota de stockage de l’organisation est déjà dépassé, ou FileAlreadyExists lors d’un retéléversement par-dessus un fichier qui existe déjà sous la même identité. Ce sont des codes d’erreur nommés dans le corps de la réponse, répertoriés avec leur code de statut exact par endpoint dans Codes d’erreur : Uploads de fichiers.

Et ensuite ?

Codes d’erreur pour la liste complète des codes nommés, y compris StorageLimitExceeded et FileAlreadyExists par endpoint.
Téléverser des données vers un Data Bundle pour l’exemple le plus complet de ce schéma, incluant un téléversement par lot reprenable.