contextId가 허용하는 값

contextId는 모든 /v1/twin/{contextId}/... 및 /v1/reality-plan/{contextId}/... 라우트에서 필수 경로 매개변수입니다. 이 값은 다형적이어서(여러 종류의 서로 다른 id가 이를 통해 해석됩니다) 형식이 올바른 UUID라도 404가 반환될 수 있습니다. 이 페이지에서는 각 라우트 계열이 허용하는 값과, 그렇지 않을 때 정확히 어떤 오류가 발생하는지 설명합니다.

contextId가 식별하는 대상

라우트 계열	`contextId`가 허용하는 값
`/v1/twin/{contextId}/...` (space, assets, POI, zones, drafts, business objects, embed 세션)	twin의 id, 그 twin이 속한 site의 id, 또는 그 twin의 draft 중 하나의 id
`/v1/reality-plan/{contextId}/...` (space, layouts, bundles, model assets)	RealityPlan Project의 id, 또는 그 layout 중 하나의 id

두 계열은 상호 배타적입니다. twin 라우트는 twin 형태의 id만 해석하고, RealityPlan 라우트는 프로젝트 형태의 id만 해석합니다.

종류가 잘못된 유효한 id: 400이 아닌 404

다른 계열에 속하는, 형식이 올바른 id를 전달해도 유효성 검사에서 실패하지 않습니다. 실제 컨텍스트로 해석되지만, 단지 해당 라우트가 제공하는 컨텍스트가 아닐 뿐입니다. API는 그 라우트가 실제로 무엇을 제공하는지 알려주는 메시지와 함께 404 Not Found로 응답합니다.

{
  "statusCode": 404,
  "message": "This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts.",
  "error": "Not Found"
}

{
  "statusCode": 404,
  "message": "This route serves design projects. It accepts a design project id or the id of one of its layouts.",
  "error": "Not Found"
}

일부 라우트는 다른 종류를 제공하는 대응 라우트를 가리키는 힌트를 덧붙입니다. 예를 들어 GET /v1/twin/{contextId}/space는 다음을 덧붙입니다.

This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts. The composition of a design project or a layout is served by GET /v1/reality-plan/{contextId}/space.

그리고 GET /v1/reality-plan/{contextId}/space는 그 반대 방향의 내용을 덧붙입니다.

This route serves design projects. It accepts a design project id or the id of one of its layouts. The composition of a twin or a twin draft is served by GET /v1/twin/{contextId}/space.

모든 라우트에 대응 라우트가 있는 것은 아닙니다. assets, POI, zones, drafts, business object 검색은 twin 전용이며, model assets와 layouts는 RealityPlan Project 전용입니다. 이러한 라우트에는 힌트가 없고, 제공 대상을 나타내는 기본 메시지만 있습니다.

UUID가 아닌 contextId: 400

contextId가 애초에 UUID 형식이 아니면, API는 라우트 핸들러에 도달하기도 전에 이를 거부합니다.

{
  "statusCode": 400,
  "message": "Context ID must be a UUID",
  "error": "Bad Request"
}

이 검사는 표준 요청 유효성 검사보다 먼저 이루어지므로, 호출하는 라우트 계열과 관계없이 형식이 잘못된 contextId에 대해서는 이 메시지가 표시됩니다.

올바른 id 찾기

GET /oauth/api-info에서 시작해 GET /v1/nodes/{id}/browse로 계층을 따라 내려가면 twin, site, draft, project, layout의 id를 찾을 수 있습니다. 전체 안내는 Finding Your IDs를 참고하세요. id를 확보하면, 이 페이지에서 그 id로 어떤 라우트 계열을 사용할 수 있는지 확인할 수 있습니다.