Valores de metadatos tipados y archivos adjuntos

Las propiedades de metadatos de los objetos de negocio (metadata en GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) no se limitan a strings, números y booleanos simples. Un valor de propiedad también puede ser un objeto etiquetado que lleva un campo especial _p3d_type, usado para representar un enlace externo o un archivo adjunto subido. Esta página documenta esa unión de valores y el flujo de subida detrás del tipo attachment.

---

La unión de valores de metadatos

Cada propiedad dentro de una sección de metadatos es una de las siguientes:

Tipo de valor	Forma
String simple	"A short text"
Número simple	42
Booleano simple	true
Enlace externo	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Adjunto	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type es el discriminador: su valor literal indica cuál de las dos formas etiquetadas estás viendo. Ambas formas etiquetadas son, por lo demás, objetos simples: no se necesita ningún endpoint adicional para leerlas, vuelven en línea dondequiera que se devuelvan metadatos.

Precaución

Solo se guardan estos cinco tipos de valor. Un objeto etiquetado con cualquier otro _p3d_type se descarta sin error: el PATCH igualmente devuelve 200, y la propiedad simplemente no aparece en la respuesta ni en lecturas posteriores.

Nota

Los desplegables se definen en un tipo de activo, y los tipos de activo son de solo lectura a través de la API, así que no puedes crear un desplegable aquí. Sí puedes hacer que aparezca uno: asigna el assetTypeId de un activo (al crearlo, o con PATCH /v1/twin/{contextId}/assets/{assetId}) a un tipo de activo que defina uno, y esa propiedad se muestra como desplegable en RealityTwin. A través de la API, su valor se lee y se escribe como una cadena simple.

{
  "Section name": {
    "name": "A short text",
    "numeric value": 42,
    "toggle name": true,
    "documentation link": {
      "url": "https://doc.prevu3d.com/",
      "text": "https://doc.prevu3d.com/",
      "_p3d_type": "urn:primitive:obj:external-link"
    },
    "landing image": {
      "name": "prevu_logo.jpg",
      "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
      "_p3d_type": "urn:primitive:obj:attachment"
    }
  }
}

Enlace externo (urn:primitive:obj:external-link)

Campo	Tipo	Notas
url	string	El destino del enlace.
text	string	Texto para mostrar del enlace.
_p3d_type	string	Siempre urn:primitive:obj:external-link.

Un enlace externo es autónomo: define el objeto directamente en una escritura de metadatos, sin subida involucrada.

Adjunto (urn:primitive:obj:attachment)

Campo	Tipo	Notas
name	string	Nombre de archivo original.
id	string	El fileId del adjunto, obtenido con el flujo de subida de abajo.
_p3d_type	string	Siempre urn:primitive:obj:attachment.

A diferencia del enlace externo, un valor attachment referencia un archivo que debe existir primero. Subirlo es una secuencia de llamadas separada y de varios pasos, que se cubre a continuación.

Adjuntar un archivo a los metadatos

Conseguir que un archivo se referencie como valor attachment es una secuencia de tres pasos: iniciar la subida, subir las partes a S3 y finalizarla; luego usa el id de archivo devuelto como el campo id de un valor attachment en tu próxima escritura de metadatos.

Método	Ruta	Alcance	Propósito
POST	/v1/twin/{contextId}/object/attachments	write:asset	Iniciar una subida de adjunto
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Reemitir URL de partes expiradas
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	Finalizar la subida
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Obtener una URL de descarga firmada
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Eliminar un adjunto

contextId es el twin, sitio o borrador al que pertenece el adjunto: el mismo id que usas para la búsqueda de objetos de negocio.

Precaución

Los cinco endpoints de adjuntos anteriores están marcados como experimentales en la referencia de la API y pueden cambiar. Los endpoints de metadatos GET/PATCH a los que alimentan no lo están.

La subida en sí sigue la misma mecánica genérica de iniciar → subir partes → finalizar usada en otras partes de la API (multipart, URL de S3 pre-firmadas, renovables si expiran). Consulta la referencia de subida multipart compartida para esa mecánica y su trampa de numeración de partes. Esta sección cubre solo lo específico de los adjuntos.

Paso 1: iniciar

POST {api_url}/v1/twin/{contextId}/object/attachments
Authorization: Bearer {access_token}
Content-Type: application/json

{ "fileName": "prevu_logo.jpg", "fileSize": 84213, "mimeType": "image/jpeg" }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "parts": 1,
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" }
  ]
}

Paso 2: subir las partes

Haz PUT de cada fragmento a su url pre-firmada, guardando el ETag devuelto por cada parte, exactamente como se describe en la referencia de subida multipart compartida.

Paso 3: finalizar

POST {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/finalize
Authorization: Bearer {access_token}
Content-Type: application/json

{ "parts": [ { "partNumber": 1, "etag": "\"a1b2c3d4e5f6\"" } ] }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "fileName": "prevu_logo.jpg",
  "size": 84213
}

Paso 4: referenciar el archivo en los metadatos

Toma el fileId de la respuesta de finalización y colócalo como el id de un valor attachment en tu próxima escritura de metadatos:

PATCH {api_url}/v1/twin/{contextId}/object/{objectId}/metadata
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "metadata": {
    "Section name": {
      "landing image": {
        "name": "prevu_logo.jpg",
        "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
        "_p3d_type": "urn:primitive:obj:attachment"
      }
    }
  }
}

Una escritura de metadatos toma el objeto de metadatos completo (secciones y propiedades nuevas, actualizadas y eliminadas juntas), no un parche de una sola propiedad. Incluye por tanto cada sección y propiedad que quieras conservar junto con la nueva referencia de adjunto.

Leer los valores etiquetados de vuelta

GET /v1/twin/{contextId}/object/{objectId}/metadata devuelve cada propiedad exactamente como se escribió: un string/número/booleano simple, o uno de los dos objetos etiquetados anteriores con _p3d_type intacto. No hay un paso de “resolución” separado para leer un valor etiquetado: el objeto en sí, incluyendo el id del adjunto, vuelve en línea en la respuesta de metadatos.

Para obtener los bytes del archivo, pasa ese id como fileId al endpoint de descarga de abajo.

Descargar y eliminar un adjunto

GET {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/download
Authorization: Bearer {access_token}

{ "url": "https://d111111abcdef8.cloudfront.net/…" }

La URL devuelta es un enlace de CloudFront firmado, válido durante aproximadamente 4 horas. Obtén uno nuevo si expira.

Para eliminar el archivo subyacente de un adjunto:

DELETE {api_url}/v1/twin/{contextId}/object/attachments/{fileId}
Authorization: Bearer {access_token}

Nota

Eliminar el archivo no quita automáticamente su referencia de ninguna propiedad de metadatos que apunte a él. Borra la referencia con una escritura de metadatos si ya no quieres que aparezca.

Límites de los adjuntos

El almacenamiento de adjuntos usa la misma asignación de almacenamiento por organización que cualquier otro archivo en RealityConnect: no existe una “cuota de adjuntos” independiente.

Pregunta	Respuesta
Tamaño máximo de un solo adjunto	No se aplica un límite de tamaño dedicado. El límite práctico es el espacio de almacenamiento restante de tu organización.
Número máximo de adjuntos por objeto	No se aplica un límite de cantidad dedicado. Una sección de metadatos puede contener cualquier número de propiedades de tipo attachment.
Total por twin o por organización	No existe una cuota de adjuntos independiente. Cada adjunto se almacena como un archivo normal y cuenta para la asignación de almacenamiento global de tu organización, el mismo contador que usa cualquier otro archivo subido. StorageLimitExceeded (consulta Códigos de error) se devuelve en cuanto el uso supera el almacenamiento asignado a tu organización. Esa asignación depende del plan, así que no hay una cifra única que publicar aquí: consulta con tu equipo de cuenta de Prevu3D para conocer la cifra de tu organización.
Tipos de archivo aceptados	Se acepta cualquier mimeType que envíes; no hay una lista de tipos permitidos que cumplir.
Mismo archivo adjuntado a varios objetos	Se almacena una vez por subida, no una vez por referencia. Subir los mismos bytes dos veces (dos secuencias initiate → finalize independientes) crea dos archivos almacenados por separado: no hay deduplicación automática. Para adjuntar un mismo documento compartido a varios objetos sin almacenarlo dos veces, súbelo una vez y reutiliza el id devuelto en el valor attachment de cada objeto en lugar de volver a subirlo.

Nota

Las respuestas anteriores sobre tamaño y cantidad describen lo que aplica hoy la ruta de subida, no un límite de producto publicado. Si tu integración necesita una cifra firme para diseñar en torno a ella (por ejemplo, adjuntar una foto a cada activo de forma masiva), confirma las cifras actuales con el equipo de Prevu3D antes de comprometerte con un diseño.

¿Qué sigue?

• Referencia de subida multipart compartida para la mecánica genérica de iniciar/subir/finalizar.
• Búsqueda de objetos de negocio y nodos para cómo se resuelve contextId.
• Consulta la referencia de la API para ver los esquemas completos de solicitud y respuesta de cada operación.