简介

RealityConnect API 是让外部系统与 Prevu3D 生态系统交互的唯一公开接口。你可以用它读取和写入 RealityPlatform 中的内容、驱动 RealityTwin 工作区、管理你的组织、上传文件和数据集，以及更多功能。

---

API 的组织方式

在开始构建之前，有几个设计选择值得了解：

• 区域基础 URL。 API 在多个区域运行（美国东部、欧盟中部、亚洲北部、加拿大中部）。你的组织被配置在其中恰好一个区域内。请始终从发现端点获取你的基础 URL，而不要将其硬编码。快速入门指南展示了具体做法。
• 一切都限定在你的组织范围内。 令牌只能看到服务用户被授予访问权限的节点。跨组织调用是不可能的。
• 资源存在于内容层级结构中。 大多数操作针对由 UUID 标识的节点。节点构成一棵树（组织 → 部门 → 站点 → 文件夹 → 资产），你可以使用 /nodes/{id}/browse 端点进行导航。
• 三层访问控制。 OAuth 作用域、内容访问和按节点的角色都必须通过，请求才能成功。有关如何配置每一项，请参阅安全模型。
• 基于 HTTPS çš„ JSON。 每个端点都接受并返回 JSON，使用 bearer 令牌身份验证，并遵循标准 HTTP 状态码。

OAuth 身份验证

API 身份验证基于 **OAuth2 协议**。支持的流程：

OAuth 流程	说明	用例示例
Client Credentials	无需已登录用户的服务器到服务器访问。在你的组织中创建一个服务用户；你单独配置其权限。	脚本、自动化、后端集成、测试 API
Native app	用户通过浏览器登录并同意授予作用域。使用带 PKCE 的 Authorization Code + Native Application 以及 http://localhost 重定向。无客户端密钥。	桌面应用、CLI 工具、CAD 插件
Authorization Code + 自定义 HTTPS 重定向	在你自己的域名上带有回调 URL 的 Web 应用程序。使用带 PKCE 的 Authorization Code 以及完全匹配的 HTTPS 重定向 URI。	Web 应用、SaaS 集成

后续步骤

• **快速入门**：前提条件、网络访问、安全模型以及选择 OAuth 流程。
• **Client Credentials 流程**：从创建 OAuth 应用到首次 API 调用的服务器到服务器设置。
• **Native Application 流程**：使用 PKCE 和本地主机重定向的用户登录。
• **Authorization Code + 自定义重定向流程**：在你的域名上使用 PKCE 和自定义 HTTPS 回调的 Web 应用登录。
• **交互式 API 参考**：完整的端点目录，包含请求/响应架构和内置的请求构建器。
• **Data Bundle 工作流**：创建 Data Bundle、上传数据、启动处理、监控进度以及下载输入文件。