Miniaturas de nodo
Un nodo de datos (división, sitio, carpeta, twin y el resto de la jerarquía) puede tener una imagen de miniatura. Esta página cubre cómo subir, reemplazar y eliminar esa miniatura, y el costo y la vida útil de la URL firmada que recibes al solicitarla.
Subir una miniatura
Sección titulada «Subir una miniatura»| Método | Ruta | Descripción |
|---|---|---|
POST | /v1/nodes/{nodeId}/thumbnail | Iniciar: devuelve un id de subida y una URL de S3 firmada previamente |
POST | /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize | Finalizar: aplica la imagen subida como la miniatura del nodo |
DELETE | /v1/nodes/{nodeId}/thumbnail | Eliminar: elimina la miniatura actual |
Las tres requieren write:hierarchy y están marcadas como experimentales. Consulta Endpoints experimentales.
Esta es la misma forma iniciar/subir/finalizar que usan otros varios endpoints de subida de la RealityConnect API. Consulta la Referencia: subida multiparte compartida para el mecanismo completo. Las miniaturas de nodo son el caso simple de un solo archivo de ese patrón: iniciar no recibe cuerpo de solicitud y devuelve exactamente una URL firmada previamente, sin partNumber y sin endpoint de actualización. Haz un PUT de la imagen a esa URL y luego llama a finalize para aplicarla. Si la URL caduca antes de que subas el archivo, vuelve a iniciar para obtener una nueva, ya que no hay nada que actualizar.
DELETE /v1/nodes/{nodeId}/thumbnail es idempotente: devuelve 204 tanto si el nodo tenía una miniatura como si no.
Formatos aceptados y límites de tamaño
Sección titulada «Formatos aceptados y límites de tamaño»Iniciar no recibe cuerpo. A diferencia de otros flujos de subida de la API, no declaras un nombre de archivo, tamaño o tipo de contenido de antemano. La API en sí no documenta ni impone una lista de formatos de imagen permitidos ni un tamaño máximo de archivo; un archivo que el procesador de imágenes posterior no puede decodificar falla en la finalización, no en el paso de PUT. Trata cualquier respuesta que no sea 204 de finalize como “este archivo no funcionó” y comunícaselo a quien llama, en lugar de asumir que cualquier imagen que puedas subir con PUT será aceptada.
Recuperar una miniatura
Sección titulada «Recuperar una miniatura»GET /v1/nodes/{id}/browse y GET /v1/nodes/search aceptan ambos includeThumbnail=true (por defecto false). Cuando se activa, cada nodo de la respuesta obtiene un campo thumbnailSignedUrl: null cuando el nodo no tiene miniatura, una URL firmada cuando sí la tiene. Consulta Tipos de nodo y jerarquía para el resto de la forma de DataNode.
includeThumbnail es false por defecto porque no es gratis: generar y firmar una URL es trabajo adicional por nodo, que se realiza para cada elemento de la página, no solo para los que quien llama realmente muestra. Solicitarlo en una llamada browse o search que ya está cerca de su límite de tamaño de página (20 para browse, 50 para search) implica pagar ese costo por toda la página. Solicítalo solo en la vista que realmente muestra imágenes, no en un listado masivo o en una sincronización en segundo plano del árbol.
Vida útil de la URL firmada
Sección titulada «Vida útil de la URL firmada»thumbnailSignedUrl es un enlace firmado previamente, y RCAPI no publica ni configura cuánto tiempo permanece válido. Trátalo, por tanto, como algo efímero y opaco, no como un identificador duradero. No guardes en caché un thumbnailSignedUrl más allá de la respuesta que lo devolvió. Si tu integración guarda en caché resultados de browse o search para volver a mostrarlos más tarde, vuelve a solicitarlos con includeThumbnail=true para obtener una URL vigente en lugar de reutilizar una guardada: una URL guardada eventualmente dejará de resolverse, sirviendo un enlace de imagen muerto sin ninguna advertencia en el resto de la respuesta.
Miniaturas y eliminación suave
Sección titulada «Miniaturas y eliminación suave»Eliminar un nodo de forma suave (DELETE /v1/nodes/{nodeId}) lo mueve a la papelera sin tocar su miniatura. GET /v1/trash acepta el mismo includeThumbnail=true y devuelve el mismo thumbnailSignedUrl para un nodo en la papelera que el que browse y search habrían devuelto antes de que fuera eliminado. Restaurar el nodo (PATCH /v1/nodes/{nodeId}/restore) lo vuelve a hacer explorable y buscable con la miniatura intacta; no hace falta volver a subir nada. Eliminar el nodo de forma permanente (DELETE /v1/nodes/{nodeId}/hard), o dejar que caduquen los 30 días de retención en la papelera, elimina la miniatura junto con todo lo demás del nodo. Consulta Qué hace realmente eliminar, por recurso para el modelo completo de eliminación, restauración y purga.
¿Qué sigue?
Sección titulada «¿Qué sigue?»- Referencia: subida multiparte compartida para el mecanismo completo de iniciar/subir/finalizar.
- Tipos de nodo y jerarquía para la forma completa de
DataNodey la referencia de campos de browse/search. - Qué hace realmente eliminar, por recurso para el comportamiento de eliminación suave, restauración y purga en todos los recursos.