文档简介：
乘风平台接口文档
版本信息
| 版本号 | 变更时间 | 变更内容 |
|---|---|---|
| v1.0 | 2020.03.01 | 创建接口文档 |
| v1.1 | 2021.04.19 | 增加验签规则 |
| v1.2 | 2021.05.08 | 增加base64头像图片上传接口 |
| v1.3 | 2021.05.10 | 直接下发接口说明更新 |
| v1.4 | 2021.06.03 | 更新接口前缀，增加token获取说明 |
| v1.5 | 2021.06.11 | 增加Postman接口调用示例和接口示例 |
| v1.6 | 2021.06.18 | 识别记录查询和数据推送识别记录，增加三个字段 |
| v1.7 | 2021.06.28 | 格式优化，文字描述优化 |
| v1.8 | 2021.06.30 |
新增人员同步超时重试接口 数据推送模块，新增设备上线推送、新增人员下发失败（含超时）推送 |
| v1.9 | 2021.07.07 | 新增和修改人员接口，当返回错误code 336时，增加额外提示信息：头像被注册的人员id |
| v2.0 | 2021.07.13 |
增加人员直接下发接口组id参数说明 新增和修改人员接口，当返回错误code=336时，提示信息字段返回结构更新 |
| V2.1 | 2021.07.14 |
推送接口新增header【pushType】 人员同步失败类型的推送消息，新增业务方id和设备id |
| V2.2 | 2021.08.02 | 新增创建人员接口，人员不存在即新增人员，人员存在即更新人 |
| V2.3 | 2021.08.23 |
增加心跳类型说明 乘风平台请求推送地址，需要推送地址支持GET和POST请求，并返回规范数据 |
| V2.4 | 2021.11.15 | 更新推送给第三方的字段，Postman验签请求工具更新 |
| V2.5 | 2021.11.24 | 验签图片更新，示例代码信息错误修改，示例代码工程更新 |
| V2.6 | 2022.01.19 |
补全识别记录返回字段，增加识别记录未通行原因、核验方式 postman请求工具优化字符串传空处理，接口示例代码工程代码优化，去除POST请求前组装参数 数据推送-推送识别记录增加通道号 |
| V3.1.2 | 2022.03.10 |
增加视频分析盒子通道和组关联关系查询接口 增加视频分析盒子绑定组查询接口 增加视频分析盒子通道和组关系配置接口 |
一. 前言
(一) 文档说明
本文档为乘风平台对外接口文档，文档分为前言（文档说明、访问限制、接入流程及签名规则、接口调用顺序、返回体数据格式、示例工程）接口详情、错误码、常见问题四部分。其中前言主要是让您更快地接入乘风平台，包括获取请求必须参数，摘要规则，调用接口顺序以及示例工程。接口详情是接口的详细请求和应答信息以及单个请求代码示例。错误码和常见问题，为您调用接口时出现错误而方面快速及时解决。
(二) 访问限制
- 本系统提供的API服务，均定义为HTTP Restful接口。
- 接口格式：所有接口默认使用 application/json，对于需要上传file的接口，使用 multipart/form-data，且会在接口说明里单独标注。
- 请求接口时必须在RequestParam中带有businessSign(签名，即摘要后的字符串)、nonce(随机数)、businessTimestamp(时间戳)。
- 识别记录和告警信息单页返回数据条数范围为1～100。其他分页列表请求，单页返回数据条数范围为1～50，请求参数pageSize超过50将按最大值50条返回。
- qps限制，api接口的qps限制跟用户绑定的设备数目正相关，计算公式为：QPS=2+2×设备绑定数。
(三) 接入流程及签名规则
乘风对外接口是提供给乘风平台的客户，从百度外部网络访问的乘风对外接口。根据相关规范，乘风接口集成在百度智能云平台对外开放。所以调用乘风对外接口需要以下步骤：
1.获取access_token
注册并接入百度智能云平台，接入百度智能云及调用智能云上api的方式请参考百度智能云api接入，从智能云平台注册后取得用户的ak（ API key）和sk（Secret Key）(获取方法：https://console.bce.baidu.com/ai/?_=1622723338765#/ai/face/chengfeng/overview)，然后根据ak和sk获取access_token（获取方法：https://ai.baidu.com/ai-doc/REFERENCE/Ck3dwjhhu），获取access_token之后，在调用接口时要带有access_token才能有效请求。
2. 获取key（验签密钥）
2.1 乘风页面右上角用户信息中，可以看到"验签密钥"选项，点击进入，即可看到账户验签密钥，点击复制即可。
3.构建businessSign(签名)
3.1 签名须知
访问乘风平台接口时还需带有一个乘风平台的签名，即摘要请求体之后获得的字符串，规则如下：由于接入机构系统和百度云系统之间的通信涉及到敏感信息，必须保证通信数据不被篡改和伪造。否则，将给机构和百度云带来一定的风险。百度云系统采用签名机制来保证通信安全。本文中的每个接口规范都包括一个参数：businessSign。businessSign是签名结果。机构请求百度云系统API请求数据时，必须双方约定的签名算法参数进行签名。API会检查对应的签名，如果验证不通过，则说明通信数据已经被篡改或伪造。百度云系统没有使用RSA、DSA等给予非对称密钥的签名算法，而是使用了MD5摘要算法。这些摘要算法本身并不能用作签名，但是结合百度云系统合作密钥，也可以起到签名的作用，进而达到防篡改和伪造的目的。每个接入机构的密钥是唯一的，决不能让第三方知道。如果密钥泄漏，必须及时通知百度云系统团队，更换密钥。
3.2签名规则
签名机制包括拼接待签名数据和对待签名数据进行摘要三个步骤：
- 待签名数据由除businessSign之外的所有请求参数（除3.3中不参与签名字段）和百度云系统合作密钥按以下规则拼接而成：
a) 请求参数都按照名称字符升序排列。（参数名称不允许相同 ）
b) 对于可选参数（接口规范中的非“必须”参数），如果没有上传，则无需参与拼接。若上传，则需要拼接。
c) 将合作密钥作为最后一个参数，参数名为key（请注意，这里的key是乘风平台提供的接入密钥，并非接入百度智能云console时给 的sk），参数值就是平台分配的合作密钥本身，合作密钥（key）的获取参见上一步。
d) 将请求参数按上述顺序用“&”拼接起来。
-
对待签名数据进行MD5摘要
特殊情况：
对于json包含数组：因为不包含key，所以对value进行升序排列，&拼接。
对于json包含数组对象的，先按照相同的规则求对象的md5，然后将md5升序排列，&拼接。
所有参数均采用UTF-8编码进行签名。相同的字符串(包括中文)，如果内部编码格式不同，那么对应的字节流可能也不相同。MD5等摘要算法是对字节流进行操作的。因此，相同字符串的摘要结果未必相同，取决于内部编码。
3.3 注意事项
- 在签名时，如果参数的值包括&、@等特殊字符或中文，这些字符需要保持原样，不要做URL编码。
- 上述规则适用于key:value的简单传输，对于部分接口key:jsonobject的传输，则按照相同的规则递归求jsonObject的md5值，当做key的value拼接。
- 对于value为空或者null的不参与验签
- 由于开放API通过百度云平台对外开放，appid对用户不可见，属于内部系统的透传参数，所以appId不参与验签。
- 文件（multipartFile等类型）或图片（Base64等类型）参数格式特殊，不参与验签。比如，人像上传接口（Base64）中的image字段。
- 除文件（multipartFile等类型）或图片（Base64等类型）参数以外，其他参数一律参与验签。
- MD5采用的是32位小写的
4.参考示例
复杂对象验签实例图：
(四) Postman请求工具和示例工程
1.Postman请求工具（推荐使用，解决验签失败问题）
1.下载Postman文件，点击此处，点击Postman中的Import，导入乘风对外接口和乘风平台OpenApi环境变量。
2.导入之后，打开Environments, 如下图所示，按照图片要求，获取并配置Postman环境变量。
3.验签过程可参考下图，调用接口，即可在在console中查看加密前字符串和加密后MD5：
2. 接口示例代码工程
1.接口示例代码工程与接口详情中每个接口的示例代码同源，示例代码中所需的request文件夹和utils文件夹，都包含在工程之中。
2.下载接口示例代码工程，点击此处。
(五) 接口调用顺序
乘风平台对外接口主要提供人员管理、人员组管理、设备管理、同步管理、时间计划、事件管理（识别记录和告警信息）、事件数据推送的功能。目的是让用户能够将需要识别的人员信息（成员、访客、黑名单）分组和时间计划一并下发到自己的设备上，设备以下发到自身的数据为依据对人员按时间计划进行识别，并将识别记录推送到乘风服务器，乘风平台的页面会对识别信息和设备告警信息进行展示，用户也可以选择让乘风平台推送识别记录和设备告警信息到用户指定的服务器。接口调用顺序主要有以下几种：
1.常规模式（推荐）
1.1 流程
创建人员-->创建人员组-->创建时间计划-->创建同步任务（包括人员组、设备编号以及时间计划）→同步任务下发到设备→设备进行识别并上传识别记录
1.2 说明
常规模式下，用户调用各模块接口分别创建人员、人员组、时间计划（识别设备的识别时间段），可以在人员创建或编辑时关联已创建人员组id，也可以在人员组创建或修改时关联已创建人员id。然后创建同步任务，同步任务包含要下发的设备、人员组（带有组内人员）和时间计划，同步任务会异步的将任务中带有的信息下发到具体设备上。该方式用户可自由创建和管理人员、人员组、时间计划、同步任务，全量或部分使用最细粒度的接口，完成自己需要的人员识别流程，具体流程如下图：
2.快捷模式
2.1流程
通过人员直接添加同步接口填入人员信息、设备信息、时间计划-->系统创建设备默认人员组-->系统创建同步任务（包括人员组、设备编号以及时间计划）→系统将同步任务下发到设备→设备进行识别并上传识别记录
2.2说明
快捷模式下，用户只调用人员直接添加同步接口，提供人员信息、要下发的设备信息、人员识别时间段等信息给到接口，乘风平台会根据这些信息创建人员，并关联一个默认的人员组，将该人员组和用户提供的设备进行关联创建同步任务，并将同步任务数据下发到设备。该调用方法，用户只调用一个直接同步接口，提供信息给接口，剩下的操作由乘风平台自动完成，方便快捷，但是用户对流程的控制相对减弱。具体流程如下图：
(六)返回体的数据格式
| 参数 | 说明 | 数据类型 | 是否必填 | 备注 |
|---|---|---|---|---|
| success | 请求是否成功 | boolean | 是 | true 表示成功； false 表示失败 |
| error_code | 状态码 | Integer | 是 | 0 成功状态码； 3xx 失败状态码； |
| result | 额外信息，具体格式参见各个接口的返回值示例 | json | 否 | 只有当success为 true 时，接口才会返回 result 字段 |
| page | 分页查询接口的额外信息 | json | 否 | 只有是分页查询接口的返回值，且当success为 true 时，接口才会返回 page 字段 |
| error_msg | 失败提示信息 | json对象 | 否 | 只有当success为 false 时，接口才会返回message字段，否则为空字符串 |
