Client Credentials 流程

对于代表你的组织执行操作而无需已登录用户的服务器到服务器集成，请使用 Client Credentials 流程。本指南将引导你完成从创建 OAuth 应用到首次 API 调用的设置。

如果你尚未了解前提条件、网络访问和安全模型，请先查看快速入门指南。

你将要做什么

创建 OAuth 应用 — 在 Prevu3D 中注册你的应用并获取凭据
配置服务用户访问权限 — 授予你的应用访问其所需数据的权限
获取访问令牌 — 进行身份验证并接收用于使用 API 的令牌
查找你的 API URL — 发现你组织的基础 URL（因区域而异）
进行首次调用 — 使用简单请求测试连接

步骤 1：创建你的 OAuth 应用

登录 Prevu3D 平台。
前往 Settings → OAuth。
点击以创建新应用。
选择 Client Credentials 作为 OAuth 流程。
分配你的应用所需的权限（这将配置第 1 层：OAuth 作用域）。你的组织管理员可以帮助你确定需要哪些作用域。
点击创建按钮。
复制并安全存储你的 Client ID 和 Client Secret。每次 API 请求都需要它们。

步骤 2：配置服务用户访问权限

创建 OAuth 应用时，会在你的组织中自动创建一个相应的服务用户。该服务用户在与 API 交互时代表你的应用，但它目前还没有任何访问权限。

此步骤涵盖安全模型的第 2 层和第 3 层：服务用户可以看到哪些节点（内容访问），以及它可以对它们做什么（角色 / 权限访问）。

前往 Settings → Users。
找到你的服务用户并点击编辑按钮（它的名称应与你创建的 OAuth 应用类似）。
授予服务用户对你的用例所需节点（组织、部门、站点等）的内容访问权限。
在这些节点上分配适当的角色 / 权限，以便服务用户可以执行它所需的操作（读取、编辑、管理等）。
确认更改。

步骤 3：获取你的访问令牌

要调用 API，你首先需要一个访问令牌。使用你的 Client ID 和 Client Secret 向令牌端点发送请求。

端点： POST https://cloud-api.prevu3d.com/oauth/token

标头：

Authorization: Basic <base64(client_id:client_secret)> — 将你的 Client ID 和 Secret 编码为 client_id:client_secret，然后对该字符串进行 Base64 编码
Content-Type: application/x-www-form-urlencoded

正文： grant_type=client_credentials

示例请求：

POST https://cloud-api.prevu3d.com/oauth/token HTTP/1.1
Host: cloud-api.prevu3d.com
Authorization: Basic eW91ci1jbGllbnQtaWQ6eW91ci1jbGllbnQtc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

示例响应：

{
  "hasError": false,
  "expiresIn": 3600,
  "accessToken": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..."
}

保存响应中的 accessToken。该令牌有效期为 1 小时；此后，你需要以相同方式请求新令牌。

步骤 4：获取你的 API 基础 URL

区域 RealityConnect API（你的组织使用某一个区域；本指南说明如何发现确切的 URL）：

调用下面的发现端点以获取你组织的 apiUrl。不要硬编码区域 URL。

端点： GET https://cloud-api.prevu3d.com/oauth/api-info

标头： Authorization: Bearer <your_access_token>

示例响应：

{
  "user": { "..." : "..." },
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "scopes": ["read:basic", "read:hierarchy"],
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

将 apiUrl 值用作你所有 API 调用的基础。另请注意 organization.id — 许多端点都需要它。

步骤 5：进行你的首次 API 调用

你现在拥有所需的一切：访问令牌和你的基础 URL。让我们进行一个简单的请求来检索你组织的部门：

GET {apiUrl}/v1/nodes/{organization_id}/browse
Authorization: Bearer <your_access_token>

使用真实值的示例：

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/nodes/217ebd23-ec54-4af0-a6d6-4a441a6d1966/browse HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...

包含部门列表的成功响应确认你的集成正在正确工作。

用 Python 试试

这是一个完成上述所有操作的完整脚本。将 client_id 和 client_secret 替换为你的凭据，然后运行它。

import requests
import base64
import json

client_id = "your-client-id"
client_secret = "your-client-secret"
base_url = "https://cloud-api.prevu3d.com"

# Step 1: Get a token
token_response = requests.post(
    f"{base_url}/oauth/token",
    data={"grant_type": "client_credentials"},
    headers={
        "Authorization": f'Basic {base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()}',
        "Content-Type": "application/x-www-form-urlencoded",
    },
)

token_response.raise_for_status()
access_token = token_response.json()["accessToken"]

# Step 2: Get your API URL and org ID
api_info = requests.get(
    f"{base_url}/oauth/api-info",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

api_url = api_info["apiUrl"]
organization_id = api_info["organization"]["id"]

# Step 3: Browse divisions
divisions = requests.get(
    f"{api_url}/v1/nodes/{organization_id}/browse",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

print("Divisions:", json.dumps(divisions, indent=2))

故障排除

如果你看到…	尝试这样做…
获取令牌时出现 401 Unauthorized	仔细检查你的 Client ID 和 Secret。确保你正确地对 `client_id:client_secret` 进行了 Base64 编码。
调用 API 时出现 403 Forbidden	请求必须通过全部三个安全层。检查（1）你的 OAuth 应用是否具有正确的作用域，（2）服务用户是否对目标节点具有内容访问权限，以及（3）它是否在该节点上具有拥有所需权限的角色。

有关连接、DNS 和 API URL 问题，请参阅快速入门 — API URL 和网络访问。

下一步是什么？

添加逻辑以在令牌过期前（1 小时后）刷新它。
探索 API 参考以查看所有可用操作。