Assets per CSV im Bulk importieren

Diese Anleitung zeigt, wie Sie RealityAssets in einem Twin per CSV-Datei im Bulk erstellen. Jede Zeile definiert einen Asset-Namen und eine orientierte Bounding Box im Twin-Raum. Der Workflow nutzt den Client-Credentials-Flow und den Scope write:asset.

---

Voraussetzungen

• Eine OAuth-Anwendung, die für Client Credentials konfiguriert ist
• Scopes: read:basic, read:hierarchy, write:asset
• Ihre client_id und client_secret
• Inhaltszugriff und Bearbeitungsberechtigungen auf dem Ziel-Twin
• Die Twin-ID, in der die Assets erstellt werden sollen

Wann Sie dieses Muster verwenden sollten

Verwenden Sie einen CSV-gesteuerten Import, wenn Sie Asset-Definitionen bereits außerhalb von Prevu3D haben, zum Beispiel:

• Gerätelisten, die aus einem CMMS- oder ERP-System mit 3D-Koordinaten exportiert wurden
• Vermessungs- oder Tagging-Ergebnisse aus einem externen Tool
• Migration von einer anderen Plattform, bei der Assets in Twin-Koordinaten positioniert wurden

Jeder API-Aufruf erstellt ein Asset. Ein Skript iteriert über die CSV-Zeilen und ruft POST /v1/twin/{twinId}/assets für jeden Eintrag auf.

CSV-Format

Die Tabelle muss eine Kopfzeile enthalten. Erforderliche Spalten:

Spalte	Zuordnung zu	Beschreibung
Description	Asset name	Anzeigename für das RealityAsset
Manual_X	Box-Mitte x	X-Koordinate des Box-Mittelpunkts im Twin-Raum
Manual_Y	Box-Mitte y	Y-Koordinate des Box-Mittelpunkts im Twin-Raum
Manual_Z	Box-Mitte z	Z-Koordinate des Box-Mittelpunkts im Twin-Raum
Manual_Box_X	Box-Größe x	Breite der Bounding Box
Manual_Box_Y	Box-Größe y	Tiefe der Bounding Box
Manual_Box_Z	Box-Größe z	Höhe der Bounding Box

Beispiel:

Description,Manual_X,Manual_Z,Manual_Y,Manual_Box_X,Manual_Box_Z,Manual_Box_Y
Pump A,6.27,-5.10,187.12,0.35,0.64,0.33
Valve B,8.84,-3.14,189.41,2.99,1.11,4.69

Hinweis

Die Spaltenreihenfolge in der Datei kann von dem obigen Beispiel abweichen, solange die Spaltennamen übereinstimmen. Zusätzliche Spalten werden ignoriert.

Die Koordinaten müssen im selben Koordinatensystem wie der Twin liegen. Wenn Sie Assets manuell in RealityTwin positioniert haben, exportieren oder notieren Sie die Werte im Twin-Raum. Die Rotation ist standardmäßig die Identität; die API akzeptiert ein optionales rotation-Quaternion auf jeder Box, wenn Sie orientierte Volumen benötigen.

End-to-End-Ablauf

flowchart LR
  A["1. Authentifizieren"] --> B["2. CSV-Zeilen lesen"]
  B --> C["3. workingStructure erstellen"]
  C --> D["4. Asset pro Zeile POSTen"]
  D --> E["5. Ergebnisse prüfen"]

Schritt	Endpunkt	Was Sie erhalten
Authentifizieren	POST /oauth/token	Access Token
API-URL auflösen	GET /oauth/api-info	Regionale apiUrl
Asset erstellen	POST /v1/twin/{twinId}/assets	Neue Asset-ID pro Zeile

Asset-Payload-Struktur

Jede Zeile wird zu einem Asset mit einer workingStructure, die eine einzelne orientierte Box enthält:

{
  "name": "Pump A",
  "workingStructure": {
    "boxes": [
      {
        "center": { "x": 6.27, "y": 187.12, "z": -5.10 },
        "size": { "x": 0.35, "y": 0.33, "z": 0.64 },
        "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
      }
    ]
  }
}

Um einen Asset-Typ bei der Erstellung zuzuweisen, fügen Sie assetTypeId mit der UUID eines in Ihrer Organisation konfigurierten Typs hinzu. Siehe Asset-Typen für die Definition von Typen in RealityPlatform.

Schritt 1 — Authentifizieren

Access Token mit Client Credentials abrufen:

POST https://cloud-api.prevu3d.com/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

GET https://cloud-api.prevu3d.com/oauth/api-info
Authorization: Bearer {access_token}

Schritt 2 — Assets aus CSV erstellen

POST {api_url}/v1/twin/{twinId}/assets
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Pump A",
  "workingStructure": {
    "boxes": [
      {
        "center": { "x": 6.27, "y": 187.12, "z": -5.10 },
        "size": { "x": 0.35, "y": 0.33, "z": 0.64 },
        "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
      }
    ]
  }
}

Eine erfolgreiche Antwort gibt das erstellte Asset zurück, einschließlich seiner id. Wiederholen Sie dies für jede CSV-Zeile.

Vollständiges Beispiel

import base64
import csv
from pathlib import Path

import requests

CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
CLOUD_API_BASE = "https://cloud-api.prevu3d.com"
TWIN_ID = "your-twin-id"
CSV_FILE = Path("assets.csv")

credentials = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
token_response = requests.post(
    f"{CLOUD_API_BASE}/oauth/token",
    data={"grant_type": "client_credentials"},
    headers={"Authorization": f"Basic {credentials}"},
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]
headers = {"Authorization": f"Bearer {access_token}"}

api_info = requests.get(f"{CLOUD_API_BASE}/oauth/api-info", headers=headers).json()
api_url = api_info["apiUrl"].rstrip("/")


def api_post(path: str, body: dict) -> dict:
    response = requests.post(f"{api_url}{path}", json=body, headers=headers)
    response.raise_for_status()
    return response.json()


def oriented_box(cx: float, cy: float, cz: float, sx: float, sy: float, sz: float) -> dict:
    return {
        "center": {"x": cx, "y": cy, "z": cz},
        "size": {"x": sx, "y": sy, "z": sz},
        "rotation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0},
    }


with CSV_FILE.open(newline="", encoding="utf-8") as handle:
    rows = list(csv.DictReader(handle))

created = []
errors = []

for row in rows:
    name = row["Description"].strip()
    body = {
        "name": name,
        "workingStructure": {
            "boxes": [
                oriented_box(
                    cx=float(row["Manual_X"]),
                    cy=float(row["Manual_Y"]),
                    cz=float(row["Manual_Z"]),
                    sx=float(row["Manual_Box_X"]),
                    sy=float(row["Manual_Box_Y"]),
                    sz=float(row["Manual_Box_Z"]),
                )
            ]
        },
    }

    try:
        asset = api_post(f"/v1/twin/{TWIN_ID}/assets", body)
        print(f"[OK]  {name}  ->  {asset['id']}")
        created.append(asset)
    except requests.HTTPError as error:
        print(f"[ERR] {name}  ->  {error.response.status_code} {error.response.text}")
        errors.append(name)

print(f"\nCreated: {len(created)}  /  Errors: {len(errors)}")

Twin-ID finden

Die Twin-ID ist die UUID des Twin-Knotens in Ihrer Inhaltshierarchie. Sie können:

• Sie aus der RealityPlatform-URL kopieren, wenn der Twin geöffnet ist
• Die Hierarchie mit GET /v1/nodes/{organizationId}/browse durchsuchen und einen Knoten mit type: "Twin" finden

Tipps für große Importe

• Verantwortungsvoll batchen. Die API erstellt ein Asset pro Anfrage. Bei Hunderten von Zeilen fügen Sie eine kurze Verzögerung oder Backoff hinzu, wenn Sie Rate Limits erreichen.
• Koordinaten zuerst validieren. Importieren Sie eine einzelne Testzeile, bevor Sie die vollständige Datei ausführen.
• Verwenden Sie den Draft Mode in RealityTwin, wenn Sie Assets prüfen möchten, bevor andere Benutzer sie sehen. Über die API erstellte Assets erscheinen sofort im Twin, es sei denn, Ihre Integration zielt auf einen Draft-Workflow ab.
• Metadaten später anhängen. Nach der Erstellung verwenden Sie PATCH /v1/twin/{twinId}/assets/{assetId}/metadata, um Eigenschaftswerte hinzuzufügen. Siehe die Asset-Endpunkte in der API-Referenz.

Wie geht es weiter?

• Richten Sie die Authentifizierung in der Anleitung Client-Credentials-Flow ein.
• Erfahren Sie, wie Assets im Twin-Workspace funktionieren: Arbeiten mit RealityAssets.
• Durchsuchen Sie Asset-Endpunkte in der API-Referenz.