跳转到内容
Prevu3D

节点缩略图

数据节点（分部、站点、文件夹、twin 以及层级结构中的其他节点）可以携带一张缩略图。本页介绍如何上传、替换和移除该缩略图，以及请求时返回的签名 URL 的成本和有效期。

上传缩略图

Section titled “上传缩略图”
方法路径说明
POST/v1/nodes/{nodeId}/thumbnail发起：返回上传 id 和一个预签名的 S3 URL
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize完成：将已上传的图片应用为该节点的缩略图
DELETE/v1/nodes/{nodeId}/thumbnail移除：删除当前缩略图

这三个端点都需要 write:hierarchy，并被标记为实验性。参阅实验性端点。

这与 RealityConnect API 其他多个上传端点所使用的发起/上传/完成流程相同。完整机制请参阅共享分段上传参考。节点缩略图是该模式下简单的单文件情形：发起调用不携带请求体，只返回一个预签名 URL，没有 partNumber，也没有刷新端点。将图片 PUT 到该 URL，然后调用完成接口以应用它。如果 URL 在你上传之前过期，重新发起以获取新的 URL。没有可刷新的东西。

DELETE /v1/nodes/{nodeId}/thumbnail 是幂等的：无论该节点此前是否有缩略图，都会返回 204。

支持的格式与大小限制

Section titled “支持的格式与大小限制”

发起调用不携带请求体。与 API 的部分其他上传流程不同，你无需预先声明文件名、大小或内容类型。API 本身并未记录或强制执行图片格式的允许列表，也没有最大文件大小限制；下游图片处理器无法解码的文件会在完成阶段失败，而不是在 PUT 阶段失败。将完成接口返回的任何非 204 响应都视为“该文件未被接受”，并将此结果反馈给调用方，而不要假定任何可以 PUT 的图片都会被接受。

获取缩略图

Section titled “获取缩略图”

GET /v1/nodes/{id}/browse 和 GET /v1/nodes/search 都接受 includeThumbnail=true（默认 false）。设置后，响应中的每个节点都会带有 thumbnailSignedUrl 字段：节点没有缩略图时为 null，有缩略图时则是一个签名 URL。DataNode 其余字段的说明请参阅节点类型与层级结构。

includeThumbnail 默认是 false，因为它并非没有成本：生成并签名一个 URL 是按节点计算的额外开销，会作用于页面上的每一项，而不只是调用方实际渲染的那些项。在已经接近分页上限（browse 为 20，search 为 50）的 browse 或 search 调用中请求它，就意味着要为整页付出这一成本。只在真正渲染图片的视图中请求它，而不要用于批量列表或后台的树形同步。

签名 URL 的有效期

Section titled “签名 URL 的有效期”

thumbnailSignedUrl 是一个预签名链接，RCAPI 并未公布或配置它的有效时长。因此应将其视为短暂且不透明的东西，而非持久标识符。不要在返回它的那次响应之外缓存 thumbnailSignedUrl。如果你的集成会缓存 browse 或 search 的结果并在之后重新渲染，请使用 includeThumbnail=true 重新获取以取得最新的 URL，而不要复用已存储的 URL：存储的 URL 最终会失效，在响应其余部分毫无警示的情况下提供一个失效的图片链接。

缩略图与软删除

Section titled “缩略图与软删除”

对节点执行软删除（DELETE /v1/nodes/{nodeId}）会将其移入回收站，而不会影响其缩略图。GET /v1/trash 同样接受 includeThumbnail=true，对回收站中的节点，返回的 thumbnailSignedUrl 与该节点被删除前 browse 和 search 所返回的相同。恢复该节点（PATCH /v1/nodes/{nodeId}/restore）会使其缩略图保持完整，并重新变得可浏览和可搜索。无需重新上传任何内容。永久删除该节点（DELETE /v1/nodes/{nodeId}/hard），或让其在回收站中的 30 天保留期届满，会连同节点上的其他一切一并移除缩略图。完整的删除/恢复/清除模型请参阅删除究竟做了什么(按资源划分)。

下一步是什么？

Section titled “下一步是什么？”