共享分段上传参考

多个 RealityConnect API 上传端点共享同一套底层模式：发起上传，将文件直接上传（PUT）到一个或多个签名 URL，然后完成上传。本页是该模式、其分段编号规则，以及如何在上传过程中刷新、续传并跟踪进度的共享参考。请从任何端点专属指南链接到本页，而不是重复该机制。

哪些端点使用此模式

流程	发起	完成	是否分段？	是否有刷新端点？
Data Bundle 上传	`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	`POST .../files/{fileId}/finalize`	是	是
对象附件	`POST /v1/twin/{contextId}/object/attachments`	`POST .../attachments/{fileId}/finalize`	是	是
站点文件	`POST /v1/site-files`	`POST /v1/site-files/{fileId}/finalize`	是	否
Asset Library 模型	`POST /v1/asset-library/{ownerContextId}/models`	`POST .../models/{libraryModelId}/finalize`	否（单个文件）	否
节点缩略图	`POST /v1/nodes/{nodeId}/thumbnail`	`POST /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize`	否（单个文件）	否

发起、上传、完成模式

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

  Client->>RCAPI: POST initiate
  RCAPI-->>Client: fileId/uploadId + 签名 URL
  loop for each part
    Client->>S3: PUT part
    S3-->>Client: ETag
  end
  Client->>RCAPI: POST finalize (附带 ETag)
  RCAPI-->>Client: 上传完成

发起：使用文件名和大小（以及该流程特有的字段，例如 Data Bundle 文件的 type）调用该流程的发起端点。响应会返回一个用于完成上传的标识符，以及一个或多个用于 PUT 文件的已签名 S3 url。
上传：将文件的字节直接 PUT 到返回的 URL。这些请求不会发送 Authorization 头，因为 URL 本身已经过签名。请保留每次 PUT 响应中的 ETag 头。
完成：使用收集到的 ETag 调用该流程的完成端点，完成上传。

Asset Library 模型和节点缩略图目前仅接受在一次 PUT 中上传单个文件，因此只有一个 URL、一个 ETag，没有任何 partNumber。可以将这两者视为同一模式下最简单的单分段情形。

分段编号：`partNumber` 与 `startIndex`

这适用于支持刷新的两个流程。

实例演示。 发起返回了 3 个分段：

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

要从 partNumber: 2 开始刷新，需减去 1，并使用 startIndex = 1 调用刷新：

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

响应的 startIndex 会原样返回 1，其 urls 再次携带从 2 开始、从 1 计数的 partNumber：

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

如果不做转换，直接把 partNumber（2 而不是 1）当作 startIndex 传入，就会跳过分段 2，只从分段 3 开始刷新。

在上传过程中刷新已过期的签名 URL

已签名的 PUT URL 会过期。如果上传耗时较长，某个分段的 PUT 开始返回 403，请针对你中断时所在的分段（即 startIndex = partNumber - 1）调用刷新端点。刷新会为该分段及其之后的每个分段返回新的 URL，因此你不需要逐个分段单独刷新，文件也不需要重新发起。

以下流程支持刷新：

Data Bundle 上传：GET /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files/{fileId}/refresh/{startIndex}
对象附件：GET /v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}

站点文件、Asset Library 模型和节点缩略图没有刷新端点。如果这些流程中的某个 URL 在上传过程中过期，请重新发起该文件以获取新的 URL。

续传部分完成的上传并跟踪进度

如何续传以及如何检查进度取决于具体流程：

Data Bundle 上传在会话级别跟踪进度。列出某个 Bundle 的上传会话（GET /v1/bundles/{bundleId}/upload-sessions），并比较 finalizedFileCount 与 expectedFileCount。要续传时，只需根据尚未显示为已完成的 type 和 fileName，仅对尚未完成的文件执行发起和完成。
对象附件、站点文件、Asset Library 模型和节点缩略图都是单文件操作，没有会话或列表可供查询。进度就是收到的 fileId（或 uploadId）是否已经成功完成。对于 Asset Library 模型，还可以通过模型自身的 status 字段查看进度，在完成之前该字段会保持 uploading。要在中断后续传这些流程中的任意一个，请保留发起时获得的标识符，继续上传剩余分段（如有需要且可用，刷新 URL），或者在标识符或其 URL 已无法使用时重新发起。

存储空间限制与对已存在文件的重新上传

如果请求本身无效，发起上传可能在发送任何字节之前就被拒绝，最常见的是组织存储配额已用尽时的 StorageLimitExceeded，以及对已存在相同标识的文件重新上传时的 FileAlreadyExists。这些是响应体中的命名错误代码，各端点对应的确切状态码见错误代码：文件上传。

后续步骤

查看错误代码，获取包括每个端点的 StorageLimitExceeded 和 FileAlreadyExists 在内的完整命名代码列表。
查看向 Data Bundle 上传数据，获取该模式最完整的实践示例，包括可续传的批量上传。