IDs finden: Organisationen, Nodes und Context

Fast jeder Pfad der RealityConnect API enthält eine ID (contextId, organizationId, ownerContextIds), die zunächst ermittelt werden muss. Diese Seite zeigt, wo diese IDs im Node-Baum Ihrer Organisation liegen, wie Sie sie ausgehend von nur einem Access Token finden, und welche Routenfamilie welche ID erwartet.

---

Alles ist ein Node

Der Inhalt Ihrer Organisation (Divisions, Sites, Folders, Twins, Data Bundles, Asset Libraries und mehr) bildet einen einzigen Baum aus Data Nodes. Jeder Node hat eine uuid-ID und einen DataNodeType (Organization, Division, Site, Folder, Twin, AssetLibrary, Project, SiteFile, Artifact, DataBundle). Die meisten Pfadparameter der API, darunter contextId, organizationId, nodeId, parentId und ownerContextId, sind schlicht die ID eines dieser Nodes.

Hinweis

Diese Seite beschreibt, wie Sie Node-IDs finden und erkennen, welche eine Route erwartet. Die vollständigen Regeln, welcher Node-Typ welchen enthalten kann, finden Sie unter Node Types and Hierarchy.

Den Baum ausgehend vom Token durchsuchen

Mit zwei Aufrufen gelangen Sie von einem Access Token zu jeder Node-ID Ihrer Organisation:

1. Organization-ID ermitteln

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 ist die Wurzel Ihres Node-Baums: die organizationId, die die meisten Routen erwarten. apiUrl ist die Basis-URL Ihrer regionalen RealityConnect API. Den vollständigen Token-Austausch und die Wahl des passenden OAuth-Flows finden Sie unter Getting Started.

2. Von dort aus abwärts navigieren

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

Übergeben Sie die Organization-ID, um Ihre Divisions zu sehen. Jedes Element der Antwort ist selbst ein Node mit eigener ID und eigenem Typ; übergeben Sie diese ID an dieselbe Route, um eine Ebene tiefer zu navigieren (die Sites einer Division, die Folders und Twins einer Site usw.). Es gibt keinen separaten Endpunkt für “meine Divisions auflisten” oder “die Twins dieser Site auflisten”: browse ist der eine Aufruf, den Baum entlang wiederholt.

Tipp

Wenn Sie bereits ungefähr wissen, wonach Sie anhand von Name oder Typ suchen, können Sie mit GET /v1/nodes/search (gefiltert nach nodeTypes, parentId oder ancestorId) direkt dorthin springen, statt Ebene für Ebene zu navigieren. Siehe Searching Business Objects and Nodes.

Welche ID erwartet welche Routenfamilie?

Routenfamilie	ID	Was sie identifiziert
/v1/twin/{contextId}/... (assets, POIs, zones, drafts, object, search, space)	contextId	Einen Twin, dessen Site oder einen seiner Drafts. Wird direkt aufgelöst; eine Design-Project- oder Layout-ID führt hier zu 404.
/v1/reality-plan/{contextId}/... (space, model-assets, layouts, bundles)	contextId	Ein Design Project (RealityPlan Project) oder eines seiner Layouts. Wird direkt aufgelöst; eine Twin-, Site- oder Twin-Draft-ID führt hier zu 404.
/v1/nodes/{id}/browse	id / nodeId / parentId	Den Data Node selbst, auf der jeweiligen Ebene.
GET /v1/asset-library/-/models (Query-Parameter ownerContextIds)	ownerContextIds	Die ID(s) des Kontexts, dem die Library gehört: Ihre Organization-ID oder die ID eines RealityPlan Project. Nicht die ID eines AssetLibrary-Nodes. Diese Route erwartet aktuell mindestens einen Wert; wird er weggelassen, liefert die Route 400.
/v1/asset-library/{ownerContextId}/... (Pfadparameter, z. B. Library-Model anlegen/lesen/aktualisieren)	ownerContextId	Wie oben: die Organization oder das RealityPlan Project, dem die Library gehört, nicht die eigene ID des AssetLibrary-Nodes.

Hinweis

contextId ist kein universeller ID-Typ: was sie repräsentiert, hängt von der jeweiligen Routenfamilie ab. Eine syntaktisch gültige ID aus der falschen Familie liefert 404, statt spezifischer zu melden, was falsch ist. Die vollständigen Auflösungsregeln finden Sie unter What contextId Accepts.

Wie geht es weiter?

• Sehen Sie sich die API-Referenz für vollständige Request-/Response-Schemas an.
• Siehe Searching Business Objects and Nodes für gefilterte Node- und Objektsuchen.
• Siehe OAuth Scopes für die Berechtigungen von read:hierarchy und write:hierarchy.