Introduction aux Data Bundles

Un Data Bundle est le conteneur d’une capture : les fichiers d’entrée bruts (nuages de points, trajectoires, images, etc.) ainsi que les sorties traitées que la plateforme génère à partir de ces entrées. La RealityConnect API expose le même cycle de vie de bundle que l’interface Prevu3D, ce qui permet aux intégrations de créer des bundles, téléverser des données, lancer le traitement, suivre la progression et récupérer les fichiers d’entrée sans navigateur.

Ce document suppose que vous avez terminé un flux OAuth et que vous disposez d’un access_token, de votre api_url régionale et de votre organization_id. Consultez les guides de flux si ce n’est pas le cas.

Tous les points de terminaison des flux de travail Data Bundle (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree et /v1/nodes/.../bundle) sont marqués expérimentaux. Attendez-vous à une évolution du contrat jusqu’à leur promotion vers le statut stable. Consultez Points de terminaison expérimentaux.

Scopes requis

Scope	Utilisation
read:bundle	Obtenir l’arbre d’entrée du périphérique, lister les sessions de téléversement, lister les options de traitement, lister les enregistrements de traitement, lister les URL de téléchargement des fichiers d’entrée
write:bundle	Créer un bundle, ouvrir et finaliser des sessions de téléversement, démarrer le traitement

Vous avez également besoin d’un accès au contenu et des permissions sur le nœud parent où le bundle est créé, ainsi que sur le bundle lui-même pour les étapes ultérieures.

Flux de bout en bout

flowchart LR
  A["1. Obtenir l'arbre d'entrée"] --> B["2. Créer le bundle"]
  B --> C["3. Téléverser les fichiers d'entrée"]
  C --> D["4. Lister les options de traitement"]
  D --> E["5. Démarrer le traitement"]
  E --> F["6. Interroger les enregistrements de traitement"]

Chaque étape numérotée correspond à un guide dédié :

Étape	Guide	Résumé
1–2	Création d’un Data Bundle	Obtenir l’arbre d’entrée du périphérique, choisir un dbuPath feuille, créer le bundle sous un nœud parent
3	Téléversement de données dans un Data Bundle	Ouvrir une session de téléversement, téléverser chaque fichier en multipart vers S3, finaliser
4–6	Traitement et suivi	Lister les sorties disponibles, lancer le traitement, interroger jusqu’à que chaque tâche atteigne un état terminal

Téléchargement des fichiers d’entrée est facultatif : utilisez-le uniquement lorsque vous avez besoin de récupérer à nouveau les fichiers d’entrée téléversés du bundle.

Modèle de validation

Les règles structurelles (types de fichiers obligatoires, extensions autorisées, dépendances inter-types, multiplicité) sont décrites dans le tableau requirements retourné lorsque vous ouvrez une session de téléversement. Il est de la responsabilité de l’utilisateur de respecter cette structure avant le téléversement et avant le lancement du traitement.

L’API de téléversement enregistre chaque fichier sous le type que vous fournissez et complète la session uniquement sur le nombre : une fois que finalizedFileCount atteint expectedFileCount, la session est completed. La validation profonde du contenu (qu’un .las est une capture authentique du périphérique, qu’un JSON de métadonnées référence correctement son image) intervient après le lancement d’un traitement, et non au moment du téléversement. Un fichier correctement nommé mais mal formé se téléverse sans erreur et échoue plus tard pendant le traitement.

Les échecs de traitement causés par une structure de téléversement incorrecte (types obligatoires manquants, dépendances non respectées, extensions incorrectes, etc.) ne seront pas remboursés.