Salta ai contenuti
Prevu3D

Miniature dei nodi

Un nodo dati (divisione, sito, cartella, twin e il resto della gerarchia) può avere un’immagine miniatura. Questa pagina copre il caricamento, la sostituzione e la rimozione di quella miniatura, oltre al costo e alla durata dell’URL firmato che ricevi quando la richiedi.

Caricare una miniatura

Sezione intitolata “Caricare una miniatura”
MetodoPercorsoDescrizione
POST/v1/nodes/{nodeId}/thumbnailAvvio: restituisce un id di caricamento e un URL S3 pre-firmato
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalizeFinalizzazione: applica l’immagine caricata come miniatura del nodo
DELETE/v1/nodes/{nodeId}/thumbnailRimozione: elimina la miniatura attuale

Tutte e tre richiedono write:hierarchy e sono contrassegnate come sperimentali. Consulta Endpoint sperimentali.

È la stessa forma avvio/caricamento/finalizzazione usata da diversi altri endpoint di caricamento della RealityConnect API. Consulta il Riferimento: caricamento multipart condiviso per il meccanismo completo. Le miniature dei nodi sono il caso semplice a file singolo di quel pattern: l’avvio non prende alcun corpo di richiesta e restituisce esattamente un URL pre-firmato, senza partNumber e senza endpoint di refresh. Esegui un PUT dell’immagine su quell’URL, poi chiama finalize per applicarla. Se l’URL scade prima che tu abbia caricato il file, avvia di nuovo per ottenerne uno nuovo, perché non c’è nulla da aggiornare.

DELETE /v1/nodes/{nodeId}/thumbnail è idempotente: restituisce 204 sia che il nodo avesse una miniatura sia che non l’avesse.

Formati accettati e limiti di dimensione

Sezione intitolata “Formati accettati e limiti di dimensione”

L’avvio non prende alcun corpo. A differenza di altri flussi di caricamento dell’API, non dichiari in anticipo nome del file, dimensione o tipo di contenuto. L’API stessa non documenta né impone una lista di formati immagine consentiti né una dimensione massima del file; un file che il processore di immagini a valle non riesce a decodificare fallisce alla finalizzazione, non al passaggio PUT. Tratta qualsiasi risposta diversa da 204 di finalize come “questo file non ha funzionato” e comunicalo al chiamante, invece di presumere che qualsiasi immagine che riesci a caricare con PUT venga accettata.

Recuperare una miniatura

Sezione intitolata “Recuperare una miniatura”

GET /v1/nodes/{id}/browse e GET /v1/nodes/search accettano entrambi includeThumbnail=true (predefinito false). Quando è impostato, ogni nodo nella risposta ottiene un campo thumbnailSignedUrl: null quando il nodo non ha una miniatura, un URL firmato quando ce l’ha. Consulta Tipi di nodo e gerarchia per il resto della forma DataNode.

includeThumbnail è false di default perché non è gratis: generare e firmare un URL è lavoro aggiuntivo per nodo, svolto per ogni elemento della pagina, non solo per quelli che il chiamante renderizza realmente. Richiederlo su una chiamata browse o search già vicina al proprio limite di dimensione pagina (20 per browse, 50 per search) significa pagare quel costo per l’intera pagina. Richiedilo solo sulla vista che effettivamente renderizza immagini, non su un elenco massivo o su una sincronizzazione in background dell’albero.

Durata dell’URL firmato

Sezione intitolata “Durata dell’URL firmato”

thumbnailSignedUrl è un link pre-firmato, e RCAPI non pubblica né configura per quanto tempo resta valido. Trattalo quindi come effimero e opaco, non come un identificatore duraturo. Non mettere in cache un thumbnailSignedUrl oltre la risposta che lo ha restituito. Se la tua integrazione mette in cache i risultati di browse o search per renderizzarli di nuovo in seguito, recuperali nuovamente con includeThumbnail=true per ottenere un URL aggiornato invece di riutilizzare uno memorizzato: un URL memorizzato prima o poi smetterà di risolversi, servendo un link immagine morto senza alcun avviso nel resto della risposta.

Miniature ed eliminazione reversibile

Sezione intitolata “Miniature ed eliminazione reversibile”

Eliminare un nodo in modo reversibile (DELETE /v1/nodes/{nodeId}) lo sposta nel cestino senza toccare la sua miniatura. GET /v1/trash accetta lo stesso includeThumbnail=true e restituisce per un nodo nel cestino lo stesso thumbnailSignedUrl che browse e search avrebbero restituito prima della sua eliminazione. Ripristinare il nodo (PATCH /v1/nodes/{nodeId}/restore) lo rende di nuovo esplorabile e ricercabile con la miniatura intatta; non serve ricaricare nulla. Eliminare definitivamente il nodo (DELETE /v1/nodes/{nodeId}/hard), o lasciare scadere i 30 giorni di conservazione nel cestino, rimuove la miniatura insieme a tutto il resto del nodo. Consulta Cosa fa davvero l’eliminazione, per risorsa per il modello completo di eliminazione/ripristino/eliminazione definitiva.

Cosa c’è dopo?

Sezione intitolata “Cosa c’è dopo?”