Assets bulksgewijs importeren uit CSV

Deze gids laat zien hoe u bulksgewijs RealityAssets in een twin maakt vanuit een CSV-bestand. Elke rij definieert een assetnaam en een georiënteerde bounding box in de twin-ruimte. De workflow gebruikt de Client Credentials-flow en de write:asset-scope.

Vereisten

Een OAuth-applicatie geconfigureerd voor Client Credentials
Scopes: read:basic, read:hierarchy, write:asset
Uw client_id en client_secret
Inhoudstoegang en bewerkingsrechten op de doeltwin
De twin-ID waar assets moeten worden gemaakt

Wanneer u dit patroon gebruikt

Gebruik een CSV-gestuurde import wanneer u al assetdefinities buiten Prevu3D hebt, bijvoorbeeld:

Apparatuurlijsten geëxporteerd uit een CMMS- of ERP-systeem met 3D-coördinaten
Meet- of taggingresultaten van een externe tool
Migratie vanaf een ander platform waar assets in twin-coördinaten waren gepositioneerd

Elke API-aanroep maakt één asset. Een script loopt over de CSV-rijen en roept POST /v1/twin/{twinId}/assets aan voor elke vermelding.

CSV-formaat

De spreadsheet moet een kopregel bevatten. Vereiste kolommen:

Kolom	Wordt toegewezen aan	Beschrijving
`Description`	Asset-`name`	Weergavenaam voor de RealityAsset
`Manual_X`	Box-centrum `x`	X-coördinaat van het boxcentrum in de twin-ruimte
`Manual_Y`	Box-centrum `y`	Y-coördinaat van het boxcentrum in de twin-ruimte
`Manual_Z`	Box-centrum `z`	Z-coördinaat van het boxcentrum in de twin-ruimte
`Manual_Box_X`	Box-grootte `x`	Breedte van de bounding box
`Manual_Box_Y`	Box-grootte `y`	Diepte van de bounding box
`Manual_Box_Z`	Box-grootte `z`	Hoogte van de bounding box

Voorbeeld:

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

Coördinaten moeten in hetzelfde coördinatensysteem als de twin staan. Als u assets handmatig in RealityTwin hebt gepositioneerd, exporteert of registreert u waarden in de twin-ruimte. De rotatie is standaard identiteit; de API accepteert een optionele rotation-quaternion op elke box als u georiënteerde volumes nodig hebt.

End-to-end-flow

flowchart LR
  A["1. Authenticeren"] --> B["2. CSV-rijen lezen"]
  B --> C["3. workingStructure bouwen"]
  C --> D["4. POST asset per rij"]
  D --> E["5. Resultaten bekijken"]

Stap	Endpoint	Wat u krijgt
Authenticeren	`POST /oauth/token`	Access token
API-URL oplossen	`GET /oauth/api-info`	Regionale `apiUrl`
Asset maken	`POST /v1/twin/{twinId}/assets`	Nieuwe asset-ID per rij

Vorm van de asset-payload

Elke rij wordt één asset met een workingStructure die één georiënteerde box bevat:

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

Om een asset-type toe te wijzen bij het maken, voegt u assetTypeId toe met de UUID van een type dat in uw organisatie is geconfigureerd. Zie Asset-typen voor hoe typen worden gedefinieerd in RealityPlatform.

Stap 1 — Authenticeren

Verkrijg een access token met Client Credentials:

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}

Stap 2 — Assets maken uit CSV

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

Een succesvolle response retourneert de gemaakte asset, inclusief de id. Herhaal dit voor elke CSV-rij.

Volledig voorbeeld

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

De twin-ID vinden

De twin-ID is de UUID van de twin-node in uw inhoudshiërarchie. U kunt:

Deze kopiëren uit de RealityPlatform-URL wanneer de twin geopend is
De hiërarchie doorbladeren met GET /v1/nodes/{organizationId}/browse en een node met type: "Twin" lokaliseren

Tips voor grote imports

Batch verantwoord. De API maakt één asset per verzoek. Voeg voor honderden rijen een korte vertraging of backoff toe als u tegen rate limits aanloopt.
Valideer eerst coördinaten. Importeer één testrij voordat u het volledige bestand uitvoert.
Gebruik de conceptmodus in RealityTwin wanneer u assets wilt beoordelen voordat andere gebruikers ze zien. Assets die via de API worden gemaakt, verschijnen onmiddellijk in de twin, tenzij uw integratie zich richt op een conceptworkflow.
Voeg later metadata toe. Gebruik na het maken PATCH /v1/twin/{twinId}/assets/{assetId}/metadata om eigenschapswaarden toe te voegen. Zie de asset-endpoints in de API-referentie.

Wat is de volgende stap?

Stel verificatie in via de gids Client Credentials-flow.
Leer hoe assets werken in de twin-werkruimte: Werken met RealityAssets.
Blader door asset-endpoints in de API-referentie.