网络要求

使用 RealityConnect API 需要能够通过出站 HTTPS 访问下列主机。本页面涵盖完整的网络路径：哪些主机必须可访问、代理和 TLS 检测如何影响连接，以及如何区分网络问题和身份验证问题。

要求摘要

仅需出站流量,通过 HTTPS(端口 443)。 不需要任何入站端口、防火墙规则或 NAT。请参阅入站访问。
允许出站 HTTPS 访问下方列出的主机名。
标准企业前向代理可透明工作,包括需要身份验证的代理。请参阅前向代理。
TLS 检测代理会中断连接,除非集成运行环境信任其根证书。请参阅TLS 检测代理。

入站访问

使用 RealityConnect API 无需开放任何入站流量。您的集成始终由自身向 Prevu3D 发起出站连接;Prevu3D 绝不会反向向您的网络发起连接。没有需要注册的 Webhook、回调 URL 或监听器,也没有需要创建的入站防火墙规则。

出站访问

您的集成需要通过出站 HTTPS 访问三类主机:

OAuth 与 API 发现: https://cloud-api.prevu3d.com
您所在区域的 RealityConnect API 主机(以下几项中的恰好一项):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
文件传输: https://cdn.prevu3d.com (下载) 和 Amazon S3, *.amazonaws.com (预签名上传 URL)

如何确定自己所在的区域

您的组织仅被部署在一个区域中,因此您不需要允许全部四个主机名。与其猜测或询问支持团队,不如让您的集成在获取到令牌后调用发现端点(GET /oauth/api-info,在每份OAuth 流程指南中均有说明):响应中的 apiUrl 字段会告诉您组织实际使用的区域主机。只需允许该主机名即可,其余三个可以忽略。

前向代理

RealityConnect API 是一个标准的 HTTPS/JSON API。它对网络路径没有任何特殊要求,也不会采取任何(例如证书锁定)会妨碍其通过标准企业前向代理正常工作的措施。

您的集成是否实际使用您的代理,取决于其所构建的 HTTP 客户端库,而非 RealityConnect API 本身:

大多数 HTTP 客户端(curl、Python 的 requests、Node 的 undici/fetch、.NET 的 HttpClient 等)都会遵循标准的 HTTPS_PROXY / HTTP_PROXY 环境变量,或客户端配置中等效的代理设置。请查阅您所用客户端库的文档以确认这一点。
需要身份验证的代理(要求用户名和密码)同样在 HTTP 客户端层处理,使用的是客户端已支持的、用于其他任何 HTTPS 目的地的相同代理凭据机制。RealityConnect API 在这方面没有任何特殊要求。如果您的客户端已经能够通过经过身份验证的代理访问其他 HTTPS 服务,它就能以同样的方式访问 RealityConnect API。

TLS 检测代理

一些企业网络运行TLS 检测(SSL 解密)代理:它位于连接中间,向您的集成呈现自己的证书而非 Prevu3D 的证书,然后将流量重新加密后转发到真实目的地。这是 API 集成中普遍存在且已知的连接故障原因,RealityConnect API 也不例外。

表现形式: 集成的 HTTPS 调用不会收到正常响应,而是在 TLS 握手期间因证书验证错误而失败。具体措辞因所用 HTTP 客户端和操作系统而异,但常见形式包括 “unable to verify the first certificate”、“certificate verify failed”、“unknown certificate authority”,或者干脆是连接被重置、根本没有任何 HTTP 状态码(因为请求从未走到能收到响应的阶段)。

这意味着什么: 您的集成运行环境无法识别检测代理所呈现的证书,原因是该运行环境不信任该代理用于重新签名流量的内部证书颁发机构(CA)。

所需处理,以下两种方式之一:

将企业根 CA 添加到集成实际使用的信任库中。 这是最常见的解决方法,也是最容易被忽略的一步:许多运行环境(Java、Node、Python)会自带或加载各自的 CA 证书包,而不是使用操作系统的证书存储。将企业根 CA 安装到 Windows 证书存储中,并不会自动覆盖这些运行环境。请检查您所用的语言/运行环境是否需要单独配置(例如环境变量 NODE_EXTRA_CA_CERTS、JVM 参数 -Djavax.net.ssl.trustStore,或将证书添加到 Python requests/certifi 安装所使用的证书包中)。
如果您的代理支持按目标设置的绕过规则,可将 RealityConnect API 的主机名从 TLS 检测中排除。 这通常比逐个修复每个运行环境的信任库更简单。

具体选择哪种方式取决于代理厂商以及集成的运行环境。

诊断:是网络问题还是身份验证问题

按顺序执行以下四项检查。每一项都会隔离出不同的层级,让您能够准确定位问题所在,而不是针对网络问题去调试身份验证代码(或反之)。

1. DNS

确认主机名能够被正常解析:

nslookup api-ue1.prevu3d.com

(请根据实际情况替换为 cloud-api.prevu3d.com 或贵组织所在区域的主机。)如果此步骤失败或超时,问题出在 DNS 解析上。请先检查该机器的 DNS 配置,再继续下一步。

2. TLS 握手

确认能够与该主机建立安全连接,且与任何 Prevu3D 特定的请求无关:

curl -v https://cloud-api.prevu3d.com

留意 SSL certificate problem、unable to get local issuer certificate,或连接在收到任何 HTTP 响应之前就被重置的情况。这些都指向网络路径上的代理或防火墙问题(参见上方的 TLS 检测代理),而不是您集成代码中的问题。只要响应带有 HTTP 状态码,即使是 401 这样的错误,也说明 TLS 已经成功,问题出在更上层。

Windows 自带的 curl 使用 Windows 证书存储，因此即使使用自带 CA 证书包的运行环境(Node、Python、Java)在 TLS 检测代理后仍然失败，此项检查也可能通过。如果检查通过但集成仍报告证书错误，请参阅TLS 检测代理。

3. 令牌请求

确认能够获取 OAuth 访问令牌。这一步用于验证您的凭据和 OAuth 请求本身是否格式正确,与任何 RealityConnect API 调用无关:

curl -v -X POST https://cloud-api.prevu3d.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

此时返回 403 (密钥错误) 或 404 (客户端 ID 未知),说明是凭据问题,而非网络问题。能走到这一步,说明 DNS 和 TLS 均已成功。

4. 首次经过身份验证的调用

确认令牌确实能对 API 生效:

curl -H "Authorization: Bearer <access_token>" https://cloud-api.prevu3d.com/oauth/api-info

此处返回成功的 JSON 响应,即可确认整条路径(DNS、TLS 和身份验证)已端到端正常工作。若第 3 步已成功,而此步骤返回 401/403,则说明问题出在作用域(scope)或权限上,而非网络或凭据问题。(/oauth/api-info 需要 read:basic 作用域。)

下一步是什么？

快速入门:前提条件、安全模型,以及如何选择 OAuth 流程。