Referência: envio multipart compartilhado

Vários endpoints de envio da RealityConnect API compartilham o mesmo padrão subjacente: iniciar o envio, enviar (PUT) o arquivo diretamente para uma ou mais URLs assinadas e, em seguida, finalizá-lo. Esta página é a referência compartilhada para esse padrão, sua regra de numeração de partes, e como renovar, retomar e acompanhar um envio. Aponte para esta página a partir de qualquer guia específico de endpoint, em vez de repetir o mecanismo.

Quais endpoints usam esse padrão

Fluxo	Iniciar	Finalizar	Dividido em partes?	Endpoint de renovação?
Uploads de Data Bundle	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	Sim	Sim
Anexos de objeto	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	Sim	Sim
Arquivos de site	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	Sim	Não
Modelos da Asset Library	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	Não (um único arquivo)	Não
Miniaturas de nó	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	Não (um único arquivo)	Não

O padrão iniciar, enviar, finalizar

sequenceDiagram
  participant Client as Client
  participant RCAPI as RCAPI
  participant S3 as S3

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + URL(s) assinada(s)
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (com os ETag)
  RCAPI-->>Client: envio concluído

Iniciar: chame o endpoint de início do fluxo com o nome e o tamanho do arquivo (e quaisquer campos específicos do fluxo, como o type de um arquivo de Data Bundle). A resposta retorna um identificador para finalizar, além de uma ou mais url da S3 assinadas para as quais fazer PUT do arquivo.
Enviar: faça PUT dos bytes do arquivo diretamente para a(s) URL(s) retornada(s). Nenhum cabeçalho Authorization é enviado nessas requisições; a URL já está assinada. Guarde o cabeçalho de resposta ETag de cada PUT.
Finalizar: chame o endpoint de finalização do fluxo com o(s) ETag(s) coletado(s) para concluir o envio.

Os modelos da Asset Library e as miniaturas de nó atualmente aceitam apenas um único arquivo em um único PUT, então há apenas uma URL, um ETag, e nenhum partNumber. Trate esses dois como o caso simples de parte única do mesmo padrão.

Numeração de partes: `partNumber` versus `startIndex`

Isso se aplica aos dois fluxos que suportam renovação.

Exemplo prático. Iniciar retorna 3 partes:

{
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" },
    { "partNumber": 2, "url": "https://s3…/part-2?…" },
    { "partNumber": 3, "url": "https://s3…/part-3?…" }
  ]
}

Para renovar a partir de partNumber: 2, subtraia 1 e chame a renovação com startIndex = 1:

GET {api_url}/.../refresh/1

A resposta reflete 1 em startIndex, e seus urls novamente trazem partNumber baseados em 1 a partir de 2:

{ "startIndex": 1, "urls": [ { "partNumber": 2, "url": "…" }, { "partNumber": 3, "url": "…" } ] }

Passar o partNumber sem alteração (2 em vez de 1) como startIndex pularia a parte 2 e renovaria apenas a partir da parte 3.

Renovando URLs assinadas expiradas durante o envio

URLs PUT assinadas expiram. Se um envio demorar e o PUT de uma parte começar a retornar 403, chame o endpoint de renovação para a parte em que você parou (como startIndex = partNumber - 1). A renovação retorna URLs novas para essa parte e todas as seguintes, portanto você não precisa renovar cada parte individualmente, e o arquivo não precisa ser reiniciado.

A renovação está disponível para:

Uploads de Data Bundle: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
Anexos de objeto: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

Arquivos de site, modelos da Asset Library e miniaturas de nó não têm endpoint de renovação. Se uma URL expirar no meio do envio em um desses fluxos, reinicie o arquivo para obter uma URL nova.

Retomando um envio parcial e acompanhando o progresso

Como retomar e como verificar o progresso depende do fluxo:

Uploads de Data Bundle acompanham o progresso no nível da sessão. Liste as sessões de upload de um bundle (GET /v1/bundles/{bundleId}/upload-sessions) e compare finalizedFileCount com expectedFileCount. Para retomar, inicie e finalize apenas os arquivos que ainda não foram concluídos, usando o type e o fileName que ainda não aparecem como finalizados.
Anexos de objeto, arquivos de site, modelos da Asset Library e miniaturas de nó são operações de arquivo único, sem sessão ou lista para consultar. O progresso é simplesmente se a finalização já foi bem-sucedida para o fileId (ou uploadId) recebido. Os modelos da Asset Library também expõem isso no próprio campo status do modelo, que permanece uploading até que a finalização seja concluída. Para retomar qualquer um desses fluxos após uma interrupção, guarde o identificador recebido ao iniciar e continue enviando as partes restantes (renovando as URLs quando necessário, onde disponível), ou reinicie caso o identificador ou suas URLs não possam mais ser usados.

Limites de armazenamento e reenvio de um arquivo existente

Iniciar um envio pode ser rejeitado antes de qualquer byte ser enviado, se a própria requisição for inválida, o mais comum é StorageLimitExceeded, quando a cota de armazenamento da organização já foi excedida, ou FileAlreadyExists, ao reenviar um arquivo que já existe com a mesma identidade. Esses são códigos de erro nomeados no corpo da resposta, catalogados com o código de status exato por endpoint em Códigos de erro: Uploads de arquivo.

E agora?

Códigos de erro para a lista completa de códigos nomeados, incluindo StorageLimitExceeded e FileAlreadyExists por endpoint.
Enviando dados para um Data Bundle para o exemplo prático mais completo desse padrão, incluindo um envio em lote retomável.