型付きメタデータ値と添付ファイル

ビジネスオブジェクトのメタデータプロパティ（GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadataのmetadata）は、単純なstring、number、booleanだけに限定されません。プロパティ値は、外部リンクまたはアップロードされたファイル添付を表す特別な_p3d_typeフィールドを持つタグ付きオブジェクトにもなり得ます。このページでは、この値のユニオンとattachment型の背後にあるアップロードフローを説明します。

メタデータ値のユニオン

メタデータセクション内の各プロパティは、次のいずれかです。

値の種類	形式
単純なstring	`"A short text"`
単純なnumber	`42`
単純なboolean	`true`
External link	`{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }`
Attachment	`{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }`

_p3d_typeは判別子です。その値によって、2つのタグ付き形式のどちらであるかがわかります。それ以外の点では、両方のタグ付き形式は単なるオブジェクトです。読み取り用の追加エンドポイントは不要で、メタデータが返される場所であればどこでもインラインで返されます。

{
  "Section name": {
    "name": "A short text",
    "numeric value": 42,
    "toggle name": true,
    "documentation link": {
      "url": "https://doc.prevu3d.com/",
      "text": "https://doc.prevu3d.com/",
      "_p3d_type": "urn:primitive:obj:external-link"
    },
    "landing image": {
      "name": "prevu_logo.jpg",
      "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
      "_p3d_type": "urn:primitive:obj:attachment"
    }
  }
}

External link（`urn:primitive:obj:external-link`）

フィールド	型	備考
`url`	string	リンク先。
`text`	string	リンクの表示テキスト。
`_p3d_type`	string	常に`urn:primitive:obj:external-link`。

External linkは自己完結型です。メタデータの書き込み時にオブジェクトを直接設定すればよく、アップロードは不要です。

Attachment（`urn:primitive:obj:attachment`）

フィールド	型	備考
`name`	string	元のファイル名。
`id`	string	下記のアップロードフローで取得するattachmentの`fileId`。
`_p3d_type`	string	常に`urn:primitive:obj:attachment`。

external linkと異なり、attachment値は先に存在している必要があるファイルを参照します。そのアップロードは、次に説明する独立した複数ステップの呼び出しシーケンスです。

メタデータへのファイルの添付

ファイルをattachment値として参照できるようにするには、3ステップのシーケンスが必要です。アップロードを初期化し、パーツをS3にアップロードし、finalizeします。その後、返されたファイルIDを、次のメタデータ書き込み時にattachment値のidフィールドとして使用します。

メソッド	パス	スコープ	目的
`POST`	`/v1/twin/{contextId}/object/attachments`	`write:asset`	添付ファイルのアップロードを初期化
`GET`	`/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}`	`write:asset`	期限切れのパートURLを再発行
`POST`	`/v1/twin/{contextId}/object/attachments/{fileId}/finalize`	`write:asset`	アップロードをfinalize
`GET`	`/v1/twin/{contextId}/object/attachments/{fileId}/download`	`read:asset`	署名付きダウンロードURLを取得
`DELETE`	`/v1/twin/{contextId}/object/attachments/{fileId}`	`write:asset`	添付ファイルを削除

contextIdは添付ファイルが属するtwin、site、またはdraftのIDです。ビジネスオブジェクトの検索で使用するIDと同じです。

アップロード自体は、API内の他の場所でも使われている汎用的なinitiate → パーツのアップロード → finalizeの仕組み（マルチパート、presigned S3 URL、期限切れ時に再発行可能）と同じです。この仕組みとパート番号付けの落とし穴については、共有マルチパートアップロードリファレンスを参照してください。このセクションでは、添付ファイルに固有の内容のみを扱います。

ステップ1：初期化

POST {api_url}/v1/twin/{contextId}/object/attachments
Authorization: Bearer {access_token}
Content-Type: application/json

{ "fileName": "prevu_logo.jpg", "fileSize": 84213, "mimeType": "image/jpeg" }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "parts": 1,
  "urls": [
    { "partNumber": 1, "url": "https://s3…/part-1?…" }
  ]
}

ステップ2：パーツのアップロード

各チャンクをpresigned urlにPUTし、パートごとに返されるETagを保持します。詳細は共有マルチパートアップロードリファレンスに記載のとおりです。

ステップ3：finalize

POST {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/finalize
Authorization: Bearer {access_token}
Content-Type: application/json

{ "parts": [ { "partNumber": 1, "etag": "\"a1b2c3d4e5f6\"" } ] }

{
  "fileId": "80559c9a-39ac-4e22-af81-7d7395f45673",
  "fileName": "prevu_logo.jpg",
  "size": 84213
}

ステップ4：メタデータでファイルを参照

finalizeレスポンスのfileIdを取得し、次のメタデータ書き込みでattachment値のidとして設定します。

PATCH {api_url}/v1/twin/{contextId}/object/{objectId}/metadata
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "metadata": {
    "Section name": {
      "landing image": {
        "name": "prevu_logo.jpg",
        "id": "80559c9a-39ac-4e22-af81-7d7395f45673",
        "_p3d_type": "urn:primitive:obj:attachment"
      }
    }
  }
}

メタデータの書き込みは、単一プロパティのパッチではなく、新規・更新・削除されたセクションとプロパティをすべて含む完全なメタデータオブジェクトを受け取ります。そのため、新しいattachment参照に加えて、保持したいすべてのセクションとプロパティを含めてください。

タグ付き値の読み取り

GET /v1/twin/{contextId}/object/{objectId}/metadataは、各プロパティを書き込まれたとおりに正確に返します。単純なstring/number/boolean、または_p3d_typeを保持したまま上記2つのタグ付きオブジェクトのいずれかです。タグ付き値を読み取るための別途の「解決」ステップはありません。attachmentのidを含め、オブジェクト自体がメタデータレスポンス内にインラインで返されます。

ファイルのバイトデータを取得するには、そのidを下記のダウンロードエンドポイントにfileIdとして渡します。

添付ファイルのダウンロードと削除

GET {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/download
Authorization: Bearer {access_token}

{ "url": "https://d111111abcdef8.cloudfront.net/…" }

返されるURLは署名付きのCloudFrontリンクで、有効期間は約4時間です。期限切れになった場合は、新しいURLを取得してください。

添付ファイルの実体を削除するには、次のようにします。

DELETE {api_url}/v1/twin/{contextId}/object/attachments/{fileId}
Authorization: Bearer {access_token}

添付ファイルの上限

添付ファイルのストレージは、RealityConnectの他のすべてのファイルと同じ組織単位のストレージ割り当てを使用します。添付ファイル専用の「割り当て」は存在しません。

質問	回答
単一の添付ファイルの最大サイズ	専用のサイズ上限は設けられていません。実質的な上限は、組織に残っているストレージの余裕です。
オブジェクトごとの添付ファイルの最大数	専用の件数上限は設けられていません。メタデータセクションには、任意の数のattachment型プロパティを含めることができます。
twinごと、または組織ごとの合計	添付ファイル専用のクォータはありません。各添付ファイルは通常のファイルとして保存され、組織全体のストレージ割り当てにカウントされます。これは、他のすべてのアップロードファイルが使用するのと同じカウンターです。使用量が組織に割り当てられたストレージを超えると、`StorageLimitExceeded`（エラーコードを参照）が返されます。この割り当てはプランごとに異なるため、ここで公開できる単一の数値はありません。組織の具体的な数値については、Prevu3Dのアカウントチームにご確認ください。
受け入れられるファイルタイプ	送信した`mimeType`はどのようなものでも受け入れられます。満たすべき許可リストはありません。
複数のオブジェクトに添付された同じファイル	アップロードごとに1回保存され、参照ごとには保存されません。同一のバイト列を2回アップロードする（initiate → finalizeの流れを2回別々に行う）と、2つの別々の保存済みファイルが作成されます。自動的な重複排除は行われません。同じ共有ドキュメントを複数のオブジェクトに、二重に保存せずに添付するには、一度だけアップロードし、再アップロードする代わりに、返された`id`を各オブジェクトのattachment値で再利用してください。

次のステップ

汎用的なinitiate/upload/finalizeの仕組みについては、共有マルチパートアップロードリファレンスを参照してください。
contextIdの解決方法については、ビジネスオブジェクトとノードの検索を参照してください。
各オペレーションの完全なリクエスト・レスポンススキーマについては、APIリファレンスを参照してください。