简介：这份资源面向正在接入中国电信物联网开放平台的开发者和解决方案集成人员，围绕北向RESTful接口提供可快速运行的Demo例程，帮助从零验证应用鉴权、设备管理、消息订阅、数据采集、命令下发及批量任务等核心业务流程，适合需要梳理平台调用逻辑、加速联调交付的团队参考。压缩包共4.59MB，虽未展示文件总数与明细，但目录结构清晰，src目录存放可直接阅读和改造的Demo源码，open source components目录集中了工程依赖jar包，便于本地环境部署与二次开发对照，属于轻量型上手范例。目前已有1389人浏览学习，适合具备一定接口开发基础、希望减少平台对接试错成本的读者使用。通过这套Demo可以快速理解北向接口在真实业务中的调用顺序、请求参数和组织方式，节省阅读冗长文档的时间，也能借助源码与依赖包直接搭建验证环境，为后续自有业务系统接入天翼物联网平台提供可复用的参考起点。
1. 中国电信物联网开放平台API Demo例程：它到底能帮你省掉多少事
做物联网设备接入的人，十有八九都经历过这种尴尬：硬件选型两周搞定，模组调通三天，结果卡在平台对接上又耗了一周——翻文档、猜接口、试密钥，甚至因为一个URL拼错导致整个联调返工。中国电信物联网开放平台API Demo例程就是为解决这件事准备的：它把设备接入、鉴权、数据上报、命令下发这些高频动作写成可直接运行的示例，让你不用从零啃文档。这篇文章我想基于我对这类平台API的接入经验，把Demo例程背后到底有什么、怎么跑通、参数怎么调、哪些坑容易反复踩，一次说清楚。适合正在做设备接入的嵌入式工程师、后端开发者，以及刚接触平台API想快速验证方案的团队。
2. 先搞懂平台的三个基础逻辑：设备身份、接入方式和API调用顺序
动手跑Demo之前，先把平台的运行逻辑理清楚。电信物联网开放平台本质上是一个设备接入与管理的中台，它对上提供RESTful API给应用服务器调用，对下通过MQTT、CoAP、HTTP等协议接入设备。很多人在Demo里跑不通，不是因为代码有问题，而是没理解平台的鉴权体系和数据流方向。
2.1 设备身份体系：为什么每个设备要有一把单独的钥匙
平台把“应用”和“设备”分成两层身份。应用身份用来调用管理面API，比如查询设备列表、下发命令；设备身份则是设备端上报数据时用的凭证。这两套身份不能混用，很多新手拿应用密钥当设备密钥去连设备接入地址，结果一直被拒绝。
我在实际接入中常见的做法是：先在产品维度创建应用，拿到应用ID（也叫appId）和应用密钥（appSecret）；再在产品下注册具体设备，平台会为每个设备分配唯一的设备ID和设备密钥。注意这里的设备ID不是IMEI或SN，它是平台内部生成的一串ID，业务上你可以通过“设备唯一标识”字段把自己业务里的设备编码映射过来。
Demo例程里通常会在配置文件中放三组信息：应用凭证、设备凭证、接口地址。跑通前先核对这三组信息是否对应同一产品下的资源，否则最常见的报错是“signature mismatch”或者“设备不存在”。
2.2 两条数据链路：上行上报与下行命令不要把方向搞反
平台的API大致分成两类调用方向。设备数据上行，例如湿度、电压、位置等状态上报，走的是设备接入层的发布接口；平台对设备的控制，比如开锁、重启、远程配置，走的是命令下发接口——应用服务器调用平台的下发API，平台再推给设备。
我在联调Deme时发现，最容易混淆的是“回调”和“查询”。平台支持两种拿数据的方式：一种是设备主动上报后，平台通过HTTP回调或消息推送把数据转给你的应用服务器；另一种是应用主动调用API查询设备最新数据。Demo例程里两个都会演示，但你要清楚自己的场景适合哪一种。上报频繁的传感器适合走推送，低频查询适合走拉取，两种混用会导致重复数据或漏数据。
2.3 Demo例程的常见工程结构：先拆开再逐段验证
电信物联网开放平台提供的Demo例程，通常是一个“主程序+配置文件+若干功能模块”的结构。主程序负责初始化，功能模块按业务拆，比如设备注册模块、数据上报模块、命令响应模块。拿到手先别急着整体跑，我一般会先把配置文件里的三个参数填好，然后逐个模块验证。
举一个我常用的最小验证顺序：先调鉴权接口拿到Token，再用Token查一次设备信息，如果这两步通了，说明身份体系没问题；接着单独跑数据上报，用平台控制台看能不能查到这条记录；最后才跑命令下发回调。这个顺序把问题隔离在每一层，不会出现“全跑起来但不知道死在哪”的黑匣子状态。
3. 把环境跑通：从控制台配置到拿到第一个真实Token
很多人拿到Demo例程就急着打开IDE编译，这是翻车的开始。平台API联调的前提是控制台配置正确，否则代码写得再好也是白搭。这一章我把从注册到拿到Token的全过程拆成可直接照做的步骤。
3.1 三步完成控制台配置：产品创建、设备添加、密钥保存
第一步，登录平台开发者控制台，创建一个产品。产品是什么？它是你设备的“型号+业务”容器，同一批功能相同的设备放一个产品下。创建时需要填产品名称、所属行业、联网方式、协议类型。我建议协议类型按设备模组能力选，不要为了Demo硬选MQTT，如果设备只支持TCP透传，就选HTTP或透传模式。
第二步，在产品下添加设备。这一步会让你填设备标识和初始配置信息，控制台会生成设备ID和设备密钥。这里有个关键点：页面一旦切换或关闭，设备密钥可能不再完整展示。我见过不止一个人漏存密钥，最后只能删掉设备重新注册。正确做法是添加完立刻把密钥复制到本地密码管理器里。
第三步，找到应用管理页面，创建或查看应用凭证。这里会有应用ID和应用密钥，与应用密钥配套的还有Token调用地址。把这个地址复制下来，后面要拿它换Token。注意不同环境（开发沙箱与生产环境）的应用凭证不通用，别混着用。
3.2 用curl先验证鉴权接口：Token怎么拿、怎么用、怎么续
配置好控制台，先别写代码。打开终端，用curl调一次鉴权接口，看看能不能拿到Token。下面的命令是常见做法，接口路径请以平台最新开发文档为准。
curl -k -X POST \ 'https://<平台域名>/iocm/app/sec/v1.3.0/login' \ -H 'Content-Type: application/json' \ -H 'appId: <你的应用ID>' \ -H 'secret: <你的应用密钥>' \ -d '{}'如果返回结果里有token字段和expiresIn字段，说明鉴权通了。其中expiresIn是以秒为单位的Token有效期，常见的是3600秒，也就是一小时。这个字段决定了你的程序里必须做Token缓存和自动刷新，不能每次请求都重新登录。
拿到Token后的调用方式是把Token放在请求头里，格式一般是Authorization: Bearer <token>。我习惯把Token手动填到API调试工具里先验证一个查询接口，确认“鉴权Token能用”这个前提成立后再进入代码复现阶段。
3.3 为什么建议先用API调试工具而不是直接改Demo
很多工程师拿到Demo例程的代码，第一反应是修改配置文件然后直接编译。我的建议是反过来：先打开API相关调试工具，新建请求，把鉴权接口和查询接口用工具调通，再回来看Demo代码。
原因很简单：Demo例程里有异常处理、日志输出、重试机制等工程化代码，一旦出错，你分不清是业务逻辑问题还是网络问题。而API调试工具把请求、响应、Header全部直观展示，出错时一眼锁定是参数问题、签名问题还是平台返回的具体错误码。
用工具调通的另一个目的，是拿到“正确的请求报文样例”。把这个样例与Demo代码里构造的请求体逐一对比，检查请求头字段大小写、时间戳格式、签名算法是否一致。这一步能避免大量因为格式差异导致的联调失败。
4. 复现两个核心Demo例程：数据上报与命令下发
平台接入最核心的两个动作就是设备数据上报和平台命令下发。这一章不贴完整工程代码，而是把Demo例程里最关键的请求构造、参数含义和返回值处理讲透，让你能对着自己的产品改出可运行的版本。
4.1 数据上报Demo：请求体里的每个字段是什么
数据上报走的是设备接入API，常见协议是HTTP POST或MQTT publish。这里先说HTTP方式，因为它最容易排错。上报的URL一般是https://<平台域名>/iocm/app/device/v1.3.0/device/<设备ID>/datas，请求头带Token，请求体是JSON数组。
curl -k -X POST \ 'https://<平台域名>/iocm/app/device/v1.3.0/device/<设备ID>/datas' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "data": [ { "serviceId": "Temperature", "properties": {"value": 36.5} } ] }'serviceId是产品模型里定义的服务名，properties里的键必须与产品模型里定义的属性名完全一致。这里有个隐蔽坑：平台对属性名是大小写敏感的，产品模型里定义的是temp，你上报Temperature或TEMP都无效。我在联调时吃过这个亏，平台返回200但控制台查不到数据，后来逐字符对比才发现是大小写问题。
上报成功后，平台一般返回{"statusCode": 0}这样的成功码。如果返回非0码，优先检查设备ID是否写对、Token是否过期、请求体JSON格式是否合法。注意很多Demo例程会做本地时间戳和平台时间的校验，时间差过大也会被拒。
4.2 命令下发与回调：双向通信的落地姿势
命令下发是反向链路：你的应用服务器调用平台API，平台把消息推给设备。这个动作涉及四端协作：应用服务器、平台、设备、设备固件。Demo例程通常会在设备端演示如何接收平台下发的命令，并在应用侧演示如何调用下发接口。
应用侧调用下发API的请求体里，核心参数是设备ID、命令名和命令参数。命令名要与产品模型里定义的命令一致，命令参数是JSON对象，比如开锁命令就是{"lock": 1}。设备端收到命令后，需要返回执行结果，这个结果通过设备上报一条带“命令响应标识”的数据来闭环。
我踩过的一个坑是回调地址配置。平台要求你在控制台配置命令响应回调地址，如果配的是http://localhost:8080/callback，平台无法访问，命令响应永远收不到。正确做法是用内网穿透工具或部署到有公网地址的测试服务器上，让平台能回调到你的服务。本地开发时可以先用线上调试工具看平台推送的原始报文，再决定本地怎么验证。
4.3 MQTT方式什么时候用：和HTTP上报的取舍
不是所有场景都需要MQTT。HTTP上报是“设备主动发起连接”，一次一请求，服务端无状态，适合功耗不敏感、频率不高的设备。MQTT则是长连接+发布订阅模型，适合低功耗广域网、弱网环境、需要服务端随时下行的场景。
我看过不少团队因为Demo例程里有MQTT版本，就盲目选MQTT接入，结果设备端内存不够跑协议栈，或者频繁掉线重连导致流量超标。我的建议是：如果你的设备是插座、门锁、传感器这类低频小包，HTTP足够；如果是车载、NB-IoT水表、移动手持终端这类需要实时下行控制的，才考虑MQTT。
MQTT版Demo的接入参数主要包括Broker地址、端口、ClientId、用户名和密码。这里的用户名密码一般是设备ID和设备密钥，不是应用凭证。很多人拿应用ID去连MQTT，连接被拒是肯定的。还有Topic的层级是平台规定的，不要自己命名。
5. 电信物联网开放平台API Demo的避坑指南：五个高频翻车点
跑Demo例程和跑自己的业务代码是两回事，Demo虽小，但平台对接的边界条件一样不少。这一章我把五个最容易翻车的问题按“现象、原因、解决”写清楚，基本都是我在联调过程中反复遇到的。
5.1 Token过期导致间歇性401
现象是程序刚启动一切正常，跑了几分钟或几个小时后，某些请求突然返回401未授权。重启程序又好了，过一会儿又坏。
原因是Token有效期到了但代码没有自动刷新。很多Demo例程只在程序启动时调用一次鉴权接口，后续所有请求共用这个Token。当expiresIn到期后，平台拒绝调用。
解决方法是把Token加缓存并做过期刷新。常见做法是一个定时任务在到期前5分钟重新调用鉴权接口，把新Token替换旧Token。注意并发问题，在Java里用单线程定时任务就行，不要开多个线程同时刷新。
5.2 设备数据上报成功但控制台查不到
现象是接口返回成功码，代码也没报错，但在平台控制台的设备历史数据里看不到任何记录。
原因是属性名或服务ID与产品模型不一致，或者数据格式里混入了平台不认识的多余字段。平台可能选择忽略非法字段而只落合法字段，导致部分数据丢失。
解决方法是先打开产品模型页面，逐字段复制属性的精确名称和类型，再核对上报JSON。仔细检查每个键的名称、大小写、值类型，尤其注意浮点数和整数的区别。还有一个办法是上报时只带业务必需的属性，不要混入杂项字段。
5.3 回调地址一直验证不通过
现象是控制台配置命令回调时，平台提示URL验证失败或超时。
原因是平台验证回调URL时，会向你的回调地址发起一个GET请求并带一个随机参数，你的服务必须把这个参数原样返回给平台。如果服务端没有处理这个GET请求，或者返回格式不对，验证就失败。
解决方法是先确认回调地址能被公网访问，然后写一个简单的路由处理GET请求，收到平台参数后原样返回。不要在这个路由逻辑里做复杂业务，验证阶段只做回显就行。验证通过后再把真实业务加进去。
5.4 设备ID、IMEI、序列号在代码里混用
现象是有些请求里需要设备ID，你填了IMEI；有些查询需要IMEI，你填了设备ID。平台一会儿返回设备不存在，一会儿返回参数错误。
原因是平台内部有三套标识：平台生成的设备ID、设备侧上报的IMEI或MAC、业务自定义的设备序列号。这三套标识的用途不同，不能互换。
解决方法是维护一张映射表，在代码里明确区分：调用平台管理API时用设备ID；上报数据时按接口要求填设备侧的IMEI或自定义标识；业务展示时用序列号。建议在配置文件里给三种标识分别命名，不要笼统叫“deviceId”。
5.5 沙箱环境与生产环境配置串了
现象是本地测试全部正常，上了生产环境后所有请求都报应用不存在或签名错误。
原因是控制台或配置文件里混用了两套环境的域名和应用凭证。沙箱的密钥在生产环境无效，反之亦然。
解决方法是把两套环境的配置完全隔离，用两个配置文件或两套环境变量管理。我在工程里通常用application-dev.yml和application-prod.yml区分，部署时显式指定加载哪套配置，避免默认加载到开发环境的值。
6. 把Demo当模板用：一种能直接复用的调试闭环
跑通Demo不是终点，终点是把它变成你自己项目的脚手架。我最后分享一个调试闭环，这套流程已经帮几个团队把平台接入时间从两周压到三天。
先建一个“最小验证脚本”，把鉴权、上报、查询三个动作串成一条链路。每次改代码只跑这条链路，不要全量回归。链路里每个关键点都打日志，包括请求URL、请求体、响应码、Token剩余有效时间。日志是排障的唯一线索，宁可多打不可少打。
再准备一个“模拟设备端”。用脚本模拟设备的上报行为，而不是每次让真实硬件去发。这样就可以在没有硬件的情况下把平台侧的逻辑全部验完。很多公司的硬件进度慢，后端完全可以用模拟数据先行开发。
最后加一个“命令回执自检”。下发命令后，定时查询设备的命令执行状态标记，确认命令是否真正被设备执行。很多联调卡在“发了命令但不知道设备有没有执行”这一步，通过查状态字段就能把黑匣子打开。
这套闭环用好之后，你的团队再对接任何物联网平台，都会习惯性地先做最小链路、再补边界、最后压性能。我在多个项目里反复验证过，这个顺序比拿到需求就写业务代码靠谱得多。希望帮到你。
本文还有配套的精品资源，点击获取
