Typisierte Metadatenwerte und Anhänge

Metadaten-Eigenschaften von Business-Objekten (metadata unter GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) sind nicht auf einfache Strings, Zahlen und Booleans beschränkt. Ein Eigenschaftswert kann auch ein getaggtes Objekt sein, das ein spezielles Feld _p3d_type trägt und einen externen Link oder einen hochgeladenen Datei-Anhang darstellt. Diese Seite dokumentiert diese Werte-Union und den Upload-Ablauf hinter dem Attachment-Typ.

---

Die Metadaten-Werte-Union

Jede Eigenschaft innerhalb eines Metadaten-Abschnitts ist eine der folgenden:

Wertart	Form
Einfacher String	"A short text"
Einfache Zahl	42
Einfacher Boolean	true
Externer Link	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Attachment	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type ist der Diskriminator: Sein literaler Wert sagt Ihnen, welche der beiden getaggten Formen vorliegt. Beide getaggten Formen sind ansonsten einfache Objekte; es ist kein zusätzlicher Endpunkt nötig, um sie zu lesen, sie kommen überall dort inline zurück, wo Metadaten zurückgegeben werden.

Achtung

Nur diese fünf Wertarten werden gespeichert. Ein getaggtes Objekt mit einem anderen _p3d_type wird ohne Fehlermeldung verworfen: Der PATCH liefert trotzdem 200, und die Eigenschaft fehlt einfach in der Antwort und in späteren Abrufen.

Hinweis

Dropdowns werden auf einem Asset-Typ definiert, und Asset-Typen sind über die API schreibgeschützt. Ein Dropdown können Sie hier also nicht anlegen. Sie können aber eines erscheinen lassen: Setzen Sie die assetTypeId eines Assets (beim Anlegen oder mit PATCH /v1/twin/{contextId}/assets/{assetId}) auf einen Asset-Typ, der eines definiert. Diese Eigenschaft wird dann in RealityTwin als Dropdown angezeigt. Über die API wird ihr Wert als einfacher String gelesen und geschrieben.

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

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

Feld	Typ	Hinweise
url	String	Das Linkziel.
text	String	Anzeigetext für den Link.
_p3d_type	String	Immer urn:primitive:obj:external-link.

Ein externer Link ist eigenständig; setzen Sie das Objekt direkt in einem Metadaten-Schreibvorgang, kein Upload nötig.

Attachment (urn:primitive:obj:attachment)

Feld	Typ	Hinweise
name	String	Ursprünglicher Dateiname.
id	String	Die fileId des Attachments, aus dem unten stehenden Upload-Ablauf.
_p3d_type	String	Immer urn:primitive:obj:attachment.

Anders als der externe Link verweist ein Attachment-Wert auf eine Datei, die zuerst existieren muss. Sie hochzuladen ist eine separate, mehrstufige Aufrufkette, die als Nächstes behandelt wird.

Eine Datei an Metadaten anhängen

Einen Datei-Verweis als Attachment-Wert zu erhalten, ist eine dreistufige Abfolge: den Upload initiieren, die Teile zu S3 hochladen, ihn finalisieren; und dann die zurückgegebene Datei-ID als id-Feld eines Attachment-Werts im nächsten Metadaten-Schreibvorgang verwenden.

Methode	Pfad	Scope	Zweck
POST	/v1/twin/{contextId}/object/attachments	write:asset	Attachment-Upload initiieren
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Abgelaufene Teil-URLs erneuern
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	Upload finalisieren
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Signierte Download-URL abrufen
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Attachment entfernen

contextId ist der Twin, die Site oder der Draft, zu dem das Attachment gehört; dieselbe ID, die Sie für die Suche nach Business-Objekten verwenden.

Achtung

Die fünf oben genannten Attachment-Endpunkte sind in der API-Referenz als experimentell markiert und können sich ändern. Die Metadaten-Endpunkte GET/PATCH, in die sie münden, sind es nicht.

Der Upload selbst folgt derselben generischen Initiate-→-Upload-Parts-→-Finalize-Mechanik, die auch anderswo in der API verwendet wird (Multipart, presigned S3-URLs, erneuerbar bei Ablauf). Siehe die gemeinsame Multipart-Upload-Referenz für diese Mechanik und ihre Falle bei der Teil-Nummerierung. Dieser Abschnitt behandelt nur das, was für Attachments spezifisch ist.

Schritt 1: initiieren

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

Schritt 2: die Teile hochladen

PUT jeden Chunk an seine presigned url, dabei den zurückgegebenen ETag pro Teil aufbewahren, genau wie in der gemeinsamen Multipart-Upload-Referenz beschrieben.

Schritt 3: finalisieren

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
}

Schritt 4: die Datei in Metadaten referenzieren

Nehmen Sie die fileId aus der Finalize-Antwort und setzen Sie sie als id eines Attachment-Werts in Ihrem nächsten Metadaten-Schreibvorgang:

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

Ein Metadaten-Schreibvorgang nimmt das vollständige Metadaten-Objekt entgegen (neue, aktualisierte und entfernte Abschnitte und Eigenschaften zusammen), nicht ein Patch einer einzelnen Eigenschaft. Nehmen Sie daher jeden Abschnitt und jede Eigenschaft mit auf, die Sie zusätzlich zum neuen Attachment-Verweis behalten möchten.

Getaggte Werte zurücklesen

GET /v1/twin/{contextId}/object/{objectId}/metadata gibt jede Eigenschaft genau so zurück, wie sie geschrieben wurde: ein einfacher String/Zahl/Boolean, oder eines der beiden getaggten Objekte oben mit intaktem _p3d_type. Es gibt keinen separaten „Auflösungs”-Schritt zum Lesen eines getaggten Werts; das Objekt selbst, einschließlich der id des Attachments, kommt inline in der Metadaten-Antwort zurück.

Um an die Bytes der Datei zu gelangen, übergeben Sie diese id als fileId an den unten stehenden Download-Endpunkt.

Ein Attachment herunterladen und entfernen

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

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

Die zurückgegebene URL ist ein signierter CloudFront-Link, gültig für etwa 4 Stunden. Rufen Sie einen neuen ab, falls dieser abläuft.

Um die zugrunde liegende Datei eines Attachments zu entfernen:

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

Hinweis

Das Löschen der Datei entfernt nicht automatisch ihren Verweis aus einer Metadaten-Eigenschaft, die darauf zeigt. Löschen Sie den Verweis mit einem Metadaten-Schreibvorgang, wenn er nicht mehr erscheinen soll.

Limits für Anhänge

Der Speicher für Anhänge nutzt dieselbe Speicherzuteilung pro Organisation wie jede andere Datei in RealityConnect; es gibt kein separates „Attachment-Kontingent”.

Frage	Antwort
Maximale Größe eines einzelnen Anhangs	Es wird keine dedizierte Größenobergrenze durchgesetzt. Die praktische Obergrenze ist der verbleibende Speicherplatz Ihrer Organisation.
Maximale Anzahl von Anhängen pro Objekt	Es wird keine dedizierte Obergrenze für die Anzahl durchgesetzt. Ein Metadaten-Abschnitt kann eine beliebige Anzahl von Attachment-Eigenschaften enthalten.
Gesamtmenge pro Twin oder pro Organisation	Es gibt kein separates Attachment-Kontingent. Jeder Anhang wird als reguläre Datei gespeichert und zählt zur gesamten Speicherzuteilung Ihrer Organisation; demselben Zähler, den jede andere hochgeladene Datei verwendet. StorageLimitExceeded (siehe Fehlercodes) wird zurückgegeben, sobald die Nutzung die zugewiesene Speichermenge Ihrer Organisation überschreitet. Diese Zuteilung ist planabhängig, daher gibt es hier keine einzelne zu veröffentlichende Zahl; wenden Sie sich an Ihr Prevu3D-Account-Team, um die Zahl für Ihre Organisation zu erfahren.
Akzeptierte Dateitypen	Jeder von Ihnen gesendete mimeType wird akzeptiert; es gibt keine Positivliste, die erfüllt werden muss.
Dieselbe Datei an mehrere Objekte angehängt	Wird einmal pro Upload gespeichert, nicht einmal pro Referenz. Das zweimalige Hochladen identischer Bytes (zwei separate Initiate-→-Finalize-Abläufe) erzeugt zwei separate gespeicherte Dateien; es gibt keine automatische Deduplizierung. Um ein gemeinsames Dokument an mehrere Objekte anzuhängen, ohne es doppelt zu speichern, laden Sie es einmal hoch und verwenden die zurückgegebene id in jedem Attachment-Wert der Objekte erneut, anstatt es erneut hochzuladen.

Hinweis

Die obigen Antworten zu Größe und Anzahl beschreiben, was der heutige Upload-Pfad durchsetzt, nicht eine veröffentlichte Produktobergrenze. Wenn Ihre Integration eine feste Zahl zum Planen benötigt (zum Beispiel das Anhängen eines Fotos an jedes Asset in großen Mengen), bestätigen Sie aktuelle Zahlen mit dem Prevu3D-Team, bevor Sie sich auf ein Design festlegen.

Wie geht es weiter?

• Gemeinsame Multipart-Upload-Referenz für die generische Initiate-/Upload-/Finalize-Mechanik.
• Business-Objekte und Knoten durchsuchen dafür, wie contextId aufgelöst wird.
• Siehe die API-Referenz für vollständige Anfrage- und Antwortschemata pro Operation.