快速入门
在调用 RealityConnect API 之前，请确认你的网络能够访问它、了解访问控制的实施方式，并选择与你的集成相匹配的 OAuth 流程。每种流程都有各自的分步指南。
你需要组织管理员访问权限才能创建你的第一个 OAuth 应用程序。如果你还没有该权限，你的组织管理员可以为你授予访问权限，或者为你创建该应用程序。
API URL 和网络访问
Section titled “API URL 和网络访问”在创建 OAuth 凭据之前，请确认运行你的集成的计算机或服务器能够通过 HTTPS 访问 Prevu3D API。企业防火墙、代理和允许列表经常会阻止出站流量，从而导致连接超时或 DNS 错误。
你的集成必须能够访问：
- OAuth 和 API 发现： https://cloud-api.prevu3d.com
- 区域 RealityConnect API（你的组织使用某一个区域；你的流程指南会说明如何发现确切的 URL）：
如果你无法连接，请让你的 IT 团队允许对这些主机进行出站 HTTPS 访问。
API 访问通过三个层级实施。请求必须全部通过才能成功；如果任何一层拒绝访问，请求就会失败。
第 1 层 — OAuth 作用域。 在 OAuth 应用程序上配置。作用域定义了应用程序被允许执行哪些操作系列（例如 read:basic、read:hierarchy）。
第 2 层 — 内容访问。 在调用 API 的账户上配置。对于 Client Credentials，这是随你的 OAuth 应用程序一起创建的服务用户。对于 Native app 流程，则是已登录的用户。此层决定了调用方可以看到并操作哪些节点（组织、部门、站点等）。
第 3 层 — 角色 / 权限访问。 在同一账户上按节点配置。决定了调用方可以对该内容执行哪些操作（读取、编辑、管理等）。
每个流程指南都会讲解在哪里以及如何为你的用例配置这些层级。
选择 OAuth 流程
Section titled “选择 OAuth 流程”选择与你的集成运行方式相匹配的 OAuth 流程，然后遵循其专属指南：
| 流程 | 最适合 | 指南 |
|---|---|---|
| Client Credentials | 代表你的组织执行操作的服务器到服务器集成、脚本和后端服务 | Client Credentials 流程 |
| Native app | 用户通过浏览器登录的集成（桌面应用、CLI 工具、插件）。使用带 PKCE 的 Authorization Code + Native Application、本地主机重定向，且无客户端密钥。 | Native Application 流程 |
| Authorization Code + 自定义 HTTPS 重定向 | 在你自己的域名上带有回调 URL 的 Web 应用程序 | Authorization Code + 自定义重定向流程 |
不确定从哪里开始？对于测试 API 或构建服务器端自动化，Client Credentials 是最简单的途径。当 API 调用必须以特定的已登录用户身份运行时，请使用 Native app 流程。
API 参考中的某些操作被标记为实验性。
请以不同于稳定端点的方式对待实验性端点：
- 预期会发生变化。 路径、参数、有效负载、响应、错误或可用性可能会发生变化，不享有 API 其余部分同等的稳定性保证。
- 隔离使用。 在你的集成中，优先使用稳定操作。如果你依赖某个实验性功能，请将其置于一个小型适配器之后，以便在契约演变时能够快速调整。
- 保持更新。 关注发行说明，并在升级后重新查看 API 参考，以免因行为变化而措手不及。
下一步是什么？
Section titled “下一步是什么？”从以下选项中选择一种流程，并端到端地遵循其指南。
探索 API 参考以查看所有可用操作。