Introdução aos Data Bundles

Um data bundle é o contêiner de uma captura: arquivos de entrada brutos (nuvens de pontos, trajetórias, imagens e assim por diante) mais as saídas processadas que a plataforma gera a partir deles. A RealityConnect API expõe o mesmo ciclo de vida de bundle que a interface da Prevu3D usa, para que integrações possam criar bundles, enviar dados, iniciar o processamento, acompanhar o progresso e recuperar arquivos de entrada sem um navegador.

Este documento pressupõe que você concluiu um fluxo OAuth e possui um access_token, sua api_url regional e seu organization_id. Consulte os guias de fluxo caso não os tenha.

Todos os endpoints do fluxo de trabalho de data bundle (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree e /v1/nodes/.../bundle) são marcados como experimentais. Espere que o contrato evolua até que eles se tornem estáveis. Consulte Endpoints experimentais.

Escopos necessários

Escopo	Usado para
read:bundle	Obter a árvore de entrada de dispositivos, listar sessões de envio, listar opções de processamento, listar registros de processamento, listar URLs de download de arquivos de entrada
write:bundle	Criar um bundle, abrir e finalizar sessões de envio, iniciar o processamento

Você também precisa de acesso ao conteúdo e permissões de nó no nó pai onde o bundle é criado, e no próprio bundle para as etapas posteriores.

Fluxo de ponta a ponta

flowchart LR
  A["1. Obter a árvore de entrada"] --> B["2. Criar o bundle"]
  B --> C["3. Enviar arquivos de entrada"]
  C --> D["4. Listar opções de processamento"]
  D --> E["5. Iniciar o processamento"]
  E --> F["6. Consultar registros de processamento"]

Cada etapa numerada corresponde a um guia dedicado:

Etapa	Guia	Resumo
1–2	Criando um Data Bundle	Obter a árvore de entrada de dispositivos, escolher um dbuPath de folha, criar o bundle sob um nó pai
3	Enviando Dados para um Data Bundle	Abrir uma sessão de envio, fazer upload multipart de cada arquivo para o S3, finalizar
4–6	Processamento e Monitoramento	Listar as saídas disponíveis, iniciar o processamento, consultar até que cada trabalho atinja um estado terminal

Baixando Arquivos de Entrada é opcional: use-o somente quando precisar recuperar novamente os arquivos de entrada enviados do bundle.

Modelo de validação

As regras estruturais (tipos de arquivo obrigatórios, extensões permitidas, dependências entre tipos, multiplicidade) são descritas no array requirements retornado quando você abre uma sessão de envio. É responsabilidade do usuário seguir essa estrutura antes de enviar e antes de iniciar o processamento.

A API de envio registra cada arquivo sob o type que você fornece e conclui a sessão apenas com base na contagem. A validação aprofundada do conteúdo (se um .las é realmente uma captura de dispositivo, se o JSON de metadados referencia corretamente sua imagem) acontece após o início de um processamento, não no momento do envio. Um arquivo com nome correto, mas malformado, é enviado sem erro e falha mais tarde durante o processamento.

Falhas de processamento causadas por uma estrutura de envio incorreta (tipos obrigatórios ausentes, dependências quebradas, extensões erradas e assim por diante) não serão reembolsadas.