Valores de metadados tipados e anexos

As propriedades de metadados de objetos de negócio (metadata em GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata) não se limitam a strings, números e booleanos simples. Um valor de propriedade também pode ser um objeto marcado que carrega um campo especial _p3d_type, usado para representar um link externo ou um anexo de arquivo enviado. Esta página documenta essa união de valores e o fluxo de envio por trás do tipo attachment.

---

A união de valores de metadados

Cada propriedade dentro de uma seção de metadados é uma das seguintes:

Tipo de valor	Formato
String simples	"A short text"
Número simples	42
Booleano simples	true
Link externo	{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Anexo	{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type é o discriminador: seu valor literal indica qual dos dois formatos marcados você está vendo. Fora isso, ambos os formatos marcados são objetos simples; nenhum endpoint adicional é necessário para lê-los, eles retornam em linha onde quer que os metadados sejam retornados.

Cuidado

Apenas esses cinco tipos de valor são armazenados. Um objeto marcado com qualquer outro _p3d_type é descartado sem erro: o PATCH ainda retorna 200, e a propriedade simplesmente não aparece na resposta nem em leituras posteriores.

Nota

Os menus suspensos são definidos em um tipo de ativo, e os tipos de ativo são somente leitura pela API, então você não pode criar um menu suspenso aqui. Você pode, porém, fazer um aparecer: defina o assetTypeId de um ativo (na criação, ou com PATCH /v1/twin/{contextId}/assets/{assetId}) para um tipo de ativo que defina um, e essa propriedade aparece como menu suspenso no RealityTwin. Pela API, seu valor é lido e gravado como uma string simples.

{
  "Section name": {
    "name": "A short text",
    "numeric value": 42,
    "toggle name": true,
    "documentation link": {
      "url": "https://doc.prevu3d.com/",
      "text": "https://doc.prevu3d.com/",
      "_p3d_type": "urn:primitive:obj:external-link"
    },
    "landing image": {
      "name": "prevu_logo.jpg",
      "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
      "_p3d_type": "urn:primitive:obj:attachment"
    }
  }
}

Link externo (urn:primitive:obj:external-link)

Campo	Tipo	Notas
url	string	O destino do link.
text	string	Texto de exibição do link.
_p3d_type	string	Sempre urn:primitive:obj:external-link.

Um link externo é autocontido; defina o objeto diretamente em uma escrita de metadados, sem envio de arquivo envolvido.

Anexo (urn:primitive:obj:attachment)

Campo	Tipo	Notas
name	string	Nome do arquivo original.
id	string	O fileId do anexo, obtido no fluxo de envio abaixo.
_p3d_type	string	Sempre urn:primitive:obj:attachment.

Diferente do link externo, um valor attachment referencia um arquivo que precisa existir primeiro. Enviá-lo é uma sequência de chamadas separada e em várias etapas, coberta a seguir.

Anexando um arquivo aos metadados

Fazer com que um arquivo seja referenciado como valor attachment é uma sequência de três etapas: iniciar o envio, enviar as partes para o S3, finalizá-lo; depois usar o id de arquivo retornado como o campo id de um valor attachment na sua próxima escrita de metadados.

Método	Caminho	Escopo	Finalidade
POST	/v1/twin/{contextId}/object/attachments	write:asset	Iniciar um envio de anexo
GET	/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}	write:asset	Reemitir URLs de partes expiradas
POST	/v1/twin/{contextId}/object/attachments/{fileId}/finalize	write:asset	Finalizar o envio
GET	/v1/twin/{contextId}/object/attachments/{fileId}/download	read:asset	Obter uma URL de download assinada
DELETE	/v1/twin/{contextId}/object/attachments/{fileId}	write:asset	Remover um anexo

contextId é o twin, site ou rascunho ao qual o anexo pertence; o mesmo id usado na pesquisa de objetos de negócio.

Cuidado

Os cinco endpoints de anexo acima estão marcados como experimentais na referência da API e podem mudar. Os endpoints de metadados GET/PATCH que eles alimentam não estão.

O envio em si segue a mesma mecânica genérica de iniciar → enviar partes → finalizar usada em outros pontos da API (multipart, URLs pré-assinadas do S3, renováveis caso expirem). Veja a referência de envio multipart compartilhada para essa mecânica e sua armadilha de numeração de partes. Esta seção cobre apenas o que é específico dos anexos.

Etapa 1: iniciar

POST {api_url}/v1/twin/{contextId}/object/attachments
Authorization: Bearer {access_token}
Content-Type: application/json

{ "fileName": "prevu_logo.jpg", "fileSize": 84213, "mimeType": "image/jpeg" }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "parts": 1,
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" }
  ]
}

Etapa 2: enviar as partes

Faça PUT de cada bloco para sua url pré-assinada, guardando o ETag retornado por parte, exatamente como descrito na referência de envio multipart compartilhada.

Etapa 3: finalizar

POST {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/finalize
Authorization: Bearer {access_token}
Content-Type: application/json

{ "parts": [ { "partNumber": 1, "etag": "\"a1b2c3d4e5f6\"" } ] }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "fileName": "prevu_logo.jpg",
  "size": 84213
}

Etapa 4: referenciar o arquivo nos metadados

Pegue o fileId da resposta de finalização e defina-o como o id de um valor attachment na sua próxima escrita de metadados:

PATCH {api_url}/v1/twin/{contextId}/object/{objectId}/metadata
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "metadata": {
    "Section name": {
      "landing image": {
        "name": "prevu_logo.jpg",
        "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
        "_p3d_type": "urn:primitive:obj:attachment"
      }
    }
  }
}

Uma escrita de metadados recebe o objeto de metadados completo (seções e propriedades novas, atualizadas e removidas juntas), não um patch de uma única propriedade. Portanto, inclua cada seção e propriedade que deseja manter junto com a nova referência de anexo.

Lendo valores marcados de volta

GET /v1/twin/{contextId}/object/{objectId}/metadata retorna cada propriedade exatamente como foi escrita: uma string/número/booleano simples, ou um dos dois objetos marcados acima com _p3d_type intacto. Não há uma etapa de “resolução” separada para ler um valor marcado; o objeto em si, incluindo o id do anexo, retorna em linha na resposta de metadados.

Para obter os bytes do arquivo, passe esse id como fileId para o endpoint de download abaixo.

Fazendo download e removendo um anexo

GET {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/download
Authorization: Bearer {access_token}

{ "url": "https://d111111abcdef8.cloudfront.net/…" }

A URL retornada é um link assinado do CloudFront, válido por aproximadamente 4 horas. Obtenha uma nova se ela expirar.

Para remover o arquivo subjacente de um anexo:

DELETE {api_url}/v1/twin/{contextId}/object/attachments/{fileId}
Authorization: Bearer {access_token}

Nota

Excluir o arquivo não remove automaticamente sua referência de nenhuma propriedade de metadados que aponte para ele. Limpe a referência com uma escrita de metadados se não quiser mais que ela apareça.

Limites de anexos

O armazenamento de anexos usa a mesma alocação de armazenamento por organização de qualquer outro arquivo no RealityConnect; não existe uma “cota de anexos” separada.

Pergunta	Resposta
Tamanho máximo de um único anexo	Nenhum limite de tamanho dedicado é aplicado. O teto prático é o espaço de armazenamento restante da sua organização.
Número máximo de anexos por objeto	Nenhum limite de quantidade dedicado é aplicado. Uma seção de metadados pode conter qualquer número de propriedades do tipo attachment.
Total por twin ou por organização	Não existe uma cota de anexos separada. Cada anexo é armazenado como um arquivo comum e conta para a alocação total de armazenamento da sua organização; o mesmo contador usado por qualquer outro arquivo enviado. StorageLimitExceeded (veja Códigos de erro) é retornado assim que o uso ultrapassa o armazenamento alocado para sua organização. Essa alocação é específica do plano, portanto não há um número único a divulgar aqui; consulte sua equipe de conta Prevu3D para saber o número da sua organização.
Tipos de arquivo aceitos	Qualquer mimeType enviado é aceito; não há uma lista de permissões a cumprir.
Mesmo arquivo anexado a vários objetos	Armazenado uma vez por envio, não uma vez por referência. Enviar os mesmos bytes duas vezes (duas sequências initiate → finalize separadas) cria dois arquivos armazenados separadamente; não há deduplicação automática. Para anexar um mesmo documento compartilhado a vários objetos sem armazená-lo duas vezes, envie-o uma vez e reutilize o id retornado no valor attachment de cada objeto, em vez de enviá-lo novamente.

Nota

As respostas acima sobre tamanho e quantidade descrevem o que o caminho de envio aplica hoje, não um teto de produto divulgado. Se sua integração precisar de um número firme para projetar (por exemplo, anexar uma foto a cada ativo em massa), confirme os números atuais com a equipe da Prevu3D antes de se comprometer com um design.

Próximos passos

• Referência de envio multipart compartilhada para a mecânica genérica de iniciar/enviar/finalizar.
• Pesquisando objetos de negócio e nós para como o contextId é resolvido.
• Consulte a referência da API para os esquemas completos de requisição e resposta de cada operação.