Pular para o conteúdo
Prevu3D

Importação em Massa de Ativos a partir de CSV

Este guia mostra como criar RealityAssets em massa em um twin a partir de um arquivo CSV. Cada linha define um nome de ativo e uma caixa delimitadora orientada no espaço do twin. O fluxo de trabalho usa o fluxo Client Credentials e o escopo write:asset.

Pré-requisitos

Seção intitulada “Pré-requisitos”
  • Um aplicativo OAuth configurado para Client Credentials
  • Escopos: read:basic, read:hierarchy, write:asset
  • Seu client_id e client_secret
  • Acesso ao conteúdo e permissões de edição no twin de destino
  • O ID do twin onde os ativos devem ser criados

Quando usar este padrão

Seção intitulada “Quando usar este padrão”

Use uma importação orientada por CSV quando você já tiver definições de ativos fora do Prevu3D, por exemplo:

  • Listas de equipamentos exportadas de um sistema CMMS ou ERP com coordenadas 3D
  • Resultados de levantamento ou de marcação de uma ferramenta externa
  • Migração de outra plataforma em que os ativos foram posicionados em coordenadas do twin

Cada chamada à API cria um ativo. Um script percorre as linhas do CSV e chama POST /v1/twin/{twinId}/assets para cada entrada.

Formato do CSV

Seção intitulada “Formato do CSV”

A planilha precisa incluir uma linha de cabeçalho. Colunas obrigatórias:

ColunaMapeia paraDescrição
Descriptionname do ativoNome de exibição do RealityAsset
Manual_Xx do centro da caixaCoordenada X do centro da caixa no espaço do twin
Manual_Yy do centro da caixaCoordenada Y do centro da caixa no espaço do twin
Manual_Zz do centro da caixaCoordenada Z do centro da caixa no espaço do twin
Manual_Box_Xx do tamanho da caixaLargura da caixa delimitadora
Manual_Box_Yy do tamanho da caixaProfundidade da caixa delimitadora
Manual_Box_Zz do tamanho da caixaAltura da caixa delimitadora

Exemplo:

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

As coordenadas precisam estar no mesmo sistema de coordenadas do twin. Se você posicionou os ativos manualmente no RealityTwin, exporte ou registre os valores no espaço do twin. A rotação assume a identidade por padrão; a API aceita um quaternion rotation opcional em cada caixa se você precisar de volumes orientados.

Fluxo de ponta a ponta

Seção intitulada “Fluxo de ponta a ponta”
flowchart LR
  A["1. Autenticar"] --> B["2. Ler linhas do CSV"]
  B --> C["3. Montar workingStructure"]
  C --> D["4. POST de ativo por linha"]
  D --> E["5. Revisar resultados"]
EtapaEndpointO que você obtém
AutenticarPOST /oauth/tokenToken de acesso
Resolver a URL da APIGET /oauth/api-infoapiUrl regional
Criar ativoPOST /v1/twin/{twinId}/assetsNovo ID de ativo por linha

Formato do payload do ativo

Seção intitulada “Formato do payload do ativo”

Cada linha se torna um ativo com uma workingStructure contendo uma única caixa orientada:

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

Para atribuir um tipo de ativo no momento da criação, adicione assetTypeId com o UUID de um tipo configurado na sua organização. Consulte Tipos de Ativo para saber como os tipos são definidos no RealityPlatform.

Etapa 1 — Autenticar

Seção intitulada “Etapa 1 — Autenticar”

Obtenha um token de acesso com 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}

Etapa 2 — Criar ativos a partir do CSV

Seção intitulada “Etapa 2 — Criar ativos a partir do 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 }
      }
    ]
  }
}

Uma resposta bem-sucedida retorna o ativo criado, incluindo seu id. Repita para cada linha do CSV.

Exemplo completo

Seção intitulada “Exemplo 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)}")

Encontrando o ID do twin

Seção intitulada “Encontrando o ID do twin”

O ID do twin é o UUID do nó do twin na sua hierarquia de conteúdo. Você pode:

  • Copiá-lo da URL do RealityPlatform quando o twin estiver aberto
  • Navegar pela hierarquia com GET /v1/nodes/{organizationId}/browse e localizar um nó com type: "Twin"

Dicas para importações grandes

Seção intitulada “Dicas para importações grandes”
  • Faça lotes com responsabilidade. A API cria um ativo por requisição. Para centenas de linhas, adicione um pequeno atraso ou backoff se você atingir os limites de taxa.
  • Valide as coordenadas primeiro. Importe uma única linha de teste antes de executar o arquivo completo.
  • Use o Modo Rascunho no RealityTwin quando quiser revisar os ativos antes que outros usuários os vejam. Ativos criados pela API aparecem no twin imediatamente, a menos que sua integração use um fluxo de rascunho.
  • Anexe metadados depois. Após a criação, use PATCH /v1/twin/{twinId}/assets/{assetId}/metadata para adicionar valores de propriedade. Consulte os endpoints de ativos na referência da API.

Próximos passos

Seção intitulada “Próximos passos”