Cómo encontrar tus IDs: organizaciones, nodos y contexto

Casi todas las rutas de la API de RealityConnect llevan un ID (contextId, organizationId, ownerContextIds) que primero hay que obtener. Esta página muestra dónde viven esos IDs en el árbol de nodos de tu organización, cómo descubrirlos partiendo únicamente de un access token, y qué familia de rutas espera cuál.

---

Todo es un nodo

El contenido de tu organización (divisions, sites, folders, twins, data bundles, asset libraries y más) forma un único árbol de data nodes. Cada nodo tiene un ID uuid y un DataNodeType (Organization, Division, Site, Folder, Twin, AssetLibrary, Project, SiteFile, Artifact, DataBundle). La mayoría de los parámetros de ruta que verás en la API, incluidos contextId, organizationId, nodeId, parentId y ownerContextId, son simplemente el ID de uno de estos nodos.

Nota

Esta página trata sobre cómo encontrar los IDs de los nodos y saber cuál espera cada ruta. Para las reglas completas sobre qué tipo de nodo puede contener a cuál, consulta Node Types and Hierarchy.

Recorre el árbol desde un token

Puedes llegar desde un access token a cualquier ID de nodo de tu organización con dos llamadas:

1. Resuelve el ID de tu organización

GET https://cloud-api.prevu3d.com/oauth/api-info
Authorization: Bearer <access_token>

{
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

organization.id es la raíz de tu árbol de nodos: el organizationId que esperan la mayoría de las rutas. apiUrl es la URL base de tu API de RealityConnect regional. Para el intercambio de token completo y cómo elegir el flujo OAuth adecuado, consulta Getting Started.

2. Desciende por el árbol desde ahí

GET {apiUrl}/v1/nodes/{id}/browse
Authorization: Bearer <access_token>

Pasa el ID de la organización para ver tus divisions. Cada elemento de la respuesta es a su vez un nodo con su propio ID y tipo; pasa ese ID a la misma ruta para bajar un nivel más (los sites de una division, los folders y twins de un site, y así sucesivamente). No existe un endpoint separado para “listar mis divisions” o “listar los twins de este site”: browse es la única llamada, repetida a lo largo del árbol.

Consejo

Si ya sabes aproximadamente qué buscas por nombre o tipo, GET /v1/nodes/search (filtrado por nodeTypes, parentId o ancestorId) te permite ir directo, en lugar de recorrer nivel por nivel. Consulta Searching Business Objects and Nodes.

¿Qué ID espera cada familia de rutas?

Familia de rutas	ID	Qué identifica
/v1/twin/{contextId}/... (assets, POIs, zones, drafts, object, search, space)	contextId	Un twin, el site al que pertenece, o uno de sus drafts. Se resuelve directamente; un ID de design project o de layout devuelve 404 aquí.
/v1/reality-plan/{contextId}/... (space, model-assets, layouts, bundles)	contextId	Un design project (RealityPlan Project) o uno de sus layouts. Se resuelve directamente; un ID de twin, site o twin draft devuelve 404 aquí.
/v1/nodes/{id}/browse	id / nodeId / parentId	El data node en sí, al nivel en el que estés trabajando.
GET /v1/asset-library/-/models (parámetro de consulta ownerContextIds)	ownerContextIds	El o los ID del contexto propietario de la biblioteca: el ID de tu organización o el de un RealityPlan Project. No el ID de un nodo AssetLibrary. Esta ruta actualmente espera al menos un valor; omitirlo devuelve 400.
/v1/asset-library/{ownerContextId}/... (parámetro de ruta, p. ej. crear/leer/actualizar un library model)	ownerContextId	Igual que arriba: la organización o el RealityPlan Project propietario de la biblioteca, no el ID propio del nodo AssetLibrary.

Nota

contextId no es un único tipo de ID universal: lo que resuelve depende de la familia de rutas en la que aparece, y un ID sintácticamente válido pero de la familia equivocada devuelve 404 en lugar de un error más específico. Para las reglas de resolución completas, consulta What contextId Accepts.

¿Qué sigue?

• Explora la referencia de la API para ver los esquemas completos de solicitud/respuesta.
• Consulta Searching Business Objects and Nodes para búsquedas filtradas de nodos y objetos.
• Consulta OAuth Scopes para saber qué otorgan read:hierarchy y write:hierarchy.