Valori di metadati tipizzati e allegati

Le proprietà di metadati degli oggetti business (metadata su GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) non sono limitate a semplici string, numeri e booleani. Un valore di proprietà può anche essere un oggetto taggato che porta un campo speciale _p3d_type, usato per rappresentare un link esterno o un allegato di file caricato. Questa pagina documenta questa unione di valori e il flusso di upload dietro il tipo attachment.

---

L’unione dei valori di metadati

Ogni proprietà all’interno di una sezione di metadati è una delle seguenti:

Tipo di valore	Forma
String semplice	"A short text"
Numero semplice	42
Booleano semplice	true
Link esterno	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Allegato	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type è il discriminatore: il suo valore letterale indica quale delle due forme taggate stai osservando. Entrambe le forme taggate sono altrimenti semplici oggetti: non serve alcun endpoint aggiuntivo per leggerle, tornano inline ovunque vengano restituiti i metadati.

Attenzione

Vengono salvati solo questi cinque tipi di valore. Un oggetto con tag con qualsiasi altro _p3d_type viene scartato senza errori: il PATCH restituisce comunque 200, e la proprietà semplicemente non compare nella risposta né nelle letture successive.

Nota

I menu a tendina sono definiti su un tipo di asset, e i tipi di asset sono di sola lettura tramite l’API, quindi qui non puoi creare un menu a tendina. Puoi però farne apparire uno: imposta l’assetTypeId di un asset (alla creazione, o con PATCH /v1/twin/{contextId}/assets/{assetId}) su un tipo di asset che ne definisce uno, e quella proprietà viene mostrata come menu a tendina in RealityTwin. Tramite l’API, il suo valore viene letto e scritto come una semplice stringa.

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

Link esterno (urn:primitive:obj:external-link)

Campo	Tipo	Note
url	string	La destinazione del link.
text	string	Testo visualizzato per il link.
_p3d_type	string	Sempre urn:primitive:obj:external-link.

Un link esterno è autonomo; imposta l’oggetto direttamente in una scrittura di metadati, senza alcun upload coinvolto.

Allegato (urn:primitive:obj:attachment)

Campo	Tipo	Note
name	string	Nome file originale.
id	string	Il fileId dell’allegato, ottenuto dal flusso di upload sottostante.
_p3d_type	string	Sempre urn:primitive:obj:attachment.

A differenza del link esterno, un valore attachment fa riferimento a un file che deve prima esistere. Caricarlo è una sequenza di chiamate separata e in più fasi, trattata di seguito.

Allegare un file ai metadati

Ottenere che un file venga referenziato come valore attachment è una sequenza in tre fasi: avviare l’upload, caricare le parti su S3, finalizzarlo; quindi usare l’id file restituito come campo id di un valore attachment nella successiva scrittura di metadati.

Metodo	Percorso	Ambito	Scopo
POST	/v1/twin/{contextId}/object/attachments	write:asset	Avviare un upload di allegato
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Riemettere URL delle parti scadute
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	Finalizzare l’upload
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Ottenere un URL di download firmato
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Rimuovere un allegato

contextId è il twin, il site o il draft a cui appartiene l’allegato; lo stesso id usato per la ricerca di oggetti business.

Attenzione

I cinque endpoint di allegato sopra elencati sono contrassegnati come sperimentali nel riferimento API e possono cambiare. Gli endpoint di metadati GET/PATCH che alimentano non lo sono.

L’upload stesso segue la stessa meccanica generica di avvio → caricamento delle parti → finalizzazione usata altrove nell’API (multipart, URL S3 presigned, rinnovabili in caso di scadenza). Consulta il riferimento condiviso per l’upload multipart per questa meccanica e la sua trappola sulla numerazione delle parti. Questa sezione copre solo ciò che è specifico degli allegati.

Fase 1: avvio

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

Fase 2: caricamento delle parti

Esegui PUT di ogni blocco verso il suo url presigned, conservando l’ETag restituito per ogni parte, esattamente come descritto nel riferimento condiviso per l’upload multipart.

Fase 3: finalizzazione

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
}

Fase 4: riferimento al file nei metadati

Prendi il fileId dalla risposta di finalizzazione e impostalo come id di un valore attachment nella successiva scrittura di metadati:

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 scrittura di metadati riceve l’intero oggetto di metadati (sezioni e proprietà nuove, aggiornate e rimosse insieme), non una patch di una singola proprietà. Includi quindi ogni sezione e proprietà che vuoi mantenere insieme al nuovo riferimento all’allegato.

Rileggere i valori taggati

GET /v1/twin/{contextId}/object/{objectId}/metadata restituisce ogni proprietà esattamente come è stata scritta: una string/numero/booleano semplice, oppure uno dei due oggetti taggati sopra con _p3d_type intatto. Non esiste una fase di “risoluzione” separata per leggere un valore taggato; l’oggetto stesso, incluso l’id dell’allegato, torna inline nella risposta dei metadati.

Per ottenere i byte del file, passa quell’id come fileId all’endpoint di download sottostante.

Scaricare e rimuovere un allegato

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

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

L’URL restituito è un link CloudFront firmato, valido per circa 4 ore. Richiedine uno nuovo se scade.

Per rimuovere il file sottostante di un allegato:

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

Nota

Eliminare il file non rimuove automaticamente il suo riferimento da nessuna proprietà di metadati che vi punti. Cancella il riferimento con una scrittura di metadati se non vuoi più che compaia.

Limiti degli allegati

L’archiviazione degli allegati utilizza la stessa allocazione di spazio di archiviazione per organizzazione di qualsiasi altro file in RealityConnect; non esiste una “quota allegati” separata.

Domanda	Risposta
Dimensione massima di un singolo allegato	Non viene applicato alcun limite di dimensione dedicato. Il limite pratico è lo spazio di archiviazione residuo della tua organizzazione.
Numero massimo di allegati per oggetto	Non viene applicato alcun limite di conteggio dedicato. Una sezione di metadati può contenere un numero qualsiasi di proprietà di tipo attachment.
Totale per twin o per organizzazione	Non esiste una quota allegati separata. Ogni allegato viene archiviato come file normale e conta ai fini dell’allocazione complessiva di archiviazione della tua organizzazione; lo stesso contatore usato da qualsiasi altro file caricato. StorageLimitExceeded (vedi Codici di errore) viene restituito non appena l’utilizzo supera lo spazio di archiviazione allocato alla tua organizzazione. Questa allocazione dipende dal piano, quindi non c’è un numero unico da pubblicare qui; verifica con il team account Prevu3D il valore per la tua organizzazione.
Tipi di file accettati	Qualsiasi mimeType tu invii viene accettato; non c’è una lista di tipi consentiti da rispettare.
Stesso file allegato a più oggetti	Viene archiviato una volta per caricamento, non una volta per riferimento. Caricare gli stessi byte due volte (due sequenze initiate → finalize separate) crea due file archiviati separatamente; non esiste alcuna deduplicazione automatica. Per allegare uno stesso documento condiviso a più oggetti senza archiviarlo due volte, caricalo una sola volta e riutilizza l’id restituito nel valore attachment di ciascun oggetto invece di ricaricarlo.

Nota

Le risposte sopra su dimensione e conteggio descrivono ciò che il percorso di caricamento applica oggi, non un limite di prodotto pubblicato. Se la tua integrazione ha bisogno di un numero certo su cui progettare (ad esempio, allegare una foto a ogni asset in blocco), conferma le cifre attuali con il team Prevu3D prima di impegnarti in una progettazione.

Cosa c’è dopo?

• Riferimento condiviso per l’upload multipart per la meccanica generica di avvio/upload/finalizzazione.
• Ricerca di oggetti business e nodi per come viene risolto contextId.
• Consulta il riferimento API per gli schemi completi di richiesta e risposta per ogni operazione.