1. 课程概述：ThingsBoard平台简介、设备批量导入的必要性、CSV模板与API调用的整体流程
1.1 ThingsBoard平台简介
ThingsBoard 是一个开源的企业级物联网平台，用于设备管理、数据收集、可视化和规则引擎处理。它支持多种物联网协议（MQTT、CoAP、HTTP），并提供可扩展的微服务架构。平台核心能力包括：
- 设备管理：创建设备、管理凭据、组织设备层级。
- 遥测数据：实时采集时间序列数据，支持聚合与存储。
- 属性管理：管理客户端属性、共享属性和服务端属性。
- 规则引擎：基于节点链处理数据、触发告警、执行动作。
- 仪表板：可视化数据，支持实时刷新与交互。
- REST API：提供完整的HTTP API，支持第三方集成与自动化。
版本说明：本课程基于 ThingsBoard 3.6.x 社区版（CE）与专业版（PE）通用API。企业版用户同样适用，部分高级字段（如客户分组、资产关联）仅在PE中生效。
1.2 设备批量导入的必要性
在实际物联网项目中，设备数量往往从几十到数万不等。手动在UI界面逐条创建设备存在以下痛点：
| 对比维度 | 手动创建（UI） | 批量导入（CSV + API） |
|---|---|---|
| 操作效率 | 每台设备约30秒，100台耗时50分钟 | 100台设备约5秒（API调用） |
| 错误率 | 高（人工输入易错、重复、遗漏） | 低（模板校验 + 程序化写入） |
| 可重复性 | 每次需重复操作，无法版本控制 | CSV文件可复用、可纳入CI/CD |
| 复杂属性 | 难以批量设置共享属性、客户关联 | CSV列映射直接写入属性 |
| 审计追溯 | 无操作日志 | API日志可记录每次导入详情 |
批量导入的核心价值在于：节省时间、降低错误、支持大规模设备上线、便于自动化运维。对于需要频繁添加设备（如产线部署、设备迁移、测试环境搭建）的场景，CSV+API方案是标准实践。
1.3 CSV模板与API调用的整体流程
本课程将引导你完成从CSV模板设计到API调用的完整链路。整体流程如下图所示：
上述流程可归纳为三个主要阶段：
- 准备阶段（步骤①-③）：设计CSV模板、填充设备数据、获取ThingsBoard API访问令牌。
- 执行阶段（步骤④-⑥）：解析CSV文件、构建HTTP请求、调用设备创建API并处理响应。
- 验证阶段（步骤⑦）：通过UI或API查询确认设备已正确创建，属性与凭据无误。
1.4 课程核心知识点结构
本课程将围绕以下知识模块展开，每个模块均包含理论讲解、CSV模板示例、API调用代码（Python/curl）及常见问题排查：
| 模块 | 核心内容 | CSV模板重点 | API接口 |
|---|---|---|---|
| 基础设备导入 | 创建设备、设置名称与类型 | name, type, label | POST /api/device |
| 带凭据导入 | 批量设置MQTT/HTTP访问令牌 | access_token, mqtt_username | POST /api/device + 凭据更新 |
| 属性批量写入 | 导入时写入共享属性与服务端属性 | attributes:key1,value1|key2,value2 | POST /api/plugins/telemetry/DEVICE/{id} |
| 客户与资产关联 | 将设备分配给客户、关联资产 | customer_id, asset_name | POST /api/customer/{customerId}/device |
| 高级校验与错误处理 | 重复检测、字段校验、批量回滚 | 唯一标识列、校验规则 | 批量状态码处理 |
课程前置要求：建议具备基础的REST API概念（HTTP方法、状态码、JSON格式），了解Python或curl的基本使用。无需深入ThingsBoard内部架构，但熟悉设备管理UI会有帮助。
1.5 课程配套资源
每章均提供以下配套材料，可在课程附件中下载：
- CSV模板文件（.csv）：包含示例数据与列说明。
- Python脚本（.py）：使用requests库实现批量导入。
- curl命令示例（.txt）：适用于Linux/Mac/Windows Git Bash。
- Postman集合（.json）：可直接导入Postman进行测试。
现在，让我们从第2章开始，深入CSV模板的设计规范与字段映射规则。