Referenz: Gemeinsamer Multipart-Upload

Mehrere Upload-Endpunkte der RealityConnect API teilen sich dasselbe zugrunde liegende Muster: die Datei initiieren, sie direkt an eine oder mehrere presignierte URLs hochladen (PUT) und anschließend finalisieren. Diese Seite ist die gemeinsame Referenz für dieses Muster, seine Teilenummerierung sowie das Erneuern, Fortsetzen und Überwachen eines Uploads. Verlinken Sie hierher aus jedem endpunktspezifischen Leitfaden, statt den Mechanismus zu wiederholen.

Welche Endpunkte dieses Muster verwenden

Flow	Initiieren	Finalisieren	In Teile aufgeteilt?	Refresh-Endpunkt?
Data Bundle-Uploads	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	Ja	Ja
Objekt-Anhänge	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	Ja	Ja
Site-Dateien	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	Ja	Nein
Asset-Library-Modelle	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	Nein (eine Datei)	Nein
Node-Vorschaubilder	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	Nein (eine Datei)	Nein

Der Ablauf: Initiieren, Hochladen, Finalisieren

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

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + presignierte URL(s)
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (mit ETags)
  RCAPI-->>Client: Upload abgeschlossen

Initiieren: rufen Sie den Initiieren-Endpunkt des Flows mit Name und Größe der Datei auf (sowie flow-spezifischen Feldern, etwa dem type einer Data-Bundle-Datei). Die Antwort liefert eine Kennung zum Finalisieren sowie eine oder mehrere presignierte S3-urls, an die die Datei per PUT gesendet wird.
Hochladen: senden Sie die Bytes der Datei direkt per PUT an die zurückgegebene(n) URL(s). Bei diesen Anfragen wird kein Authorization-Header gesendet; die URL ist bereits signiert. Bewahren Sie den ETag-Antwortheader jedes PUT auf.
Finalisieren: rufen Sie den Finalisieren-Endpunkt des Flows mit den gesammelten ETag(s) auf, um den Upload abzuschließen.

Asset-Library-Modelle und Node-Vorschaubilder akzeptieren derzeit nur eine einzelne Datei in einem PUT, es gibt also nur eine URL, einen ETag und keine partNumber. Betrachten Sie diese beiden als den einfachen Ein-Teil-Fall desselben Musters.

Teilenummerierung: `partNumber` vs. `startIndex`

Dies betrifft die beiden Flows, die Refresh unterstützen.

Ausgearbeitetes Beispiel. Initiieren liefert 3 Teile:

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

Um ab partNumber: 2 zu erneuern, ziehen Sie 1 ab und rufen Refresh mit startIndex = 1 auf:

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

Die Antwort spiegelt in startIndex wieder 1 wider, und ihre urls tragen erneut 1-basierte partNumber-Werte ab 2:

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

Würde man partNumber unverändert (2 statt 1) als startIndex übergeben, würde Teil 2 übersprungen und nur ab Teil 3 erneuert.

Abgelaufene presignierte URLs während des Uploads erneuern

Presignierte PUT-URLs laufen ab. Läuft ein Upload lange und liefert das PUT eines Teils 403, rufen Sie den Refresh-Endpunkt für den Teil auf, bei dem Sie stehen geblieben sind (als startIndex = partNumber - 1). Refresh liefert frische URLs für diesen Teil und jeden nachfolgenden Teil, sodass Sie nicht jeden Teil einzeln erneuern müssen, und die Datei muss nicht erneut initiiert werden.

Refresh ist verfügbar für:

Data Bundle-Uploads: GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
Objekt-Anhänge: GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

Site-Dateien, Asset-Library-Modelle und Node-Vorschaubilder haben keinen Refresh-Endpunkt. Läuft bei einem dieser Flows eine URL während des Uploads ab, initiieren Sie die Datei erneut, um eine frische URL zu erhalten.

Einen unterbrochenen Upload fortsetzen und den Fortschritt verfolgen

Wie Sie fortsetzen und den Fortschritt prüfen, hängt vom Flow ab:

Data Bundle-Uploads verfolgen den Fortschritt auf Session-Ebene. Listen Sie die Upload-Sessions eines Bundles auf (GET /v1/bundles/{bundleId}/upload-sessions) und vergleichen Sie finalizedFileCount mit expectedFileCount. Um fortzusetzen, initiieren und finalisieren Sie nur die Dateien, die noch nicht abgeschlossen sind, anhand von type und fileName, die noch nicht als finalisiert erscheinen.
Objekt-Anhänge, Site-Dateien, Asset-Library-Modelle und Node-Vorschaubilder sind Einzeldatei-Vorgänge ohne Session oder Liste zum Abfragen. Der Fortschritt besteht schlicht darin, ob das Finalisieren für die erhaltene fileId (bzw. uploadId) bereits erfolgreich war. Bei Asset-Library-Modellen zeigt sich dies zusätzlich im status-Feld des Modells, das bis zum Abschluss des Finalisierens uploading lautet. Um einen dieser Flows nach einer Unterbrechung fortzusetzen, behalten Sie die von Initiieren erhaltene Kennung und laden entweder die verbleibenden Teile weiter hoch (erneuern Sie URLs bei Bedarf, sofern verfügbar) oder initiieren erneut, falls die Kennung oder ihre URLs nicht mehr verwendet werden können.

Speicherlimits und erneutes Hochladen einer vorhandenen Datei

Das Initiieren eines Uploads kann bereits vor dem Senden von Daten abgelehnt werden, wenn die Anfrage selbst ungültig ist, am häufigsten StorageLimitExceeded, wenn das Speicherkontingent der Organisation bereits ausgeschöpft ist, oder FileAlreadyExists beim erneuten Hochladen über eine bereits vorhandene Datei mit derselben Identität. Dies sind benannte Fehlercodes im Antworttext, die mit ihrem genauen Statuscode je Endpunkt in Fehlercodes: Datei-Uploads aufgeführt sind.

Wie geht es weiter?

Fehlercodes für die vollständige Liste der benannten Codes, einschließlich StorageLimitExceeded und FileAlreadyExists je Endpunkt.
Daten in ein Data Bundle hochladen für das ausführlichste ausgearbeitete Beispiel dieses Musters, einschließlich eines fortsetzbaren Batch-Uploads.