Aller au contenu
Prevu3D

Miniatures de nœud

Un nœud de données (division, site, dossier, twin, et le reste de la hiérarchie) peut porter une image miniature. Cette page couvre le téléversement, le remplacement et la suppression de cette miniature, ainsi que le coût et la durée de vie de l’URL signée renvoyée lorsque vous la demandez.

Téléverser une miniature

Section intitulée « Téléverser une miniature »
MéthodeCheminDescription
POST/v1/nodes/{nodeId}/thumbnailInitier : renvoie un id de téléversement et une URL S3 présignée
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalizeFinaliser : applique l’image téléversée comme miniature du nœud
DELETE/v1/nodes/{nodeId}/thumbnailSupprimer : supprime la miniature actuelle

Les trois routes nécessitent write:hierarchy et sont marquées expérimentales. Voir Points de terminaison expérimentaux.

C’est la même forme initier/téléverser/finaliser utilisée par plusieurs autres points de terminaison de téléversement de la RealityConnect API. Voir la Référence : téléversement multipart partagé pour le mécanisme complet. Les miniatures de nœud sont le cas simple à un seul fichier de ce schéma : l’initiation ne prend aucun corps de requête et renvoie exactement une URL présignée, sans partNumber et sans point de terminaison de rafraîchissement. Faites un PUT de l’image vers cette URL, puis appelez finalize pour l’appliquer. Si l’URL expire avant que vous ne l’ayez utilisée, ré-initiez pour en obtenir une nouvelle ; il n’y a rien à rafraîchir.

DELETE /v1/nodes/{nodeId}/thumbnail est idempotent : elle renvoie 204 que le nœud ait eu une miniature ou non.

Formats acceptés et limites de taille

Section intitulée « Formats acceptés et limites de taille »

L’initiation ne prend aucun corps. Contrairement à certains autres flux de téléversement de l’API, vous ne déclarez pas de nom de fichier, de taille ou de type de contenu en amont. L’API ne documente ni n’impose elle-même de liste de formats d’image autorisés ni de taille de fichier maximale ; un fichier que le processeur d’image en aval ne peut pas décoder échoue à l’étape de finalisation plutôt qu’à l’étape du PUT. Traitez toute réponse non 204 de finalize comme « ce fichier n’a pas fonctionné » et remontez cette information à l’appelant, plutôt que de supposer que toute image que vous pouvez faire un PUT sera acceptée.

Récupérer une miniature

Section intitulée « Récupérer une miniature »

GET /v1/nodes/{id}/browse et GET /v1/nodes/search acceptent tous deux includeThumbnail=true (par défaut false). Lorsqu’il est activé, chaque nœud de la réponse obtient un champ thumbnailSignedUrl : null quand le nœud n’a pas de miniature, une URL signée quand il en a une. Voir Types de nœuds et hiérarchie pour le reste de la forme DataNode.

includeThumbnail vaut false par défaut car ce n’est pas gratuit : générer et signer une URL représente un travail supplémentaire par nœud, effectué pour chaque élément de la page, pas seulement pour ceux que l’appelant affiche réellement. Le demander sur un appel browse ou search déjà proche de sa limite de taille de page (20 pour browse, 50 pour search) revient à payer ce coût pour la page entière. Ne le demandez que sur la vue qui affiche réellement des images, pas sur un listing en masse ou une synchronisation d’arrière-plan de l’arborescence.

Durée de vie de l’URL signée

Section intitulée « Durée de vie de l’URL signée »

thumbnailSignedUrl est un lien présigné, et la RCAPI ne publie ni ne configure sa durée de validité. Traitez-la donc comme éphémère et opaque, pas comme un identifiant durable. Ne mettez pas en cache un thumbnailSignedUrl au-delà de la réponse qui l’a renvoyé. Si votre intégration met en cache des résultats de browse ou search pour les réafficher plus tard, récupérez-les à nouveau avec includeThumbnail=true pour obtenir une URL à jour plutôt que de rejouer une URL stockée : une URL stockée finira par ne plus se résoudre, servant un lien d’image mort sans aucun avertissement dans le reste de la réponse.

Les miniatures et la suppression douce

Section intitulée « Les miniatures et la suppression douce »

Supprimer un nœud en douceur (DELETE /v1/nodes/{nodeId}) le déplace vers la corbeille sans toucher à sa miniature. GET /v1/trash accepte le même includeThumbnail=true et renvoie le même thumbnailSignedUrl pour un nœud dans la corbeille que ce que browse et search auraient renvoyé avant sa suppression. Restaurer le nœud (PATCH /v1/nodes/{nodeId}/restore) le rend à nouveau consultable et recherchable avec sa miniature intacte ; rien n’a besoin d’être re-téléversé. Supprimer définitivement le nœud (DELETE /v1/nodes/{nodeId}/hard), ou laisser expirer la rétention de 30 jours de la corbeille, supprime la miniature avec tout le reste du nœud. Voir Ce que la suppression fait réellement, par ressource pour le modèle complet de suppression/restauration/purge.

Et ensuite ?

Section intitulée « Et ensuite ? »