7月08日-02-余名兴_林燕发-API对接开发基础.pdf

视联网深度二开：API对接开发基础 天翼视联科技有限公司 余名兴、林燕发 2024年.7月 1 一、课程背景： 课程大纲 1、业务背景：中国电信天翼视联能力开放平台可满足相关政府部门、省市应用平台对视 第一讲 门户入驻流...

视联网深度二开：API对接开发基础 天翼视联科技有限公司 余名兴、林燕发 2024年.7月 1 一、课程背景： 课程大纲 1、业务背景：中国电信天翼视联能力开放平台可满足相关政府部门、省市应用平台对视 第一讲 门户入驻流程指引 频源的集中管理、远程实时查看、远程调用录像、分级授权等功能要求，实现了视频流、 1、门户入驻整体流程 转码流、AI消息流、图片流等四大类能力的标准化对接与开放输出 2、门户入驻 2、中心思想：如何快速对接天翼视联能力开放API接口 3、原子能力下单 二、培训对象： 4、创建应用 燎原计划精英学员 5、开发调试 三、课程收益： 6、审核上线 1、熟悉能力开放门户的入驻流程，掌握门户的常用配置项； 第二讲 接口对接指引 2、掌握天翼视联能力开放API接口的接入协议与规范； 1、门户关键配置 3、了解并掌握能力开放3种获取访问令牌的对接流程； 2、接口规范 4、能够独立完成基础API的对接，包括常用的目录树，设备数，直播，云回看等； 3、获取访问令牌 四、课程时长：9小时 4、获取设备列表 五、教学形式：讲授（30%）、小节解答（10%）、演示实操（20%）、实践（40%） 5、查询监控目录 课程大纲 6、查询我的设备 2、点评分析 7、查询行业树目录 8、案例分析 9、根据设备编码调API业务接口 10、常用API接口功能简介 第三讲 操作演示 第四讲 问题解答 1、问题讨论与小结 第五讲 实操环节 1、实操演练  01 门户入驻流程指引 目 02 接口对接指引 03 操作演示 录 04 问题解答 05 实操环节  门户入驻整体流程 天翼视联能力开放门户提供一站式的自助接入服务，使接入流程各环节信息化，支持应用创建、原子能力申请、原子能力订单自动 关联、白名单自助配置、添加企业主账号等自助服务。 门户入驻 原子能力下单 创建应用 开发调试 审核上线  门户入驻 进入门户，点击“注册”进入合作方注册页面，录入合作方基本信息并提交，完成合作方入驻申请； 参考链接：https://vcp.dlife.cn/portal/cooperative-access 流程： 1 2 进入注册页 扫码注册 录入基本信息 3 4 上传资质文件  原子能力下单 通过门户-能力仓跳转数字化原子能力平台下单订购“平台对接”+对应原子能力，包括“天翼视联能力开放-省应用平台对接”或 “天翼视联能力开放-市应用平台对接”、“天翼视联能力开放-基础视频流”、“天翼视联能力开放-转码流”、“天翼视联能力开 放-图片流”、“天翼视联能力开放-消息流”等，可通过门户“能力仓”进行查看，选购。参考链接： https://vcp.dlife.cn/portal/ability-mall 1 2 流程： 点击链接 https://atom.189.cn，跳转 数字化原子能力平台 下单订购 “平台对接”+对应原子能 力（只下单不调用不产生费用） 3 4 注：每个原子能力订单对应能力是一个能 力集合，包含多个API接口能力  创建应用 登陆门户，进入管理中心/我的应用，点击创建应用，进行应用的创建及应用基本信息的录入，根据填入的原子能力订单号（原子 能力下单环节获取到的订单号）或上传商务需求调研表附件申请应用的能力权限； 详情可参考链接：https://vcp.dlife.cn/portal/cooperative-access 主要流程 录入应用基本信息 能力申请 注： 在能力申请中，需要填写“关联订单”，若不填写，后期 应用试用期过期后需要补录，只有实际在原子能力平台下 单，关联到创建的应用，并在应用授权能力对应的API接 口，对接时才能有权限调相关接口 若暂未订购原子能力订单，可通过上传“需求调研表”申 请API接口30天试用期 在能力申请中，标准API应用可选项对接的授权模式，天 翼账号，用户扫码，无感知3种获取访问令牌的方式之一 ，请慎重选择，应用创建完成后在对接时必须按照对应方 式对接，如需修改，可在能力申请中变更授权方式 除标准API应用外，其他应用类型授权方式都是无感知  开发调试 应用创建成功后，开发者可查看应用授权信息、授权凭证、可进行服务器IP配置、业务域名配置、消息推送设置等。查看文档中心相 应接口文档进行对接-文档中心：https://vcp.dlife.cn/portal/document 开发调试关键步骤 查看应用授权信息 掌握API接口规范 获取访问令牌 通过API接口获取授权登录用户 收编的设备 根据设备编码调用API业务接口  审核上线 开发者完成应用开发点击应用列表上架按钮，能力开放平台审核人员在后台完成应用审核后即完成对接上线。 上架流程： 在应用管理页，点击卡片的【上架】按 钮，发起上架流程。 填写和上传相关信息后，点击【提交】 后台会在三个工作日内进行确认。 注：在申请应用时，默认为测试版本应用 ，测试版只有30天有效期，请在调试成功 后30天内上架应用，完成审核上线，否则 应用过期后服务会拒绝该应用的所有请求 流程  01 门户入驻流程指引 目 02 接口对接指引 03 操作演示 录 04 问题解答 05 实操环节  门户关键配置 应用授权信息： AppID: 应用appId,公共请求参数，用于校验appId的有效性 AppSecrect: 请求密钥，用于公共请求参数，加密和签名或 响应参数解密 RSA私钥：合作方用于响应参数或消息推送数据解密 RSA公钥：平台用于响应参数加密（合作方可用于测试数据 验证加解密） 关键配置项 服务器IP白名单：API接入方服务器公网出口IP 授权回调域名：用户扫码授权方式（必填）的应用接收授 权码的域名， 业务域名：播放视频的应用域名，用于解决WEB浏览器播 放直播流时跨域问题  接口规范 接口规范，是所有接口都必须遵守的，包括三部分：通信协议，请求参数以及请求头 参考链接：https://vcp.dlife.cn/portal/document-detail?group=1635521788683673602 通 信 协 议 平 台 对 接 环 境 请 求 头  接口规范 把接口里面定义的私有请求参数加密成 params，然后把以下请求参数放入 Http Request 中，组成 固定的请求参数，最终提交给平台的参数如下表。 公共请求参数 业务请求参数  获取访问令牌 天翼账号鉴权 用户扫码 用户无感知 1、完成天翼账号的对接并获取天翼账号的 1、调能力开放接口getAuthPageUrl获取 1、门户-我的应用-应用详情-企业主管理添 tokenCode 登录框 加并进行企业主授权 2、用户扫码登录成功后重定向到上一步接 口getAuthPageU的请求参数callbackUrl 地址，并携带授权码authCode 2、使用天翼账号tokeCode调能力开放接 口getAccessToken获取能力开放访问令 牌，即天翼视联访问令牌 2、调能力开放接口getAccessToken获取 能力开放访问令牌，即天翼视联访问令牌 3、使上一步获取的授权码authCode调能 力开放接口getAccessToken获取能力开放 访问令牌，即天翼视联访问令牌 3、无感知应用调API业务接口时必传参数 ：enterpriseUser即为第一步中授权的企业 主账号对应手机号  获取设备列表 对接前需明确设备是如何收编到云眼账号的，收编方式有一般三种，分为：绑定，级联或由省份的天翼云眼管理后台分配，对应三 颗树，分为设备树，业务树（目录树），行业树（固定业务树），不同的收编方式（树）在获取设备列表是调用的API接口是不同的 ，请通过对应的API接口获取设备列表 业务树 设备树 行业树 收编方式： 收编方式： 用户（企业主）将绑定在设备树上的设 级联设备（最常用的把设备挂到业务树 收编方式： 备级联到固定业务树上 的方式） 绑定设备到云眼账号 用户（企业主）将业务树上的设备级联 拉取看家的设备 到固定业务树止 级联国标设备 由管理员在后台将现在业务树生成为行 拉取国标设备 业树 查询监控目录：对应获取业务树（目录树 查询我的设备：对应设备树 查询行业目录：对应行业树 ）设备 参考链接： 树参考链接： 参考链接： https://vcp.dlife.cn/portal/document- https://vcp.dlife.cn/portal/document- https://vcp.dlife.cn/portal/document- detail?group=1601202223413760002 detail?group=1601202223413760002 detail?group=1601202223413760002 树形结构：一般情况需要结合获取目录与获取设备列表接口，遍历递归整颗树  查询监控目录（业务树） 分类 接口名称 接口字段标识 描述 注意事项 查询监控目录树 getReginWithGroupList 获取监控目录结构 此接口只是获取业务树目录结构，通过响应参数判断是否 有下级目录，当前目录（不包含下级）层级是否有设备 查目录/路径 通过监控目录ID查询目录路径 getFullRegionPath 查询目录全路径 按目录名称模糊查询目录 getCusDirByDirName 业务树 - 按目录名称模 糊查询目录 查询监控目录子目录设备列表 getDeviceList 查询监控目录设备列表 只能获取当前目录层级的设备，若需要获取下级目录的设 备需要重新调用此接口并传入下级区域id（对应查目录接 口中响应参数区域id） 按分页方式查询监控目录设备 getAllDeviceListNew 获取设备列表，通过该 total 参数只在首次查询结果后返回，请留意保存，通过该 列表 接口分页查询账号下所 接口分页查询账号下所有设备列表 lastId 参数首次必传， 有设备列表 下一次分页查询传入接口返回lastId数值，当lastId返回-1 时表示数据查询完毕 查设备 根据经纬度范围查询备列表 getDevByLongitudeAndLati 根据经纬度范围查询设 若设备收编是未配置经纬度，此接口无法查到该设备 tude 备列表 按设备名称模糊查询设备 getCusDevicesByDeviceNa 业务树 - 按设备名称模 me 糊查询设备 按设备码查询设备 getCusDeviceByDeviceCod 业务树 - 按设备码查询 e 设备 查询监控目录子目录区域设备 getCusDeviceCount 查询监控目录子目录区 查的是当前目录的子目录，不包含当前目录，为空查首层 数、在线设备数 域设备数、在线设备数 目录 查询监控目录树设备总数、在 getCusTreeDeviceCount 查询监控目录树设备数 查询整个目录树 查数量 线设备总数（数据岛） 量、在线设备数量 批量查询监控目录设备总数 batchRegionCount 批量查询目录设备总数  查询监控目录（业务树） 获取目录 1.此接口只是获取业务树目录结构，通过响应参数判断是否有下级 2.目录结构展示 目录，当前目录（不包含下级）层级是否有设备  查询监控目录（业务树） 获取设备列表 1.查询监控目录设备列表（普通分页） 2.按分页方式查询监控目录设备列表（游标）  查询我的设备（设备树） 分类 接口名称 接口字段标识 描述 注意事项 查询设备树目录结构（行政区 getRegions 查询云眼设备树目录结构 获取的是一个包含行政区域的6级目录， 域） 只有最后一层级目录包含设备 查询设备树最后一层目录列表 getLastRegions 查询设备树最后一层目录列表 如果不需要获取6级行政区域目录，可直 说明：通过云眼app登录看到的“我 接调此接口获取最后一层级目录，用此目 查目录/路径 的设备”目录 录id可直接调用 getDevicesByRegionCode获取所有设备 树上的设备 按目录名称模糊查询目录 getDeviceDirByDirName 设备树 - 按目录名称模糊查询目录 根据区域码分页查询设备树下 getDevicesByRegionCode 根据区域码查询设备列表 设备树只有最后一层级有设备 设备列表 根据条件查询设备列表 getDevicesByRegionCon 根据条件查询设备树下设备列表 查设备 按设备名称模糊查询设备 getDevicesByDeviceName 设备树 - 按设备名称模糊查询设备 按设备码查询设备 getDevicesByDeviceName 设备树 - 按设备码查询设备 查询设备树设备总数、在线设 getDeviceCount 查询设备树设备数、在线设备数 查数量 备总数（数据岛）  查询我的设备（设备树） 查询我的设备 1.查询设备树最后一层目录列表 2.根据区域码分页查询设备树下设备列表（分页）  查询行业树目录（行业树） 分类 接口名称 接口字段标识 描述 注意事项 查询行业目录树 getProRegionList 查询行业树目录结构 此接口只是获取业务树目录结构，通过响应参 数判断是否有下级目录，当前目录层级是否有 设备 模糊查询行业树区域信息 getRegionList 模糊查询行业树区域信息 请求参数sortArr为上一次查询结果返回的 sortArr字符串数组，非首次查询必传，这是滚 查目录/路径 动查询的标识（游标实现） 按设备编码获取固定树路径 getFixDeviceRegion 查询用户有权限的固定业务树设备 查的路径信息更详细，每一级目录信息都有， 全路径 包含区域id，层级信息等 按设备编码查询固定业务树全 getFixDeviceRegionLink 按设备编码查询固定业务树全路径 查的路径信息简单，只有层级区域名称 路径 Name 根据区域编码获取行业树设备 getProDevicesByRegion 根据区域编码获取行业树设备列表 请求参数lastId：每次批量查询后的最后一个 列表 Code id，首次查询不传（游标实现） 分页获取用户行业树下设备列 getDeviceByTagAndRegi 根据条件查询设备树下设备列表 区域编码regionCode不传查首层，可结合 表 on getProRegionList遍历递归整颗树 查设备 按设备名称模糊查询设备 getFixDirByDirName 行业树 - 按设备名称模糊查询设备 按设备码查询设备 getFixDeviceByDeviceCo 行业树 - 按设备码查询设备 de 查询行业树设备总数、在线设 getFixTreeDeviceCount 查询行业树设备数、在线设备数 查询行业树整颗树 备总数（数据岛） 查数量 查询行业树子目录设备数、在 getDeviceCount 查询行业树子区域设备数、在线设 查询行业树当前区域的子区域 线设备数 备数 查询用户行业树行业标签信息 getFixTreeTagInfo 查询用户行业树行业标签信息 标注是那个行业应用的，如明厨亮灶，平安慧 其他 眼等，每个省份都唯一  查询我行业树目录（行业树） 查询行业树目录 1.查询行业目录树 2.目录结构展示  查询我行业树目录（行业树） 查询设备列表 1.分页获取用户行业树下设备列表（普通分页） 2.根据区域编码获取行业树设备列表（游标）  案例分析 查询目录 查询设备 查询总数 设备状态 设备详情  根据设备编码调API业务接口 天翼视联能力开放绝大多数API接口都是基于授权登录云眼企业主与设备（设备编码）去调用的  常用API接口能力简介 分类 接口能力名称 描述 查询设备基础信息 获取设备详细信息，包括设备在线状态，绑定用户，设备来源，设备配置信息，接入协议等 查询设备能力集 获取设备上报的支持那些能力，如语音对讲，1400图片抓拍，云台控制等 获取设备1400图片抓拍，人脸抓拍或车牌抓拍开关的开关状态 查询AI开通信息 查询授权登录的云眼账号开通的AI销售群信息，该账号名下设备ai销售品开通使用情况，场景能力信息 查询设备AI告警信息 只能查询AI单品的告警信息 基础视频流能力 刷新告警信息中过期的图片链接 应用级消息推送 将此应用授权登录的云眼账号下的设备的部分告警信息推送合作方指定接口地址，如设备上下线，设备 绑定，接连，目录结构变更等 标准直播视频流 获取设备标准rtsp直播流地址 云回看文件下载 获取设备云回看云目录结构，云存文件，下载地址等 云回看视频流 获取云回看视频链接地址，查看云存文件详情，云存策略等  常用API接口能力简介 分类 接口能力名称 描述 转码直播视频流 获取设备的hls,rtmp,webrtc直播链接 转码云回看视频流 获取云回看云存文件的hls,rtmp视频播放链接 转码流能力 云存剪辑 剪辑设备云存文件指定时间范围内的云存文件生成一个新的视频云存文件，并可获取该新视频文件下 载地址 查询设备1400图片 获取设备1400图片抓拍的图片列表，图片详情等 图片流能力 推送设备1400图片 通过订阅1400图片抓拍告警将抓拍图片推送到合作方知道接口地址 语音对讲 1 对 1 双向实时语音对话 云台控制 远程下发信令到设备，控制设备变焦变倍，转动等 增值能力 TF卡流化 获取设备端设备TF卡，SD卡设存储的视频列表，播放链接等 视频编码转换 获取直播，转码指定编码格式的流地址，如直播流转码264，265,云回看流转码264，265  常用API接口能力简介 分类 接口能力名称 描述 订阅云眼AI单品告警消息，将告警消息到合作方指定接口地址 类型：3 画面异常巡检，4 时光缩影，5 区域入侵，12客流统计，13厨帽识别，14抽烟识别，15口罩 识别，16玩手机识别，17火情识别，7人脸布控，6 车牌布控，21大象识别；22 电动车;25 人群聚集 订阅设备AI告警消息 检测，26 医用防护服检测，27 高空抛物，28 车辆违停占道 10 设备上线 1 设备下线 订阅行业应用告警消息，如明厨亮灶，智慧商企等推送到合作方指定接口地址 订阅行业应用AI消息 AI场景AI消息，将AI场景告警消息推送到合作方指定接口地址 AI消息流 订阅AI场景消息  01 门户入驻流程指引 目 02 接口对接指引 03 操作演示 录 04 问题解答 05 实操环节  操作演示 获取访问令牌 获取设备 直播与云回看 授权登录获取访问令牌（天翼账号，扫码， 目录树（业务树），设备树，行业树（固定 直播流（标准rtsp,转码hls,rtmp,webrtc） 无感知） 业务树）获取树目录结构及设备列表 云回看视频流，云存文件下载，云存剪辑 等 演示视频 演示视频 演示视频  01 门户入驻流程指引 目 02 接口对接指引 03 操作演示 录 04 问题解答 05 实操环节  问题讨论与小结 对接步骤 你觉的对接步骤中那个一步最 重要？说出你的理由 思考 对接流程 天翼视联能力开放的对接流程 复杂吗？你有哪些优化建议 开发者 对接流程中，有哪些注意事项， 不少于5项，并说出你的理由  01 门户入驻流程指引 目 02 接口对接指引 03 操作演示 录 04 问题解答 05 实操环节  实操演练 实操课题： postman完成基础API的对接，包括获取访问令牌，目录树，直播，云回看文档中的所有接口 自定义完成一个前端+后台的小服务 环境准备： 开发环境：以Java语言为例，推荐使用idea、jdk8+以上环境 开发者账号，公网环境 功能要求： 授权登录页面 有目录树页面，可多级展示设备 WEB端内嵌播放器，可进行直播，云回看 加分项： 可视化界面，页面布局与交互设计合理  点评分析 获取访问令牌 10分 获取目录树 10分 基础实践（postman） 获取直播链接 10分 获取云回看直播链接并 10分 下载云回看文件 评分 标准 授权登录页面 10分 有目录树页面，可多级 15分 拓展实践（自定义完成一个前端+后台 展示设备 的小服务） WEB端内嵌播放器，可 20分 进行直播，云回看 可视化界面 15分 37