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

この 2 つのファミリーは互いに排他的です。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 を取得したら、このページでどのルートファミリーが利用できるようになるかを確認できます。