콘텐츠로 이동
Prevu3D

타입이 지정된 메타데이터 값과 첨부 파일

business object의 메타데이터 속성(GET/PATCH /v1/twin/{contextId}/object/{objectId}/metadata의 metadata)은 단순한 string, number, boolean에만 국한되지 않습니다. 속성 값은 외부 링크나 업로드된 파일 첨부를 나타내는 특수 필드 _p3d_type을 가진 태그된 객체일 수도 있습니다. 이 페이지에서는 이 값 유니언과 attachment 타입 뒤에 있는 업로드 흐름을 설명합니다.

메타데이터 값 유니언

섹션 제목: “메타데이터 값 유니언”

메타데이터 섹션 내의 각 속성은 다음 중 하나입니다.

값 종류형태
단순 string"A short text"
단순 number42
단순 booleantrue
External link{ "url": "...", "text": "...", "_p3d_type": "urn:primitive:obj:external-link" }
Attachment{ "name": "...", "id": "...", "_p3d_type": "urn:primitive:obj:attachment" }

_p3d_type은 판별자입니다. 이 리터럴 값을 통해 두 태그된 형태 중 어느 것을 보고 있는지 알 수 있습니다. 두 태그된 형태는 그 외에는 단순한 객체입니다. 읽기 위한 별도의 엔드포인트가 필요하지 않으며, 메타데이터가 반환되는 모든 곳에서 인라인으로 함께 반환됩니다.

{
  "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)”
필드타입참고
urlstring링크 대상.
textstring링크의 표시 텍스트.
_p3d_typestring항상 urn:primitive:obj:external-link.

external link는 그 자체로 완결됩니다; 업로드 없이 메타데이터 쓰기 시 객체를 직접 설정하면 됩니다.

Attachment (urn:primitive:obj:attachment)

섹션 제목: “Attachment (urn:primitive:obj:attachment)”
필드타입참고
namestring원본 파일명.
idstring아래 업로드 흐름에서 얻는 attachment의 fileId.
_p3d_typestring항상 urn:primitive:obj:attachment.

external link와 달리 attachment 값은 먼저 존재해야 하는 파일을 참조합니다. 이를 업로드하는 것은 별도의 여러 단계 호출 시퀀스이며, 다음에서 다룹니다.

메타데이터에 파일 첨부하기

섹션 제목: “메타데이터에 파일 첨부하기”

파일이 attachment 값으로 참조되도록 하려면 세 단계 시퀀스를 거쳐야 합니다: 업로드를 시작하고, 파트를 S3에 업로드하고, 완료한 다음, 반환된 파일 id를 다음 메타데이터 쓰기에서 attachment 값의 id 필드로 사용합니다.

메서드경로스코프목적
POST/v1/twin/{contextId}/object/attachmentswrite:asset첨부 파일 업로드 시작
GET/v1/twin/{contextId}/object/attachments/{fileId}/refresh/{startIndex}write:asset만료된 파트 URL 재발급
POST/v1/twin/{contextId}/object/attachments/{fileId}/finalizewrite:asset업로드 완료
GET/v1/twin/{contextId}/object/attachments/{fileId}/downloadread:asset서명된 다운로드 URL 가져오기
DELETE/v1/twin/{contextId}/object/attachments/{fileId}write:asset첨부 파일 제거

contextId는 첨부 파일이 속한 트윈, 사이트 또는 드래프트입니다; business object 검색에서 사용하는 것과 동일한 id입니다.

업로드 자체는 API의 다른 부분에서도 사용되는 것과 동일한 범용 initiate → 파트 업로드 → finalize 메커니즘(멀티파트, presigned S3 URL, 만료 시 재발급 가능)을 따릅니다. 이 메커니즘과 파트 번호 지정의 함정에 대해서는 공유 멀티파트 업로드 참조를 참조하세요. 이 섹션에서는 첨부 파일에만 특화된 내용을 다룹니다.

1단계: 시작

섹션 제목: “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단계: 파트 업로드

섹션 제목: “2단계: 파트 업로드”

각 청크를 해당 presigned url에 PUT으로 전송하고, 각 파트에서 반환된 ETag를 보관합니다. 자세한 내용은 공유 멀티파트 업로드 참조에 설명된 대로입니다.

3단계: 완료

섹션 제목: “3단계: 완료”
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단계: 메타데이터에서 파일 참조

섹션 제목: “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이 그대로 유지된 위 두 태그된 객체 중 하나입니다. 태그된 값을 읽기 위한 별도의 “해석” 단계는 없습니다; attachment의 id를 포함한 객체 자체가 메타데이터 응답에 인라인으로 반환됩니다.

파일의 바이트를 가져오려면 해당 id를 아래 다운로드 엔드포인트에 fileId로 전달하세요.

첨부 파일 다운로드 및 제거

섹션 제목: “첨부 파일 다운로드 및 제거”
GET {api_url}/v1/twin/{contextId}/object/attachments/{fileId}/download
Authorization: Bearer {access_token}
{ "url": "https://d111111abcdef8.cloudfront.net/…" }

반환된 URL은 약 4시간 동안 유효한 서명된 CloudFront 링크입니다. 만료되면 새로 가져오세요.

첨부 파일의 실제 파일을 제거하려면:

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

첨부 파일 제한

섹션 제목: “첨부 파일 제한”

첨부 파일 저장소는 RealityConnect의 다른 모든 파일과 동일한 조직별 스토리지 할당량을 사용합니다. 별도의 “첨부 파일 할당량”은 존재하지 않습니다.

질문답변
단일 첨부 파일의 최대 크기전용 크기 제한은 적용되지 않습니다. 실질적인 상한선은 조직에 남아 있는 스토리지 여유 공간입니다.
객체당 최대 첨부 파일 수전용 개수 제한은 적용되지 않습니다. 메타데이터 섹션에는 attachment 타입 속성을 원하는 만큼 포함할 수 있습니다.
트윈 또는 조직당 총량별도의 첨부 파일 할당량은 없습니다. 각 첨부 파일은 일반 파일로 저장되며 조직의 전체 스토리지 할당량에 포함됩니다. 이는 다른 모든 업로드된 파일이 사용하는 것과 동일한 카운터입니다. 사용량이 조직에 할당된 스토리지를 초과하면 StorageLimitExceeded(오류 코드 참조)가 반환됩니다. 이 할당량은 요금제에 따라 다르므로 여기서 공개할 단일 수치는 없습니다. 조직의 정확한 수치는 Prevu3D 계정팀에 문의하세요.
허용되는 파일 형식전송하는 모든 mimeType이 허용됩니다. 충족해야 할 허용 목록은 없습니다.
여러 객체에 첨부된 동일한 파일참조마다가 아니라 업로드마다 한 번 저장됩니다. 동일한 바이트를 두 번 업로드하면(별도의 initiate → finalize 시퀀스 두 번) 별도로 저장된 두 개의 파일이 생성됩니다. 자동 중복 제거는 이루어지지 않습니다. 동일한 공유 문서를 여러 객체에 두 번 저장하지 않고 첨부하려면, 한 번만 업로드하고 다시 업로드하는 대신 반환된 id를 각 객체의 attachment 값에서 재사용하세요.

다음은?

섹션 제목: “다음은?”