Importazione in blocco di asset da CSV

Questa guida mostra come creare in blocco RealityAssets in un twin da un file CSV. Ogni riga definisce il nome di un asset e un bounding box orientato nello spazio del twin. Il flusso di lavoro usa il flusso Client Credentials e lo scope write:asset.

Prerequisiti

Un’applicazione OAuth configurata per Client Credentials
Scope: read:basic, read:hierarchy, write:asset
Il tuo client_id e client_secret
Accesso ai contenuti e permessi di modifica sul twin di destinazione
L’ID del twin in cui creare gli asset

Quando usare questo schema

Usa un’importazione basata su CSV quando hai già definizioni di asset al di fuori di Prevu3D, ad esempio:

Elenchi di attrezzature esportati da un sistema CMMS o ERP con coordinate 3D
Risultati di rilievi o etichettatura da uno strumento esterno
Migrazione da un’altra piattaforma in cui gli asset erano posizionati in coordinate del twin

Ogni chiamata all’API crea un asset. Uno script itera sulle righe del CSV e chiama POST /v1/twin/{twinId}/assets per ciascuna voce.

Formato CSV

Il foglio di calcolo deve includere una riga di intestazione. Colonne richieste:

Colonna	Corrisponde a	Descrizione
`Description`	`name` dell’asset	Nome visualizzato per il RealityAsset
`Manual_X`	`x` del centro del box	Coordinata X del centro del box nello spazio del twin
`Manual_Y`	`y` del centro del box	Coordinata Y del centro del box nello spazio del twin
`Manual_Z`	`z` del centro del box	Coordinata Z del centro del box nello spazio del twin
`Manual_Box_X`	`x` della dimensione del box	Larghezza del bounding box
`Manual_Box_Y`	`y` della dimensione del box	Profondità del bounding box
`Manual_Box_Z`	`z` della dimensione del box	Altezza del bounding box

Esempio:

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

Le coordinate devono essere nello stesso sistema di coordinate del twin. Se hai posizionato gli asset manualmente in RealityTwin, esporta o registra i valori nello spazio del twin. La rotazione predefinita è l’identità; l’API accetta un quaternione rotation opzionale su ciascun box se hai bisogno di volumi orientati.

Flusso end-to-end

flowchart LR
  A["1. Authenticate"] --> B["2. Read CSV rows"]
  B --> C["3. Build workingStructure"]
  C --> D["4. POST asset per row"]
  D --> E["5. Review results"]

Passaggio	Endpoint	Cosa ottieni
Autenticazione	`POST /oauth/token`	Access token
Risoluzione dell’URL dell’API	`GET /oauth/api-info`	`apiUrl` regionale
Creazione dell’asset	`POST /v1/twin/{twinId}/assets`	Nuovo ID asset per riga

Forma del payload dell’asset

Ogni riga diventa un asset con una workingStructure contenente un singolo box orientato:

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

Per assegnare un tipo di asset al momento della creazione, aggiungi assetTypeId con l’UUID di un tipo configurato nella tua organizzazione. Consulta Tipi di asset per sapere come i tipi vengono definiti in RealityPlatform.

Passaggio 1 — Autenticazione

Ottieni un access token con 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}

Passaggio 2 — Crea gli asset dal 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 }
      }
    ]
  }
}

Una risposta di successo restituisce l’asset creato, incluso il suo id. Ripeti per ogni riga del CSV.

Esempio completo

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

Trovare l’ID del twin

L’ID del twin è l’UUID del nodo twin nella tua gerarchia di contenuti. Puoi:

Copiarlo dall’URL di RealityPlatform quando il twin è aperto
Esplorare la gerarchia con GET /v1/nodes/{organizationId}/browse e individuare un nodo con type: "Twin"

Suggerimenti per importazioni di grandi dimensioni

Suddividi in batch in modo responsabile. L’API crea un asset per richiesta. Per centinaia di righe, aggiungi un breve ritardo o un backoff se raggiungi i limiti di frequenza.
Valida prima le coordinate. Importa una singola riga di test prima di eseguire il file completo.
Usa la Modalità bozza in RealityTwin quando vuoi rivedere gli asset prima che altri utenti li vedano. Gli asset creati tramite l’API appaiono immediatamente nel twin a meno che la tua integrazione non punti a un flusso di lavoro con bozza.
Allega i metadati in seguito. Dopo la creazione, usa PATCH /v1/twin/{twinId}/assets/{assetId}/metadata per aggiungere valori delle proprietà. Consulta gli endpoint degli asset nel riferimento API.

Cosa c’è dopo?

Configura l’autenticazione nella guida Flusso Client Credentials.
Scopri come funzionano gli asset nel twin workspace: Lavorare con i RealityAssets.
Esplora gli endpoint degli asset nel riferimento API.