Riferimento: caricamento multipart condiviso

Diversi endpoint di caricamento della RealityConnect API condividono lo stesso schema di base: avviare il caricamento, caricare (PUT) il file direttamente verso uno o più URL prefirmati e infine finalizzarlo. Questa pagina è il riferimento condiviso per questo schema, per la sua regola di numerazione delle parti e per come rinnovare, riprendere e monitorare un caricamento. Rimanda a questa pagina da qualsiasi guida specifica di un endpoint invece di ripetere il meccanismo.

---

Quali endpoint usano questo schema

Flusso	Avvia	Finalizza	Suddiviso in parti?	Endpoint di rinnovo?
Caricamenti di Data Bundle	POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	POST .../files/{fileId}/finalize	Sì	Sì
Allegati oggetto	POST /v1/twin/{contextId}/object/attachments	POST .../attachments/{fileId}/finalize	Sì	Sì
File del sito	POST /v1/site-files	POST /v1/site-files/{fileId}/finalize	Sì	No
Modelli dell’asset library	POST /v1/asset-library/{ownerContextId}/models	POST .../models/{libraryModelId}/finalize	No (un solo file)	No
Miniature dei nodi	POST /v1/nodes/{nodeId}/thumbnail	POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize	No (un solo file)	No

Lo schema avvia, carica, finalizza

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

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + URL prefirmato/i
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (con gli ETag)
  RCAPI-->>Client: caricamento completato

1. Avvia: chiama l’endpoint di avvio del flusso con il nome e la dimensione del file (e gli eventuali campi specifici del flusso, come il type di un file di Data Bundle). La risposta restituisce un identificativo per la finalizzazione e uno o più url S3 prefirmati verso cui fare PUT del file.
2. Carica: esegui il PUT dei byte del file direttamente verso l’URL (o gli URL) restituiti. Su queste richieste non viene inviata alcuna intestazione Authorization; l’URL è già firmato. Conserva l’intestazione di risposta ETag di ogni PUT.
3. Finalizza: chiama l’endpoint di finalizzazione del flusso con gli ETag raccolti per completare il caricamento.

I modelli dell’asset library e le miniature dei nodi attualmente accettano un solo file in un unico PUT, quindi c’è un solo URL, un solo ETag e nessun partNumber. Considera questi due come il caso semplice a parte singola dello stesso schema.

Numerazione delle parti: partNumber rispetto a startIndex

Attenzione

I valori di partNumber restituiti dall’avvio (e dal rinnovo) sono basati su 1: la prima parte è partNumber: 1. Lo startIndex che invii al rinnovo è basato su 0: la prima parte è l’indice 0. Per rinnovare una determinata parte, passa partNumber - 1, non partNumber così com’è.

Questo vale per i due flussi che supportano il rinnovo.

Esempio pratico. L’avvio restituisce 3 parti:

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

Per rinnovare a partire da partNumber: 2, sottrai 1 e chiama il rinnovo con startIndex = 1:

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

La risposta riflette 1 in startIndex, e i suoi urls riportano di nuovo partNumber basati su 1 a partire da 2:

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

Passare partNumber senza modifiche (2 invece di 1) come startIndex salterebbe la parte 2 e rinnoverebbe solo a partire dalla parte 3.

Rinnovare URL firmati scaduti durante il caricamento

Gli URL PUT prefirmati scadono. Se un caricamento si protrae e il PUT di una parte inizia a restituire 403, chiama l’endpoint di rinnovo per la parte a cui ti eri fermato (come startIndex = partNumber - 1). Il rinnovo restituisce URL nuovi per quella parte e tutte quelle successive, quindi non è necessario rinnovare ogni parte singolarmente, e il file non deve essere riavviato.

Il rinnovo è disponibile per:

• Caricamenti di Data Bundle: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
• Allegati oggetto: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

File del sito, modelli dell’asset library e miniature dei nodi non hanno un endpoint di rinnovo. Se un URL scade a metà caricamento in uno di questi flussi, riavvia il file per ottenere un URL nuovo.

Riprendere un caricamento parziale e monitorare i progressi

Il modo per riprendere e controllare i progressi dipende dal flusso:

• I caricamenti di Data Bundle monitorano i progressi a livello di sessione. Elenca le sessioni di caricamento di un bundle (GET /v1/bundles/{bundleId}/upload-sessions) e confronta finalizedFileCount con expectedFileCount. Per riprendere, avvia e finalizza solo i file non ancora completati, usando il type e il fileName che non compaiono ancora come finalizzati.
• Allegati oggetto, file del sito, modelli dell’asset library e miniature dei nodi sono operazioni a file singolo, senza sessione o elenco da interrogare: il progresso è semplicemente se la finalizzazione è già andata a buon fine per il fileId (o uploadId) ricevuto. I modelli dell’asset library lo espongono anche tramite il campo status del modello stesso, che resta uploading fino al completamento della finalizzazione. Per riprendere uno qualsiasi di questi flussi dopo un’interruzione, conserva l’identificativo ricevuto all’avvio e continua a caricare le parti rimanenti (rinnovando gli URL se necessario, dove disponibile), oppure riavvia se l’identificativo o i suoi URL non sono più utilizzabili.

Limiti di archiviazione e nuovo caricamento di un file esistente

L’avvio di un caricamento può essere rifiutato prima ancora che venga inviato un solo byte, se la richiesta stessa non è valida: il caso più comune è StorageLimitExceeded, quando la quota di archiviazione dell’organizzazione è già stata superata, oppure FileAlreadyExists, quando si ricarica un file che esiste già con la stessa identità. Questi sono codici di errore con nome nel corpo della risposta, catalogati con il codice di stato esatto per endpoint in Codici di errore: Caricamento di file.

Prossimi passi

• Codici di errore per l’elenco completo dei codici con nome, inclusi StorageLimitExceeded e FileAlreadyExists per endpoint.
• Caricare dati in un Data Bundle per l’esempio pratico più completo di questo schema, incluso un caricamento in batch ripetibile.