Valeurs de métadonnées typées et pièces jointes

Les propriétés de métadonnées des objets métier (metadata sur GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) ne se limitent pas à de simples strings, nombres et booléens. Une valeur de propriété peut aussi être un objet tagué portant un champ spécial _p3d_type, utilisé pour représenter un lien externe ou une pièce jointe téléversée. Cette page documente cette union de valeurs et le flux d’upload derrière le type attachment.

---

L’union des valeurs de métadonnées

Chaque propriété à l’intérieur d’une section de métadonnées est l’une des suivantes :

Type de valeur	Forme
String simple	"A short text"
Nombre simple	42
Booléen simple	true
Lien externe	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Pièce jointe	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type est le discriminant : sa valeur littérale indique laquelle des deux formes taguées vous avez sous les yeux. Les deux formes taguées sont sinon de simples objets; aucun endpoint supplémentaire n’est nécessaire pour les lire, elles reviennent en ligne partout où des métadonnées sont renvoyées.

Attention

Seuls ces cinq types de valeur sont enregistrés. Un objet balisé avec tout autre _p3d_type est ignoré sans erreur : le PATCH renvoie tout de même 200, et la propriété est simplement absente de la réponse et des lectures suivantes.

Note

Les listes déroulantes sont définies sur un type d’actif, et les types d’actif sont en lecture seule via l’API : vous ne pouvez donc pas en créer ici. Vous pouvez en revanche en faire apparaître une : définissez l’assetTypeId d’un actif (à la création, ou avec PATCH /v1/twin/{contextId}/assets/{assetId}) sur un type d’actif qui en définit une, et cette propriété s’affiche comme liste déroulante dans RealityTwin. Via l’API, sa valeur est lue et écrite comme une simple chaîne.

{
  "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"
    }
  }
}

Lien externe (urn:primitive:obj:external-link)

Champ	Type	Remarques
url	string	La cible du lien.
text	string	Texte d’affichage du lien.
_p3d_type	string	Toujours urn:primitive:obj:external-link.

Un lien externe est autonome; définissez l’objet directement lors d’une écriture de métadonnées, sans upload requis.

Pièce jointe (urn:primitive:obj:attachment)

Champ	Type	Remarques
name	string	Nom de fichier d’origine.
id	string	Le fileId de la pièce jointe, obtenu via le flux d’upload ci-dessous.
_p3d_type	string	Toujours urn:primitive:obj:attachment.

Contrairement au lien externe, une valeur attachment référence un fichier qui doit d’abord exister. Le téléverser est une séquence d’appels distincte et en plusieurs étapes, couverte ci-dessous.

Joindre un fichier aux métadonnées

Obtenir un fichier référencé comme valeur attachment est une séquence en trois étapes : initier l’upload, téléverser les parties vers S3, le finaliser; puis utiliser l’identifiant de fichier renvoyé comme champ id d’une valeur attachment lors de votre prochaine écriture de métadonnées.

Méthode	Chemin	Scope	Objectif
POST	/v1/twin/{contextId}/object/attachments	write:asset	Initier un upload de pièce jointe
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Réémettre des URL de parties expirées
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	Finaliser l’upload
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Obtenir une URL de téléchargement signée
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Supprimer une pièce jointe

contextId est le twin, le site ou le brouillon auquel appartient la pièce jointe; le même identifiant que celui utilisé pour la recherche d’objets métier.

Attention

Les cinq endpoints de pièces jointes ci-dessus sont marqués comme expérimentaux dans la référence API et peuvent évoluer. Les endpoints de métadonnées GET/PATCH qu’ils alimentent ne le sont pas.

L’upload lui-même suit la même mécanique générique initiate → upload des parties → finalize utilisée ailleurs dans l’API (multipart, URL S3 présignées, renouvelables en cas d’expiration). Consultez la référence d’upload multipart partagée pour cette mécanique et son piège de numérotation des parties. Cette section couvre uniquement ce qui est spécifique aux pièces jointes.

Étape 1 : initier

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?…" }
  ]
}

Étape 2 : téléverser les parties

PUT chaque bloc vers son url présignée, en conservant l’ETag renvoyé pour chaque partie, exactement comme décrit dans la référence d’upload multipart partagée.

Étape 3 : finaliser

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
}

Étape 4 : référencer le fichier dans les métadonnées

Prenez le fileId de la réponse de finalisation et définissez-le comme id d’une valeur attachment lors de votre prochaine écriture de métadonnées :

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"
      }
    }
  }
}

Une écriture de métadonnées prend l’objet de métadonnées complet (sections et propriétés nouvelles, mises à jour et supprimées ensemble), et non un correctif d’une seule propriété. Incluez donc chaque section et propriété que vous souhaitez conserver en plus de la nouvelle référence attachment.

Relire les valeurs taguées

GET /v1/twin/{contextId}/object/{objectId}/metadata renvoie chaque propriété exactement telle qu’elle a été écrite : un string/nombre/booléen simple, ou l’un des deux objets tagués ci-dessus avec _p3d_type intact. Il n’y a pas d’étape de « résolution » séparée pour lire une valeur taguée; l’objet lui-même, y compris l’id de la pièce jointe, revient en ligne dans la réponse de métadonnées.

Pour obtenir les octets du fichier, transmettez cet id comme fileId à l’endpoint de téléchargement ci-dessous.

Télécharger et supprimer une pièce jointe

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

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

L’URL renvoyée est un lien CloudFront signé, valable environ 4 heures. Récupérez-en une nouvelle si elle expire.

Pour supprimer le fichier sous-jacent d’une pièce jointe :

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

Note

Supprimer le fichier ne retire pas automatiquement sa référence d’une propriété de métadonnées qui pointe vers lui. Effacez la référence via une écriture de métadonnées si vous ne voulez plus qu’elle apparaisse.

Limites des pièces jointes

Le stockage des pièces jointes repose sur la même allocation de stockage par organisation que tout autre fichier dans RealityConnect; il n’existe pas de « quota de pièces jointes » distinct.

Question	Réponse
Taille maximale d’une pièce jointe unique	Aucune limite de taille dédiée n’est appliquée. Le plafond pratique est l’espace de stockage restant de votre organisation.
Nombre maximal de pièces jointes par objet	Aucune limite de nombre dédiée n’est appliquée. Une section de métadonnées peut contenir un nombre quelconque de propriétés de type attachment.
Total par twin ou par organisation	Il n’existe pas de quota de pièces jointes distinct. Chaque pièce jointe est stockée comme un fichier ordinaire et compte dans l’allocation de stockage globale de votre organisation; le même compteur que celui utilisé par tout autre fichier téléversé. StorageLimitExceeded (voir Codes d’erreur) est renvoyé dès que l’utilisation dépasse le stockage alloué à votre organisation. Cette allocation dépend du plan souscrit ; il n’y a donc pas de chiffre unique à publier ici; consultez votre équipe de compte Prevu3D pour connaître le chiffre de votre organisation.
Types de fichiers acceptés	Tout mimeType que vous envoyez est accepté ; il n’y a pas de liste blanche à respecter.
Même fichier joint à plusieurs objets	Stocké une fois par upload, pas une fois par référence. Téléverser deux fois les mêmes octets (deux séquences initiate → finalize distinctes) crée deux fichiers stockés séparément; il n’y a pas de déduplication automatique. Pour joindre un même document partagé à plusieurs objets sans le stocker deux fois, téléversez-le une fois et réutilisez l’id renvoyé dans la valeur attachment de chaque objet plutôt que de le téléverser à nouveau.

Note

Les réponses ci-dessus sur la taille et le nombre décrivent ce que le chemin d’upload applique aujourd’hui, pas un plafond produit publié. Si votre intégration a besoin d’un chiffre ferme pour concevoir en amont (par exemple, joindre une photo à chaque asset en masse), confirmez les chiffres actuels auprès de l’équipe Prevu3D avant de vous engager sur une conception.

Et ensuite ?

• Référence d’upload multipart partagée pour la mécanique générique d’initiation/upload/finalisation.
• Rechercher des objets métier et des nœuds pour la façon dont contextId est résolu.
• Consultez la référence API pour les schémas complets de requête et de réponse par opération.