Introduzione ai Data Bundle

Un data bundle è il contenitore di un’acquisizione: file di input grezzi (nuvole di punti, traiettorie, immagini e così via) più gli output elaborati che la piattaforma genera da essi. La RealityConnect API espone lo stesso ciclo di vita del bundle usato dall’interfaccia utente di Prevu3D, così le integrazioni possono creare bundle, caricare dati, avviare l’elaborazione, tracciare i progressi e recuperare i file di input senza un browser.

Questo documento presuppone che tu abbia completato un flusso OAuth e disponga di un access_token, del tuo api_url regionale e del tuo organization_id. Consulta le guide ai flussi se non li hai.

Tutti gli endpoint del flusso di lavoro dei data bundle (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree e /v1/nodes/.../bundle) sono contrassegnati come sperimentali. Aspettati che il contratto evolva finché non diventano stabili. Consulta Endpoint sperimentali.

Scope richiesti

Scope	Usato per
read:bundle	Recuperare l’albero degli input del dispositivo, elencare le sessioni di caricamento, elencare le opzioni di elaborazione, elencare i record di elaborazione, elencare gli URL di download dei file di input
write:bundle	Creare un bundle, aprire e finalizzare le sessioni di caricamento, avviare l’elaborazione

Hai anche bisogno dell’accesso ai contenuti e dei permessi sul nodo padre in cui viene creato il bundle, e sul bundle stesso per i passaggi successivi.

Flusso end-to-end

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

Ogni passaggio numerato corrisponde a una guida dedicata:

Passaggio	Guida	Riepilogo
1–2	Creare un Data Bundle	Recuperare l’albero degli input del dispositivo, scegliere un dbuPath foglia, creare il bundle sotto un nodo padre
3	Caricare dati in un Data Bundle	Aprire una sessione di caricamento, caricare ogni file su S3 in multipart, finalizzare
4–6	Elaborazione e monitoraggio	Elencare gli output disponibili, avviare l’elaborazione, effettuare il polling finché ogni job raggiunge uno stato terminale

Scaricare i file di input è opzionale: usalo solo quando devi recuperare di nuovo i file di input caricati del bundle.

Modello di validazione

Le regole strutturali (tipi di file obbligatori, estensioni consentite, dipendenze tra tipi, molteplicità) sono descritte nell’array requirements restituito quando apri una sessione di caricamento. È responsabilità dell’utente seguire quella struttura prima di caricare e prima di avviare l’elaborazione.

L’API di caricamento registra ogni file sotto il type che fornisci e completa la sessione solo in base al conteggio. La validazione approfondita del contenuto (se un .las è una vera acquisizione del dispositivo, se il JSON dei metadati fa correttamente riferimento alla sua immagine) avviene dopo l’avvio di un’elaborazione, non al momento del caricamento. Un file correttamente denominato ma malformato viene caricato senza errori e fallisce in seguito durante l’elaborazione.

Gli errori di elaborazione causati da una struttura di caricamento errata (tipi obbligatori mancanti, dipendenze interrotte, estensioni errate e così via) non verranno rimborsati.