Referencia: subida multiparte compartida

Varios endpoints de subida de la API de RealityConnect comparten el mismo patrón subyacente: iniciar la subida, subir (PUT) el archivo directamente a una o varias URL prefirmadas y luego finalizarla. Esta página es la referencia compartida para ese patrón, su regla de numeración de partes, y cómo actualizar, reanudar y monitorear una subida en curso. Enlaza aquí desde cualquier guía específica de un endpoint en lugar de repetir el mecanismo.

Qué endpoints usan este patrón

Flujo	Iniciar	Finalizar	¿Dividido en partes?	¿Endpoint de actualización?
Subidas a Data Bundle	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	Sí	Sí
Adjuntos de objeto	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	Sí	Sí
Archivos de sitio	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	Sí	No
Modelos de la Asset Library	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	No (un solo archivo)	No
Miniaturas de nodo	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	No (un solo archivo)	No

El patrón iniciar, subir, finalizar

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

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + URL(s) prefirmada(s)
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (con los ETag)
  RCAPI-->>Client: subida completada

Iniciar: llama al endpoint de inicio del flujo con el nombre y el tamaño del archivo (y cualquier campo específico del flujo, como el type de un archivo de Data Bundle). La respuesta devuelve un identificador para finalizar, y una o varias url de S3 prefirmadas a las que hacer PUT del archivo.
Subir: haz PUT de los bytes del archivo directamente a la(s) URL devuelta(s). No se envía cabecera Authorization en estas solicitudes; la URL ya está firmada. Guarda la cabecera de respuesta ETag de cada PUT.
Finalizar: llama al endpoint de finalización del flujo con el o los ETag recopilados para completar la subida.

Los modelos de la Asset Library y las miniaturas de nodo actualmente solo aceptan un único archivo en un solo PUT, por lo que hay una URL, un ETag, y ningún partNumber. Trátalos como el caso simple de una sola parte del mismo patrón.

Numeración de partes: `partNumber` frente a `startIndex`

Esto se aplica a los dos flujos que admiten actualización.

Ejemplo práctico. Iniciar devuelve 3 partes:

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

Para actualizar a partir de partNumber: 2, resta 1 y llama a actualizar con startIndex = 1:

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

La respuesta refleja 1 en startIndex, y sus urls vuelven a llevar partNumber de base 1 a partir de 2:

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

Pasar partNumber sin modificar (2 en lugar de 1) como startIndex saltaría la parte 2 y solo actualizaría a partir de la parte 3.

Actualizar URL firmadas caducadas durante la subida

Las URL PUT prefirmadas caducan. Si una subida se prolonga y el PUT de una parte empieza a devolver 403, llama al endpoint de actualización para la parte en la que te quedaste (como startIndex = partNumber - 1). Actualizar devuelve URL nuevas para esa parte y todas las siguientes, así que no necesitas actualizar cada parte por separado, y el archivo no necesita volver a iniciarse.

La actualización está disponible para:

Subidas a Data Bundle: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
Adjuntos de objeto: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

Los archivos de sitio, los modelos de la Asset Library y las miniaturas de nodo no tienen endpoint de actualización. Si una URL caduca a mitad de una subida en uno de estos flujos, vuelve a iniciar el archivo para obtener una URL nueva.

Reanudar una subida parcial y seguir el progreso

Cómo reanudar y cómo comprobar el progreso depende del flujo:

Las subidas a Data Bundle siguen el progreso a nivel de sesión. Lista las sesiones de subida de un bundle (GET /v1/bundles/{bundleId}/upload-sessions) y compara finalizedFileCount con expectedFileCount. Para reanudar, inicia y finaliza únicamente los archivos que aún no se han completado, usando el type y el fileName que todavía no aparecen como finalizados.
Los adjuntos de objeto, archivos de sitio, modelos de la Asset Library y miniaturas de nodo son operaciones de un solo archivo, sin sesión ni lista que consultar: el progreso es simplemente si la finalización ya se completó para el fileId (o uploadId) recibido. Los modelos de la Asset Library además exponen esto en el propio campo status del modelo, que se mantiene en uploading hasta que se completa la finalización. Para reanudar cualquiera de estos flujos tras una interrupción, conserva el identificador recibido al iniciar y continúa subiendo las partes restantes (actualizando las URL si es necesario, cuando esté disponible), o vuelve a iniciar si el identificador o sus URL ya no se pueden usar.

Límites de almacenamiento y volver a subir un archivo existente

Iniciar una subida puede rechazarse antes de enviar ningún byte si la solicitud en sí no es válida, lo más habitual es StorageLimitExceeded cuando ya se ha superado la cuota de almacenamiento de la organización, o FileAlreadyExists al volver a subir un archivo que ya existe con la misma identidad. Son códigos de error con nombre en el cuerpo de la respuesta, catalogados con su código de estado exacto por endpoint en Códigos de error: Cargas de archivos.

¿Qué sigue?

Códigos de error para la lista completa de códigos con nombre, incluidos StorageLimitExceeded y FileAlreadyExists por endpoint.
Subir datos a un Data Bundle para el ejemplo práctico más completo de este patrón, incluida una subida por lotes reanudable.