Pular para o conteúdo
Prevu3D

Miniaturas de nó

Um nó de dados (divisão, site, pasta, twin e o restante da hierarquia) pode ter uma imagem de miniatura. Esta página cobre o envio, a substituição e a remoção dessa miniatura, além do custo e do tempo de vida da URL assinada que você recebe ao solicitá-la.

Enviando uma miniatura

Seção intitulada “Enviando uma miniatura”
MétodoCaminhoDescrição
POST/v1/nodes/{nodeId}/thumbnailIniciar: retorna um id de envio e uma URL do S3 pré-assinada
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalizeFinalizar: aplica a imagem enviada como a miniatura do nó
DELETE/v1/nodes/{nodeId}/thumbnailRemover: exclui a miniatura atual

As três exigem write:hierarchy e são marcadas como experimentais. Veja Endpoints experimentais.

Este é o mesmo formato iniciar/enviar/finalizar usado por vários outros endpoints de envio da RealityConnect API. Veja a Referência: envio multipart compartilhado para o mecanismo completo. Miniaturas de nó são o caso simples de arquivo único desse padrão: iniciar não recebe corpo de requisição e retorna exatamente uma URL pré-assinada, sem partNumber e sem endpoint de atualização. Faça um PUT da imagem para essa URL e depois chame finalize para aplicá-la. Se a URL expirar antes de você enviar o arquivo, inicie novamente para obter uma nova: não há nada para atualizar.

DELETE /v1/nodes/{nodeId}/thumbnail é idempotente: retorna 204 independentemente de o nó ter ou não uma miniatura.

Formatos aceitos e limites de tamanho

Seção intitulada “Formatos aceitos e limites de tamanho”

Iniciar não recebe corpo. Diferentemente de alguns outros fluxos de envio da API, você não declara nome do arquivo, tamanho ou tipo de conteúdo antecipadamente. A própria API não documenta nem impõe uma lista de formatos de imagem permitidos ou um tamanho máximo de arquivo; um arquivo que o processador de imagem downstream não consegue decodificar falha na finalização, não na etapa de PUT. Trate qualquer resposta diferente de 204 de finalize como “este arquivo não funcionou” e repasse isso ao chamador, em vez de presumir que qualquer imagem que você consiga enviar com PUT será aceita.

Recuperando uma miniatura

Seção intitulada “Recuperando uma miniatura”

GET /v1/nodes/{id}/browse e GET /v1/nodes/search aceitam ambos includeThumbnail=true (padrão false). Quando definido, cada nó na resposta recebe um campo thumbnailSignedUrl: null quando o nó não tem miniatura, uma URL assinada quando tem. Veja Tipos de nó e hierarquia para o restante do formato DataNode.

includeThumbnail é false por padrão porque não é gratuito: gerar e assinar uma URL é trabalho extra por nó, feito para cada item da página, não apenas para os que o chamador realmente renderiza. Solicitá-lo em uma chamada browse ou search já próxima do seu limite de tamanho de página (20 para browse, 50 para search) significa pagar esse custo pela página inteira. Solicite apenas na visualização que realmente renderiza imagens, não em uma listagem em massa ou em uma sincronização em segundo plano da árvore.

Tempo de vida da URL assinada

Seção intitulada “Tempo de vida da URL assinada”

thumbnailSignedUrl é um link pré-assinado, e a RCAPI não publica nem configura por quanto tempo ele permanece válido. Trate-o, portanto, como efêmero e opaco, não como um identificador durável. Não armazene em cache um thumbnailSignedUrl além da resposta que o retornou. Se sua integração armazena em cache resultados de browse ou search para renderizá-los novamente depois, busque-os novamente com includeThumbnail=true para obter uma URL atual, em vez de reutilizar uma armazenada: uma URL armazenada eventualmente deixará de resolver, servindo um link de imagem morto sem nenhum aviso no restante da resposta.

Miniaturas e exclusão reversível

Seção intitulada “Miniaturas e exclusão reversível”

Excluir um nó de forma reversível (DELETE /v1/nodes/{nodeId}) o move para a lixeira sem alterar sua miniatura. GET /v1/trash aceita o mesmo includeThumbnail=true e retorna o mesmo thumbnailSignedUrl para um nó na lixeira que browse e search teriam retornado antes de ele ser excluído. Restaurar o nó (PATCH /v1/nodes/{nodeId}/restore) o torna navegável e pesquisável novamente com a miniatura intacta; nada precisa ser reenviado. Excluir o nó permanentemente (DELETE /v1/nodes/{nodeId}/hard), ou deixar expirar os 30 dias de retenção na lixeira, remove a miniatura junto com todo o resto do nó. Veja O que excluir realmente faz, por recurso para o modelo completo de exclusão/restauração/purga.

Próximos passos

Seção intitulada “Próximos passos”