コンテンツにスキップ
Prevu3D

ノードのサムネイル

データノード（ディビジョン、サイト、フォルダ、ツイン、その他の階層）はサムネイル画像を持つことができます。このページでは、そのサムネイルのアップロード、置き換え、削除、および要求時に返される署名付きURLのコストと有効期間について説明します。

サムネイルのアップロード

Section titled “サムネイルのアップロード”
メソッドパス説明
POST/v1/nodes/{nodeId}/thumbnail開始：アップロードIDと署名済みS3 URLを返します
POST/v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize確定：アップロードされた画像をノードのサムネイルとして適用します
DELETE/v1/nodes/{nodeId}/thumbnail削除：現在のサムネイルを削除します

3つとも write:hierarchy が必要で、実験的とマークされています。実験的エンドポイントを参照してください。

これはRealityConnect APIの他の複数のアップロードエンドポイントで使われているのと同じ開始/アップロード/確定の形です。完全な仕組みについては共有マルチパートアップロードリファレンスを参照してください。ノードのサムネイルは、そのパターンの単純な単一ファイルのケースです。開始はリクエストボディを取らず、署名済みURLをちょうど1つ返し、partNumber もリフレッシュエンドポイントもありません。画像をそのURLにPUTし、それを適用するために確定を呼び出してください。アップロードする前に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の結果をキャッシュして後で再表示する場合は、保存したURLを再利用するのではなく、includeThumbnail=true を付けて再取得し、最新のURLを取得してください。保存されたURLはいずれ解決できなくなり、レスポンスの他の部分から警告のないまま無効な画像リンクを提供することになります。

サムネイルとソフトデリート

Section titled “サムネイルとソフトデリート”

ノードのソフトデリート（DELETE /v1/nodes/{nodeId}）は、サムネイルに触れることなくノードをゴミ箱に移動します。GET /v1/trash は同じ includeThumbnail=true を受け付け、ゴミ箱内のノードに対して、削除前にbrowseやsearchが返していたのと同じ thumbnailSignedUrl を返します。ノードの復元（PATCH /v1/nodes/{nodeId}/restore）は、サムネイルを保持したまま再びbrowseやsearchの対象にします。再アップロードは不要です。ノードの完全削除（DELETE /v1/nodes/{nodeId}/hard）、または30日間のゴミ箱保持期間の経過は、ノードの他のすべてとともにサムネイルも削除します。完全な削除/復元/パージのモデルについては削除が実際に何をするか(リソース別)を参照してください。

次のステップ

Section titled “次のステップ”