Getypeerde metadatawaarden en bijlagen

Metadata-eigenschappen van business objects (metadata op GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) zijn niet beperkt tot eenvoudige strings, getallen en booleans. Een eigenschapswaarde kan ook een getagd object zijn met een speciaal veld _p3d_type, gebruikt om een externe link of een geüploade bestandsbijlage weer te geven. Deze pagina documenteert die waarde-union en de uploadflow achter het attachment-type.

---

De metadatawaarde-union

Elke eigenschap binnen een metadatasectie is een van de volgende:

Soort waarde	Vorm
Eenvoudige string	"A short text"
Eenvoudig getal	42
Eenvoudige boolean	true
Externe link	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Bijlage	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type is de discriminator: de letterlijke waarde vertelt u welke van de twee getagde vormen u ziet. Beide getagde vormen zijn verder gewone objecten; er is geen extra endpoint nodig om ze te lezen, ze komen inline terug overal waar metadata wordt teruggegeven.

Opgepast

Alleen deze vijf soorten waarden worden opgeslagen. Een getagd object met een andere _p3d_type wordt zonder foutmelding genegeerd: de PATCH geeft nog steeds 200 terug, en de eigenschap ontbreekt gewoon in het antwoord en bij latere leesacties.

Opmerking

Dropdowns worden gedefinieerd op een assettype, en assettypen zijn via de API alleen-lezen, dus u kunt hier geen dropdown aanmaken. U kunt er wel een laten verschijnen: stel de assetTypeId van een asset (bij het aanmaken, of met PATCH /v1/twin/{contextId}/assets/{assetId}) in op een assettype dat er een definieert, en die eigenschap wordt in RealityTwin als dropdown getoond. Via de API wordt de waarde gelezen en geschreven als een gewone string.

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

Externe link (urn:primitive:obj:external-link)

Veld	Type	Opmerkingen
url	string	Het linkdoel.
text	string	Weergavetekst voor de link.
_p3d_type	string	Altijd urn:primitive:obj:external-link.

Een externe link is op zichzelf staand; stel het object direct in bij een metadata-schrijfactie, er is geen upload voor nodig.

Bijlage (urn:primitive:obj:attachment)

Veld	Type	Opmerkingen
name	string	Oorspronkelijke bestandsnaam.
id	string	De fileId van de bijlage, verkregen uit de uploadflow hieronder.
_p3d_type	string	Altijd urn:primitive:obj:attachment.

In tegenstelling tot de externe link verwijst een attachment-waarde naar een bestand dat eerst moet bestaan. Het uploaden ervan is een aparte, meerstaps aanroepreeks, hieronder behandeld.

Een bestand aan metadata koppelen

Ervoor zorgen dat een bestand als attachment-waarde wordt gerefereerd, is een reeks van drie stappen: de upload initiëren, de delen naar S3 uploaden, deze finaliseren; en daarna het geretourneerde bestands-id gebruiken als het id-veld van een attachment-waarde bij uw volgende metadata-schrijfactie.

Methode	Pad	Scope	Doel
POST	/v1/twin/{contextId}/object/attachments	write:asset	Een bijlage-upload initiëren
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Verlopen deel-URL’s opnieuw uitgeven
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	De upload finaliseren
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Een ondertekende download-URL ophalen
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Een bijlage verwijderen

contextId is de twin, site of draft waartoe de bijlage behoort; hetzelfde id dat u gebruikt voor het doorzoeken van business objects.

Opgepast

De vijf bovenstaande bijlage-endpoints zijn in de API-referentie gemarkeerd als experimenteel en kunnen wijzigen. De metadata-endpoints GET/PATCH die ze voeden, zijn dat niet.

De upload zelf volgt dezelfde generieke initiate → delen uploaden → finalize-mechaniek die ook elders in de API wordt gebruikt (multipart, presigned S3-URL’s, vernieuwbaar bij verlopen). Zie de gedeelde multipart-uploadreferentie voor die mechaniek en de valkuil rond deelnummering. Deze sectie behandelt alleen wat specifiek is voor bijlagen.

Stap 1: initiëren

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

Stap 2: de delen uploaden

Voer PUT uit voor elk deel naar de bijbehorende presigned url, en bewaar de geretourneerde ETag per deel, precies zoals beschreven in de gedeelde multipart-uploadreferentie.

Stap 3: finaliseren

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
}

Stap 4: het bestand refereren in metadata

Neem de fileId uit het finalize-antwoord en stel deze in als de id van een attachment-waarde bij uw volgende metadata-schrijfactie:

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

Een metadata-schrijfactie neemt het volledige metadata-object aan (nieuwe, bijgewerkte en verwijderde secties en eigenschappen samen), niet een patch van één eigenschap. Neem daarom elke sectie en eigenschap op die u wilt behouden, samen met de nieuwe attachment-referentie.

Getagde waarden terug lezen

GET /v1/twin/{contextId}/object/{objectId}/metadata geeft elke eigenschap exact terug zoals deze werd geschreven: een eenvoudige string/getal/boolean, of een van de twee getagde objecten hierboven met intacte _p3d_type. Er is geen aparte “resolutie”-stap voor het lezen van een getagde waarde; het object zelf, inclusief het id van de bijlage, komt inline terug in het metadata-antwoord.

Om bij de bytes van het bestand te komen, geeft u dat id als fileId door aan het download-endpoint hieronder.

Een bijlage downloaden en verwijderen

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

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

De geretourneerde URL is een ondertekende CloudFront-link, ongeveer 4 uur geldig. Vraag een nieuwe aan als deze verloopt.

Om het onderliggende bestand van een bijlage te verwijderen:

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

Opmerking

Het verwijderen van het bestand verwijdert niet automatisch de referentie ervan uit een metadata-eigenschap die ernaar verwijst. Wis de referentie met een metadata-schrijfactie als u niet meer wilt dat deze verschijnt.

Limieten voor bijlagen

Opslag voor bijlagen gebruikt dezelfde opslagtoewijzing per organisatie als elk ander bestand in RealityConnect; er is geen aparte “bijlagequota”.

Vraag	Antwoord
Maximale grootte van één bijlage	Er wordt geen specifieke groottelimiet gehandhaafd. De praktische bovengrens is de resterende opslagruimte van uw organisatie.
Maximaal aantal bijlagen per object	Er wordt geen specifieke aantalslimiet gehandhaafd. Een metadatasectie kan een willekeurig aantal attachment-eigenschappen bevatten.
Totaal per twin of per organisatie	Er is geen aparte bijlagequota. Elke bijlage wordt opgeslagen als een gewoon bestand en telt mee voor de totale opslagtoewijzing van uw organisatie; dezelfde teller die elk ander geüpload bestand gebruikt. StorageLimitExceeded (zie Foutcodes) wordt geretourneerd zodra het gebruik de aan uw organisatie toegewezen opslag overschrijdt. Die toewijzing is planafhankelijk, dus er is hier geen eenduidig getal te publiceren; neem contact op met uw Prevu3D-accountteam voor het getal van uw organisatie.
Geaccepteerde bestandstypen	Elke mimeType die u verstuurt wordt geaccepteerd; er is geen toegestane lijst waaraan moet worden voldaan.
Hetzelfde bestand aan meerdere objecten gekoppeld	Wordt eenmaal per upload opgeslagen, niet eenmaal per referentie. Dezelfde bytes tweemaal uploaden (twee afzonderlijke initiate → finalize-reeksen) creëert twee afzonderlijk opgeslagen bestanden; er is geen automatische deduplicatie. Om hetzelfde gedeelde document aan meerdere objecten te koppelen zonder het dubbel op te slaan, uploadt u het eenmaal en hergebruikt u de geretourneerde id in de attachment-waarde van elk object in plaats van opnieuw te uploaden.

Opmerking

De bovenstaande antwoorden over grootte en aantal beschrijven wat het huidige uploadpad afdwingt, niet een gepubliceerde productlimiet. Als uw integratie een vast getal nodig heeft om op te ontwerpen (bijvoorbeeld het in bulk koppelen van een foto aan elk asset), bevestig dan de actuele cijfers bij het Prevu3D-team voordat u zich vastlegt op een ontwerp.

Wat is de volgende stap?

• Gedeelde multipart-uploadreferentie voor de generieke initiate/upload/finalize-mechaniek.
• Business objects en nodes doorzoeken voor hoe contextId wordt herleid.
• Zie de API-referentie voor volledige request- en response-schema’s per operatie.