Einführung in Data Bundles

Ein Data Bundle ist der Container für eine Erfassung: Roh-Eingabedateien (Punktwolken, Trajektorien, Bilder und so weiter) plus die verarbeiteten Ausgaben, die die Plattform daraus generiert. Die RealityConnect API stellt denselben Bundle-Lebenszyklus bereit, den die Prevu3D-Oberfläche nutzt, sodass Integrationen Bundles erstellen, Daten hochladen, die Verarbeitung starten, den Fortschritt verfolgen und Eingabedateien abrufen können, ohne einen Browser.

Dieses Dokument setzt voraus, dass Sie einen OAuth-Flow abgeschlossen haben und über ein access_token, Ihre regionale api_url und Ihre organization_id verfügen. Siehe die Flow-Leitfäden, falls nicht.

Alle Endpunkte für Data-Bundle-Workflows (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree und /v1/nodes/.../bundle) sind als experimentell gekennzeichnet. Rechnen Sie damit, dass sich der Vertrag weiterentwickelt, bis sie stabil werden. Siehe Experimentelle Endpunkte.

Erforderliche Scopes

Scope	Verwendung
`read:bundle`	Geräte-Input-Baum abrufen, Upload-Sessions auflisten, Verarbeitungsoptionen auflisten, Verarbeitungsdatensätze auflisten, Download-URLs für Eingabedateien auflisten
`write:bundle`	Bundle erstellen, Upload-Sessions öffnen und abschließen, Verarbeitung starten

Sie benötigen außerdem Inhaltszugriff und Knotenberechtigungen auf dem übergeordneten Knoten, unter dem das Bundle erstellt wird, sowie auf dem Bundle selbst für spätere Schritte.

End-to-End-Ablauf

flowchart LR
  A["1. Get input tree"] --> B["2. Create bundle"]
  B --> C["3. Upload input files"]
  C --> D["4. List processing options"]
  D --> E["5. Start processing"]
  E --> F["6. Poll processing records"]

Jeder nummerierte Schritt entspricht einem eigenen Leitfaden:

Schritt	Leitfaden	Zusammenfassung
1-2	Data Bundle erstellen	Geräte-Input-Baum abrufen, Blatt-`dbuPath` wählen, Bundle unter einem übergeordneten Knoten erstellen
3	Daten in ein Data Bundle hochladen	Upload-Session öffnen, jede Datei per Multipart-Upload nach S3 hochladen, abschließen
4-6	Verarbeitung und Überwachung	Verfügbare Ausgaben auflisten, Verarbeitung starten, abfragen, bis jeder Job einen Endzustand erreicht

Download von Eingabedateien ist optional: Verwenden Sie ihn nur, wenn Sie die hochgeladenen Eingabedateien des Bundles erneut abrufen müssen.

Validierungsmodell

Strukturelle Regeln (Pflicht-Dateitypen, erlaubte Erweiterungen, abhängige Typen, Mehrfachheit) werden im requirements-Array beschrieben, das beim Öffnen einer Upload-Session zurückgegeben wird. Es liegt in der Verantwortung des Benutzers, diese Struktur vor dem Upload und vor dem Start der Verarbeitung einzuhalten.

Die Upload-API erfasst jede Datei unter dem von Ihnen angegebenen type und schließt die Session allein anhand der Anzahl ab. Eine tiefe Inhaltsvalidierung (ob eine .las eine echte Geräteerfassung ist, ob JSON-Metadaten korrekt auf ihr Bild verweisen) erfolgt erst nach dem Start der Verarbeitung, nicht zum Upload-Zeitpunkt. Eine korrekt benannte, aber fehlerhafte Datei wird ohne Fehler hochgeladen und schlägt später während der Verarbeitung fehl.

Verarbeitungsfehler, die durch eine falsche Upload-Struktur verursacht werden (fehlende Pflichttypen, defekte Abhängigkeiten, falsche Erweiterungen und so weiter), werden nicht erstattet.