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，或其某个 draft 的 id
/v1/reality-plan/{contextId}/...（space、layouts、bundles、model assets）	RealityPlan Project 的 id，或其某个 layout 的 id

这两个系列互斥：twin 路由只解析 twin 形态的 id，RealityPlan 路由只解析项目形态的 id。

类型错误的有效 id：404 而非 400

传入一个格式正确、但属于另一个系列的 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；这些路由不会附加提示，只返回说明其服务对象的基础消息。

注意

类型错误时的响应始终是 404，绝不是 400：id 本身是有效的，只是无法在该路由上被寻址。请将其视为其他任何”在此路由上未找到”的情况一样处理。

不是 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 后，本页可以帮助你确认它能解锁哪些路由系列。