1187 lines
28 KiB
Markdown
1187 lines
28 KiB
Markdown
# RevitHttpControl API 接口文档
|
||
|
||
## 概述
|
||
|
||
RevitHttpControl 是一个 Revit 2017 远程控制插件，提供 HTTP API 接口来实现 Revit 模型的远程操作。
|
||
|
||
**基本信息：**
|
||
- 服务器地址：`http://localhost:9000`
|
||
- 数据格式：JSON
|
||
- 字符编码：UTF-8
|
||
|
||
## 统一响应格式
|
||
|
||
所有接口都遵循统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"success": true, // 操作是否成功
|
||
"code": 200, // 状态码
|
||
"message": "操作成功", // 状态消息
|
||
"data": {}, // 响应数据
|
||
"timestamp": "2025-01-27T10:30:00Z" // 时间戳（自动生成）
|
||
}
|
||
```
|
||
|
||
## 接口列表
|
||
|
||
### 1. 服务器状态检查 ✅
|
||
|
||
**接口地址：** `GET /api/health`
|
||
|
||
**功能描述：** 检查 Revit 服务器状态和当前文档信息
|
||
|
||
**实现状态：** ✅ 已完成并测试通过
|
||
|
||
**请求示例：**
|
||
```
|
||
GET /api/health
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
// 有文档打开时
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "服务正常",
|
||
"data": {
|
||
"serverStatus": "running",
|
||
"revitVersion": "2017",
|
||
"currentDocument": {
|
||
"isOpen": true,
|
||
"fileName": "MyProject.rvt",
|
||
"filePath": "C:\\Projects\\MyProject.rvt"
|
||
}
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00.000Z"
|
||
}
|
||
|
||
// 无文档打开时
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "服务正常",
|
||
"data": {
|
||
"serverStatus": "running",
|
||
"revitVersion": "2017",
|
||
"currentDocument": {
|
||
"isOpen": false,
|
||
"fileName": null,
|
||
"filePath": null
|
||
}
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00.000Z"
|
||
}
|
||
```
|
||
|
||
**状态说明：**
|
||
- `serverStatus`: 服务器状态（running/stopped）
|
||
- `currentDocument.isOpen`: 是否有打开的文档
|
||
- `fileName`: 当前文档名称（无文档时为 null）
|
||
- `filePath`: 当前文档路径（无文档时为 null）
|
||
|
||
---
|
||
|
||
### 2. 打开文件（同步） ✅
|
||
|
||
**接口地址：** `POST /api/open`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 同步打开 Revit 文件
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"filePath": "string", // 文件路径（必填）
|
||
"detached": "boolean" // 是否分离模式（可选，默认false）
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `filePath`: Revit 文件的完整路径，支持 .rvt 格式
|
||
- `detached`:
|
||
- `true`: 分离模式（保留工作集）
|
||
- `false`: 正常模式（丢弃工作集）
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"filePath": "C:\\Projects\\MyProject.rvt",
|
||
"detached": false
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
// 成功
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "文件打开成功",
|
||
"data": {
|
||
"result": "文件打开成功",
|
||
"fileName": "MyProject.rvt",
|
||
"filePath": "C:\\Projects\\MyProject.rvt"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
|
||
// 失败
|
||
{
|
||
"success": false,
|
||
"code": 404,
|
||
"message": "文件不存在或路径无效",
|
||
"data": {
|
||
"error": "FILE_NOT_FOUND"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 打开文件（异步） ✅
|
||
|
||
**接口地址：** `POST /api/open/async`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 异步打开 Revit 文件，返回任务ID
|
||
|
||
**请求参数：** 与同步接口相同
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 202,
|
||
"message": "文件打开任务已创建",
|
||
"data": {
|
||
"taskId": "123e4567-e89b-12d3-a456-426614174000",
|
||
"statusUrl": "/api/task/123e4567-e89b-12d3-a456-426614174000"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取统计信息（同步） ✅
|
||
|
||
**接口地址：** `POST /api/stats/sync`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 同步获取当前打开模型的元素统计信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"type": "integer" // 统计类型（必填）
|
||
}
|
||
```
|
||
|
||
**统计类型说明：**
|
||
| 值 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| 0 | Wall | 墙体 |
|
||
| 1 | Door | 门 |
|
||
| 2 | Window | 窗 |
|
||
| 3 | Floor | 地板 |
|
||
| 4 | Ceiling | 天花板 |
|
||
| 5 | Roof | 屋顶 |
|
||
| 6 | Column | 柱子 |
|
||
| 7 | Beam | 梁 |
|
||
| 8 | Furniture | 家具 |
|
||
| 9 | Room | 房间 |
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"type": 0 // 统计墙体数量
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
// 成功
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "统计数据获取成功",
|
||
"data": {
|
||
"elementType": "Wall",
|
||
"count": 25,
|
||
"details": {
|
||
"typeName": "墙体",
|
||
"typeId": -2000011
|
||
}
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
|
||
// 失败 - 无文档打开
|
||
{
|
||
"success": false,
|
||
"code": 409,
|
||
"message": "没有打开的文档",
|
||
"data": {
|
||
"error": "NO_DOCUMENT_OPEN"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取统计信息（异步） ✅
|
||
|
||
**接口地址：** `POST /api/stats/async`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 异步获取当前打开模型的元素统计信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"type": "integer" // 统计类型（必填）
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"type": 0 // 统计墙体数量
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 202,
|
||
"message": "统计任务已创建",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc",
|
||
"statusUrl": "/api/task/12345678-1234-1234-1234-123456789abc"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 查询任务状态 ✅
|
||
|
||
**接口地址：** `GET /api/task/{taskId}`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 查询异步任务的执行状态和结果
|
||
|
||
**路径参数：**
|
||
- `taskId`: 任务ID（从异步统计接口返回）
|
||
|
||
**请求示例：**
|
||
```
|
||
GET /api/task/12345678-1234-1234-1234-123456789abc
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
// 进行中
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取任务状态成功",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc",
|
||
"status": "Running",
|
||
"createdAt": "2025-01-27T10:30:00Z",
|
||
"completedAt": null,
|
||
"result": null,
|
||
"errorMessage": null
|
||
},
|
||
"timestamp": "2025-01-27T10:30:15Z"
|
||
}
|
||
|
||
// 完成
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取任务状态成功",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc",
|
||
"status": "Completed",
|
||
"createdAt": "2025-01-27T10:30:00Z",
|
||
"completedAt": "2025-01-27T10:30:45Z",
|
||
"result": {
|
||
"elementType": "Wall",
|
||
"count": 25,
|
||
"details": {
|
||
"typeName": "墙体",
|
||
"typeId": -2000011
|
||
}
|
||
},
|
||
"errorMessage": null
|
||
},
|
||
"timestamp": "2025-01-27T10:30:45Z"
|
||
}
|
||
|
||
// 失败
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取任务状态成功",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc",
|
||
"status": "Failed",
|
||
"createdAt": "2025-01-27T10:30:00Z",
|
||
"completedAt": "2025-01-27T10:30:30Z",
|
||
"result": null,
|
||
"errorMessage": "没有打开的文档"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:30Z"
|
||
}
|
||
|
||
// 任务不存在
|
||
{
|
||
"success": false,
|
||
"code": 404,
|
||
"message": "任务不存在",
|
||
"data": {
|
||
"error": "TASK_NOT_FOUND"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:30Z"
|
||
}
|
||
```
|
||
|
||
**任务状态说明：**
|
||
- `Pending`: 等待中
|
||
- `Running`: 运行中
|
||
- `Completed`: 已完成
|
||
- `Failed`: 失败
|
||
- `Cancelled`: 已取消
|
||
|
||
---
|
||
|
||
### 7. 旧版任务状态查询（兼容） ✅
|
||
|
||
**接口地址：** `GET /api/status/{taskId}`
|
||
|
||
**实现状态：** ✅ 已完成（向后兼容）
|
||
|
||
**功能描述：** 兼容旧版的简化任务状态查询
|
||
|
||
**响应示例：**
|
||
```json
|
||
// 完成时
|
||
{ "result": 25 }
|
||
|
||
// 处理中
|
||
{ "status": "processing" }
|
||
|
||
// 失败时
|
||
{ "error": "没有打开的文档" }
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 取消任务 ✅
|
||
|
||
**接口地址：** `DELETE /api/task/{taskId}`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 取消正在进行的任务
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "任务已取消",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9. 任务管理器状态 ✅
|
||
|
||
**接口地址：** `GET /api/tasks/status`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 获取任务管理器整体状态
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取任务管理器状态成功",
|
||
"data": {
|
||
"totalTasks": 15,
|
||
"pendingTasks": 2,
|
||
"runningTasks": 1,
|
||
"completedTasks": 10,
|
||
"failedTasks": 1,
|
||
"cancelledTasks": 1
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 10. 薄壳优化 - 获取优化模式配置 ✅
|
||
|
||
**接口地址：** `GET /api/shell/modes`
|
||
|
||
**功能描述：** 获取所有薄壳优化模式的配置说明
|
||
|
||
**请求示例：**
|
||
```
|
||
GET /api/shell/modes
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "优化模式配置获取成功",
|
||
"data": [
|
||
{
|
||
"mode": "Conservative",
|
||
"name": "保守模式",
|
||
"description": "仅删除装饰元素，减少约30%文件大小",
|
||
"estimatedReduction": "30%",
|
||
"deletedElements": ["配景", "植物", "装饰元素"]
|
||
},
|
||
{
|
||
"mode": "Standard",
|
||
"name": "标准模式",
|
||
"description": "删除家具和部分内墙，减少约65%文件大小",
|
||
"estimatedReduction": "65%",
|
||
"deletedElements": ["家具", "橱柜", "配景", "植物", "部分灯具"]
|
||
},
|
||
{
|
||
"mode": "Aggressive",
|
||
"name": "激进模式",
|
||
"description": "删除所有内部元素，减少约80%文件大小",
|
||
"estimatedReduction": "80%",
|
||
"deletedElements": ["家具", "设备", "天花板", "配景", "植物", "灯具", "内部装饰"]
|
||
}
|
||
],
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 11. 薄壳优化 - 分析模型薄壳优化方案 ✅
|
||
|
||
**接口地址：** `POST /api/shell/analyze`
|
||
|
||
**功能描述：** 分析当前模型在指定优化模式下的薄壳优化效果（仅分析，不做实际删除）
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mode": "Standard" // 优化模式，必填，取值：Conservative/Standard/Aggressive
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"mode": "Standard"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "薄壳分析完成",
|
||
"data": {
|
||
"analysis": {
|
||
"totalElements": 1250,
|
||
"keepElements": 875,
|
||
"removeElements": 375,
|
||
"estimatedReduction": "65%"
|
||
},
|
||
"categories": [
|
||
{
|
||
"name": "墙",
|
||
"total": 120,
|
||
"keep": 95,
|
||
"remove": 25,
|
||
"keepPercentage": "79%"
|
||
},
|
||
{
|
||
"name": "家具",
|
||
"total": 180,
|
||
"keep": 0,
|
||
"remove": 180,
|
||
"keepPercentage": "0%"
|
||
}
|
||
]
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 12. 薄壳优化 - 执行薄壳优化（异步） ✅
|
||
|
||
**接口地址：** `POST /api/shell/execute`
|
||
|
||
**功能描述：** 按指定模式异步执行薄壳优化，返回任务ID，适合大型模型
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mode": "Standard", // 优化模式，必填
|
||
"backupOriginal": true // 是否备份原文件，建议true
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"mode": "Standard",
|
||
"backupOriginal": true
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 202,
|
||
"message": "薄壳优化任务已创建",
|
||
"data": {
|
||
"taskId": "123e4567-e89b-12d3-a456-426614174000",
|
||
"statusUrl": "/api/task/123e4567-e89b-12d3-a456-426614174000"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
**任务进度查询：**
|
||
```
|
||
GET /api/task/{taskId}
|
||
```
|
||
|
||
**完成后响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "任务查询成功",
|
||
"data": {
|
||
"taskId": "123e4567-e89b-12d3-a456-426614174000",
|
||
"status": "Completed",
|
||
"result": {
|
||
"removedCount": 342,
|
||
"originalSize": "156.8 MB",
|
||
"optimizedSize": "54.9 MB",
|
||
"reduction": "65.0%",
|
||
"backupPath": "D:\\Projects\\Building_backup_20241230_143052.rvt",
|
||
"processingTimeSeconds": 45.2
|
||
}
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 13. 薄壳优化 - 执行薄壳优化（同步） ✅
|
||
|
||
**接口地址：** `POST /api/shell/execute/sync`
|
||
|
||
**功能描述：** 按指定模式同步执行薄壳优化，适合小型模型或测试
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mode": "Conservative", // 优化模式，必填
|
||
"backupOriginal": true // 是否备份原文件，建议true
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"mode": "Conservative",
|
||
"backupOriginal": true
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "薄壳优化执行完成",
|
||
"data": {
|
||
"removedCount": 120,
|
||
"originalSize": "156.8 MB",
|
||
"optimizedSize": "109.8 MB",
|
||
"reduction": "30.0%",
|
||
"backupPath": "D:\\Projects\\Building_backup_20241230_143052.rvt",
|
||
"processingTimeSeconds": 12.5
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 14. 获取支持的导出格式 ✅
|
||
|
||
**接口地址：** `GET /api/export/formats`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 获取系统支持的所有导出格式列表
|
||
|
||
**请求示例：**
|
||
```
|
||
GET /api/export/formats
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"Success": true,
|
||
"Code": 200,
|
||
"Message": "获取支持的导出格式成功",
|
||
"Data": [
|
||
{
|
||
"Name": "IFC",
|
||
"Description": "Industry Foundation Classes - 建筑信息模型交换格式",
|
||
"FileExtension": ".ifc",
|
||
"SupportedVersions": ["IFC2x3", "IFC4", "IFC4RV", "IFC4DTV"],
|
||
"IsAsync": true
|
||
}
|
||
],
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 15. 同步导出IFC格式 ✅
|
||
|
||
**接口地址：** `POST /api/export/ifc`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 同步导出当前打开的Revit模型为IFC格式，适合小文件或快速导出
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"IfcVersion": "IFC4", // IFC版本，必填
|
||
"OutputPath": "C:\\Export\\model.ifc", // 输出路径，可选
|
||
"ExportRange": "VisibleElements", // 导出范围，可选
|
||
"IncludeSpaceBoundaries": true, // 包含空间边界，可选
|
||
"SplitWallsAndColumns": false, // 分离墙和柱，可选
|
||
"Include2DElements": false, // 包含2D元素，可选
|
||
"ExportBaseQuantities": true, // 导出基本数量，可选
|
||
"ExportSchedulesAsTables": false, // 导出明细表，可选
|
||
"ExportUserDefinedPsets": true, // 导出用户属性集，可选
|
||
"ExportInternalRevitPropertySets": false, // 导出内部属性集，可选
|
||
"ExportIFCCommonPropertySets": true, // 导出IFC通用属性集，可选
|
||
"ExportPartsAsBuildingElements": false, // 导出部件为建筑元素，可选
|
||
"ExportBoundingBox": false, // 导出边界框，可选
|
||
"ExportSolidModelRep": false, // 导出实体模型，可选
|
||
"ExportLinkedFiles": false // 导出链接文件，可选
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `IfcVersion`: IFC版本，支持 "IFC2x3", "IFC4", "IFC4RV", "IFC4DTV"
|
||
- `OutputPath`: 输出文件路径，不提供则自动生成到当前文档目录
|
||
- `ExportRange`: 导出范围
|
||
- `"AllElements"`: 所有元素
|
||
- `"VisibleElements"`: 可见元素（默认）
|
||
- `"SelectedElements"`: 选中元素
|
||
- 其他参数均为可选的导出选项，默认值为false
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"IfcVersion": "IFC4",
|
||
"OutputPath": "C:\\Export\\MyProject.ifc",
|
||
"ExportRange": "VisibleElements",
|
||
"IncludeSpaceBoundaries": true,
|
||
"ExportBaseQuantities": true,
|
||
"ExportUserDefinedPsets": true,
|
||
"ExportIFCCommonPropertySets": true
|
||
}
|
||
```
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"Success": true,
|
||
"Code": 200,
|
||
"Message": "IFC导出成功",
|
||
"Data": {
|
||
"FilePath": "C:\\Export\\MyProject.ifc",
|
||
"FileSize": 1024000,
|
||
"ExportTime": "2024-01-01T10:30:00",
|
||
"Statistics": {
|
||
"TotalElements": 1500,
|
||
"ExportedElements": 1450,
|
||
"SkippedElements": 50
|
||
}
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
**错误响应示例：**
|
||
```json
|
||
// 无文档打开
|
||
{
|
||
"Success": false,
|
||
"Code": 409,
|
||
"Message": "没有打开的文档",
|
||
"Data": {
|
||
"error": "NO_DOCUMENT_OPEN"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
|
||
// 路径无效
|
||
{
|
||
"Success": false,
|
||
"Code": 400,
|
||
"Message": "导出路径无效",
|
||
"Data": {
|
||
"error": "EXPORT_PATH_INVALID"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 16. 异步导出IFC格式 ✅
|
||
|
||
**接口地址：** `POST /api/export/ifc/async`
|
||
|
||
**实现状态：** ✅ 已完成
|
||
|
||
**功能描述：** 异步导出当前打开的Revit模型为IFC格式，适合大文件或长时间导出
|
||
|
||
**请求参数：** 与同步接口相同
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"IfcVersion": "IFC4",
|
||
"OutputPath": "C:\\Export\\LargeProject.ifc",
|
||
"ExportRange": "AllElements",
|
||
"IncludeSpaceBoundaries": true,
|
||
"ExportBaseQuantities": true
|
||
}
|
||
```
|
||
|
||
**立即响应：**
|
||
```json
|
||
{
|
||
"Success": true,
|
||
"Code": 202,
|
||
"Message": "IFC导出任务已创建",
|
||
"Data": {
|
||
"TaskId": "12345678-1234-1234-1234-123456789abc",
|
||
"StatusUrl": "/api/task/12345678-1234-1234-1234-123456789abc",
|
||
"EstimatedCompletionTime": "2024-01-01T10:35:00"
|
||
},
|
||
"timestamp": "2025-01-27T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
**任务状态查询：**
|
||
```
|
||
GET /api/task/12345678-1234-1234-1234-123456789abc
|
||
```
|
||
|
||
**完成后响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "获取任务状态成功",
|
||
"data": {
|
||
"taskId": "12345678-1234-1234-1234-123456789abc",
|
||
"status": "Completed",
|
||
"createdAt": "2025-01-27T10:30:00Z",
|
||
"completedAt": "2025-01-27T10:35:30Z",
|
||
"result": {
|
||
"FilePath": "C:\\Export\\LargeProject.ifc",
|
||
"FileSize": 5120000,
|
||
"ExportTime": "2024-01-01T10:35:30",
|
||
"Statistics": {
|
||
"TotalElements": 8500,
|
||
"ExportedElements": 8200,
|
||
"SkippedElements": 300
|
||
}
|
||
},
|
||
"errorMessage": null
|
||
},
|
||
"timestamp": "2025-01-27T10:35:30Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### IFC导出注意事项
|
||
|
||
1. **必须有打开的Revit文档**，否则接口会返回409错误。
|
||
2. **IFC版本选择**：
|
||
- `IFC2x3`: 兼容性最好，适合旧版软件
|
||
- `IFC4`: 新标准，功能更丰富（推荐）
|
||
- `IFC4RV`: Revit视图专用版本
|
||
- `IFC4DTV`: 设计传输视图版本
|
||
3. **导出路径**：
|
||
- 不提供OutputPath时，自动生成到当前文档同目录
|
||
- 路径必须是绝对路径，且目录必须存在
|
||
- 文件扩展名必须是.ifc
|
||
4. **导出范围建议**：
|
||
- 小模型：使用同步接口，选择VisibleElements
|
||
- 大模型：使用异步接口，选择AllElements
|
||
5. **性能优化**：
|
||
- 大文件建议使用异步接口避免超时
|
||
- 可通过ExportRange控制导出元素数量
|
||
6. **Revit 2017兼容性**：
|
||
- 某些高级选项可能不支持（如SplitWallsAndColumns）
|
||
- 系统会自动忽略不支持的选项
|
||
|
||
---
|
||
|
||
#### 薄壳优化注意事项
|
||
|
||
1. **必须有打开的Revit文档**，否则接口会返回400错误。
|
||
2. **建议始终设置 `backupOriginal: true`**，系统会自动创建带时间戳的备份文件。
|
||
3. **模式选择建议**：首次使用建议选择保守模式，避免误删。
|
||
4. **大型模型建议使用异步接口**，小型模型可用同步接口。
|
||
5. **接口参数区分大小写**，mode参数必须为Conservative/Standard/Aggressive。
|
||
6. **所有薄壳接口均有详细错误码和说明，见统一响应格式和错误码表。
|
||
|
||
---
|
||
|
||
## 错误码定义
|
||
|
||
| 错误码 | 描述 | 解决方案 |
|
||
|---|---|---|
|
||
| `FILE_NOT_FOUND` | 文件不存在 | 检查文件路径是否正确 |
|
||
| `FILE_ACCESS_DENIED` | 文件访问被拒绝 | 检查文件权限或文件是否被占用 |
|
||
| `NO_DOCUMENT_OPEN` | 没有打开的文档 | 先使用 `/api/open` 打开文件 |
|
||
| `INVALID_ELEMENT_TYPE` | 无效的元素类型 | 检查统计类型参数是否在 0-9 范围内 |
|
||
| `REVIT_NOT_READY` | Revit 未就绪 | 等待 Revit 完全启动后重试 |
|
||
| `OPERATION_TIMEOUT` | 操作超时 | 重试操作或增加超时时间 |
|
||
| `PROCESSING_ERROR` | 处理过程中发生错误 | 查看详细错误信息并重试 |
|
||
| `INTERNAL_ERROR` | 内部服务器错误 | 联系技术支持 |
|
||
| `EXPORT_FAILED` | 导出失败 | 检查模型和导出参数 |
|
||
| `EXPORT_PATH_INVALID` | 导出路径无效 | 检查路径格式和权限 |
|
||
| `EXPORT_PATH_ACCESS_DENIED` | 导出路径访问被拒绝 | 检查目录权限 |
|
||
| `EXPORT_NO_ELEMENTS` | 没有可导出的元素 | 检查导出范围设置 |
|
||
| `EXPORT_UNSUPPORTED_FORMAT` | 不支持的导出格式 | 使用支持的格式 |
|
||
| `EXPORT_CONFIGURATION_ERROR` | 导出配置错误 | 检查导出参数设置 |
|
||
| `IFC_EXPORT_FAILED` | IFC导出失败 | 检查IFC版本和参数 |
|
||
| `IFC_VERSION_NOT_SUPPORTED` | IFC版本不支持 | 使用支持的IFC版本 |
|
||
| `EXPORT_CANCELLED_BY_USER` | 用户取消导出 | 重新发起导出请求 |
|
||
| `EXPORT_DISK_SPACE_INSUFFICIENT` | 磁盘空间不足 | 清理磁盘空间 |
|
||
|
||
---
|
||
|
||
## 使用流程
|
||
|
||
### 推荐使用流程：
|
||
|
||
1. **检查服务器状态**
|
||
2. **打开文件**
|
||
3. **获取统计信息**
|
||
|
||
### 前端使用示例
|
||
|
||
```javascript
|
||
class RevitApi {
|
||
constructor() {
|
||
this.baseUrl = 'http://localhost:9000/api';
|
||
}
|
||
|
||
// 检查服务器状态
|
||
async checkHealth() {
|
||
try {
|
||
const response = await fetch(`${this.baseUrl}/health`);
|
||
const result = await response.json();
|
||
return result;
|
||
} catch (error) {
|
||
return {
|
||
success: false,
|
||
code: 500,
|
||
message: '服务器连接失败',
|
||
data: { error: 'CONNECTION_ERROR' }
|
||
};
|
||
}
|
||
}
|
||
|
||
// 打开文件
|
||
async openFile(filePath, detached = false) {
|
||
const response = await fetch(`${this.baseUrl}/open`, {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify({filePath, detached})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 获取统计信息（同步）
|
||
async getStatsSync(type) {
|
||
const response = await fetch(`${this.baseUrl}/stats/sync`, {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify({type})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 获取统计信息（异步）
|
||
async getStatsAsync(type) {
|
||
const response = await fetch(`${this.baseUrl}/stats/async`, {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify({type})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 查询任务状态
|
||
async getTaskStatus(taskId) {
|
||
const response = await fetch(`${this.baseUrl}/task/${taskId}`);
|
||
return await response.json();
|
||
}
|
||
|
||
// 获取支持的导出格式
|
||
async getSupportedFormats() {
|
||
const response = await fetch(`${this.baseUrl}/export/formats`);
|
||
return await response.json();
|
||
}
|
||
|
||
// 同步导出IFC
|
||
async exportIfcSync(exportRequest) {
|
||
const response = await fetch(`${this.baseUrl}/export/ifc`, {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify(exportRequest)
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 异步导出IFC
|
||
async exportIfcAsync(exportRequest) {
|
||
const response = await fetch(`${this.baseUrl}/export/ifc/async`, {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify(exportRequest)
|
||
});
|
||
return await response.json();
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
const api = new RevitApi();
|
||
|
||
async function example() {
|
||
// 1. 检查服务器状态
|
||
const health = await api.checkHealth();
|
||
if (!health.success) {
|
||
console.error('服务器未就绪:', health.message);
|
||
return;
|
||
}
|
||
|
||
// 2. 打开文件
|
||
const openResult = await api.openFile('C:\\Projects\\MyProject.rvt');
|
||
if (!openResult.success) {
|
||
console.error('文件打开失败:', openResult.data.errorDescription);
|
||
return;
|
||
}
|
||
|
||
console.log('文件打开成功:', openResult.data.fileName);
|
||
|
||
// 3. 获取墙体统计（同步）
|
||
const statsResult = await api.getStatsSync(0);
|
||
if (statsResult.success) {
|
||
console.log('墙体数量:', statsResult.data.count);
|
||
} else {
|
||
console.error('统计失败:', statsResult.data.errorDescription);
|
||
}
|
||
|
||
// 4. 导出IFC文件（同步）
|
||
const exportRequest = {
|
||
IfcVersion: "IFC4",
|
||
OutputPath: "C:\\Export\\MyProject.ifc",
|
||
ExportRange: "VisibleElements",
|
||
IncludeSpaceBoundaries: true,
|
||
ExportBaseQuantities: true
|
||
};
|
||
|
||
const exportResult = await api.exportIfcSync(exportRequest);
|
||
if (exportResult.Success) {
|
||
console.log('IFC导出成功:', exportResult.Data.FilePath);
|
||
console.log('文件大小:', exportResult.Data.FileSize, 'bytes');
|
||
console.log('导出元素数:', exportResult.Data.Statistics.ExportedElements);
|
||
} else {
|
||
console.error('导出失败:', exportResult.Message);
|
||
}
|
||
}
|
||
|
||
// 异步导出示例
|
||
async function exportLargeModel() {
|
||
const api = new RevitApi();
|
||
|
||
// 检查服务器状态
|
||
const health = await api.checkHealth();
|
||
if (!health.success) {
|
||
console.error('服务器未就绪');
|
||
return;
|
||
}
|
||
|
||
// 异步导出大模型
|
||
const exportRequest = {
|
||
IfcVersion: "IFC4",
|
||
OutputPath: "C:\\Export\\LargeProject.ifc",
|
||
ExportRange: "AllElements",
|
||
IncludeSpaceBoundaries: true,
|
||
ExportBaseQuantities: true,
|
||
ExportUserDefinedPsets: true
|
||
};
|
||
|
||
const asyncResult = await api.exportIfcAsync(exportRequest);
|
||
if (!asyncResult.Success) {
|
||
console.error('导出任务创建失败:', asyncResult.Message);
|
||
return;
|
||
}
|
||
|
||
console.log('导出任务已创建:', asyncResult.Data.TaskId);
|
||
|
||
// 轮询任务状态
|
||
const taskId = asyncResult.Data.TaskId;
|
||
let completed = false;
|
||
|
||
while (!completed) {
|
||
await new Promise(resolve => setTimeout(resolve, 2000)); // 等待2秒
|
||
|
||
const status = await api.getTaskStatus(taskId);
|
||
if (status.success) {
|
||
console.log('任务状态:', status.data.status);
|
||
|
||
if (status.data.status === 'Completed') {
|
||
console.log('导出完成!');
|
||
console.log('文件路径:', status.data.result.FilePath);
|
||
console.log('文件大小:', status.data.result.FileSize, 'bytes');
|
||
completed = true;
|
||
} else if (status.data.status === 'Failed') {
|
||
console.error('导出失败:', status.data.errorMessage);
|
||
completed = true;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
| HTTP 状态码 | 含义 | 使用场景 |
|
||
|---|---|---|
|
||
| 200 | 成功 | 操作成功完成 |
|
||
| 202 | 已接受 | 异步任务已创建 |
|
||
| 400 | 请求错误 | 参数错误、文件不存在等 |
|
||
| 404 | 未找到 | 任务不存在 |
|
||
| 500 | 服务器错误 | 内部处理错误 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **前置条件：** 确保 Revit 2017 已启动且插件已加载
|
||
2. **文件路径：** 必须使用完整的绝对路径，路径中的反斜杠需要转义
|
||
3. **同步 vs 异步：**
|
||
- 同步接口适用于快速操作，直接返回结果
|
||
- 异步接口适用于耗时操作，返回任务ID需要轮询
|
||
4. **错误处理：** 所有错误都有详细的错误码和描述
|
||
5. **网络安全：** 仅限内网使用，不建议暴露到公网
|
||
|
||
---
|
||
|
||
## 测试工具
|
||
|
||
### Postman 测试配置
|
||
|
||
1. **导入基本配置**
|
||
- Base URL: `http://localhost:9000/api`
|
||
- Content-Type: `application/json`
|
||
|
||
2. **测试顺序**
|
||
- 先测试 `GET /health` 确认服务正常
|
||
- 然后测试 `POST /open` 打开文件
|
||
- 最后测试 `POST /stats/sync` 获取统计
|
||
|
||
3. **示例测试数据**
|
||
```json
|
||
// 打开文件
|
||
{
|
||
"filePath": "C:\\temp\\test.rvt",
|
||
"detached": false
|
||
}
|
||
|
||
// 统计墙体
|
||
{
|
||
"type": 0
|
||
}
|
||
|
||
// 同步导出IFC
|
||
{
|
||
"IfcVersion": "IFC4",
|
||
"OutputPath": "C:\\Export\\test.ifc",
|
||
"ExportRange": "VisibleElements",
|
||
"IncludeSpaceBoundaries": true,
|
||
"ExportBaseQuantities": true
|
||
}
|
||
|
||
// 异步导出IFC（大文件）
|
||
{
|
||
"IfcVersion": "IFC4",
|
||
"OutputPath": "C:\\Export\\large_model.ifc",
|
||
"ExportRange": "AllElements",
|
||
"IncludeSpaceBoundaries": true,
|
||
"ExportBaseQuantities": true,
|
||
"ExportUserDefinedPsets": true,
|
||
"ExportIFCCommonPropertySets": true
|
||
}
|
||
```
|
||
|
||
4. **导出接口测试顺序**
|
||
- 先测试 `GET /api/export/formats` 获取支持格式
|
||
- 确保有文档打开后测试 `POST /api/export/ifc`
|
||
- 测试异步导出 `POST /api/export/ifc/async` 并轮询任务状态 |