接口文档

更新时间：2022-01-22

乘风平台接口文档

版本信息

版本号	变更时间	变更内容
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请求前组装参数数据推送-推送识别记录增加通道号

一. 前言

(一) 文档说明

本文档为乘风平台对外接口文档，文档分为前言（文档说明、访问限制、接入流程及签名规则、接口调用顺序、返回体数据格式、示例工程）接口详情、错误码、常见问题四部分。其中前言主要是让您更快地接入乘风平台，包括获取请求必须参数，摘要规则，调用接口顺序以及示例工程。接口详情是接口的详细请求和应答信息以及单个请求代码示例。错误码和常见问题，为您调用接口时出现错误而方面快速及时解决。

(二) 访问限制

本系统提供的API服务，均定义为HTTP Restful接口。
接口格式：所有接口默认使用 application/json，对于需要上传file的接口，使用 multipart/form-data，且会在接口说明里单独标注。
请求接口时必须在RequestParam中带有businessSign(签名，即摘要后的字符串)、nonce(随机数)、businessTimestamp(时间戳)。
识别记录和告警信息单页返回数据条数范围为1～100。其他分页列表请求，单页返回数据条数范围为1～50，请求参数pageSize超过50将按最大值50条返回。
qps限制，查询类接口qps限制为10，其他接口qps限制为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字段，否则为空字符串

成功消息示例：

{
    "success":true,
    "error_code":0,
        "error_msg":"",
    "result":{
        "userName":"刘xx",
        "sex":"male",
        "id":"hdjafhak_112"
    }
}

分页查询请求成功消息示例：

{
    "success":true,
    "error_code":0,
        "error_msg":"",
    "page":{
        "pageNo":1,
        "pageSize":10,
        "totalCount":2,
        "result":[
     {...},{...}

        ]
    }
}

失败消息示例：

{
    "success":false,
    "error_code":301,
    "error_msg":{
        "global":"缺少用户名参数"
    }
}

(七)数据推送

在乘风平台页面-系统管理-开放能力-数据推送，进行推送地址配置。
在配置推送地址前，贵方需要保证推送地址支持POST和GET两种请求，并返回规范正确的响应信息。规范的响应信息参见本文档，二.接口详情--(六)数据推送--1.1.4 返回字段说明。
配置完成后，二.接口详情--(六)数据推送的信息将推送到该地址。

二. 接口详情

接口公共字段

json请求与表单请求均必传

字段	含义	备注
nonce	用户生成的随机数
businessTimestamp	用户请求的时间戳
businessSign	当前请求的签名数据	签名规则参考『上文』

(一) 人员API

1 人员管理

1.1 添加人员

1.1.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/add

Method: post

接口描述: 添加人员接口，可添加成员、访客、黑名单

1.1.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
name	人员姓名（限长40，超过长度部分会被截去）	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
groupIdList	人员组id	String数组	否
memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+sex	性别。（添加成员时可填）可选值 "male" "female"（注意：其他非可选值一律认为是未知性别）	String	否
+internalNum	成员编号（添加成员时可填）	String	否
+cardId	卡号（添加成员时可填）	String	否
+passWord	密码（添加成员时可填）	String	否
+entryDate	入职日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
+birthDate	出生日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+startTime	到访起始时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+endTime	到访结束时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+purpose	来访目的（添加访客时可填）	String	否
+receiveMemId	受访人员id（添加访客时可填），该字段必须传乘风平台人员id	String	否
+expiredClearFlag	访客过期清除标志（只有两种值 0：不清除; 1：清除）	Integer	否
phoneNum	手机号（成员字段）	String	否
email	邮箱	String	否
backUp	备注（访客没有）	String	否
hint	自定义提示语	String	否
avatar	注册照的key，图片通过上传接口上传后取得	String	否
showAvatar	展示照的key，图片通过上传接口上传后取得	String	否
customPersonId	开放接口用户方的人员ID（限长50）（请确保该字段唯一性，否则可能导致不能根据该字段进行查询）	String	否
customExtends	开放接口用户扩展字段（限长200）	String	否

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.request.GuestDetail;
import com.baidu.demo.request.MemberDetail;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.PersonAddRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

public class PersonAdd {
    /**
     * request,utils文件夹请从接口文档中下载
     *
     */
    public static void personAdd() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String name = "小明";
        Integer personType = 1;
        String groupId = "测试人员组";
        String sex = "male";
        String internalNum = "45678977";
        String cardId = "123478";
        String passWord = "12453";
        String entryDate = "2021-06-10";
        String birthDate = "1995-06-10";
        String company = "某公司";
        String position = "某职位";
        String startTime = "2021-06-17T08:00:00Z";
        String endTime = "2021-06-17T18:00:00Z";
        String purpose = "访问";
        String receiveMemId = "MEM_815265821110_1032";
        String phoneNum = "13290606065";
        String email = "13290606065@163.com";
        String backUp = "backUp";
        String hint = "欢迎您";
        // 调用人像上传返回参数的key,不是filePath
        String avatar = "153ef41326ee45b413db762795967dac";
        // 调用人像上传返回参数的key,不是filePath
        String showAvatar = "153ef41326ee45b413db762795967dac";
        String customPersonId = "cd12321423";
        String customExtends = "123456";
        // 2.签名
        PersonAddRequest personAddRequest =  PersonAddRequest.builder()
                .name(name)
                .personType(personType)
                .groupIdList(new String[]{groupId})
                .memberDetail(MemberDetail.builder()
                        .sex(sex)
                        .internalNum(internalNum)
                        .cardId(cardId)
                        .passWord(passWord)
                        .entryDate(entryDate)
                        .birthDate(birthDate)
                        .company(company)
                        .position(position)
                        .build())
                .guestDetail(GuestDetail.builder()
                        .startTime(startTime)
                        .endTime(endTime)
                        .purpose(purpose)
                        .receiveMemId(receiveMemId)
                        .build())
                .phoneNum(phoneNum)
                .email(email)
                .backUp(backUp)
                .hint(hint)
                .avatar(avatar)
                .showAvatar(showAvatar)
                .customPersonId(customPersonId)
                .customExtends(customExtends)
                .build();
        OpenAPIRequest sign = SignUtil.sign(personAddRequest, key);
        // 3.转化参数
        String param = GsonUtils.toJson(sign);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/add?access_token="+ accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        PersonAdd.personAdd();
    }
}

1.1.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",（限长40，超过长度部分会被截去）
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{      （该对象仅成员返回） 
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{ （该对象仅访客返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判",（访客字段）
        "expiredClearFlag":0
        },
        "phoneNum":"17221614782",（成员字段）
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":""
    }
}

Error Response Example

{
    "success":false,
    "error_code":336,
    "error_msg":{
        "global": "头像已被人员 MEM_12345_1 注册"
    },
    "result":{
        "existPersonId": "MEM_12345_1",   
        "existCustomPersonId": "111111"
    }
}

1.1.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
+existPersonId	失败提示额外信息，头像已被注册的人员id（只有当error_code为336时，接口才会返回existPersonId字段）	String	否
+existCustomPersonId	失败提示额外信息，头像已被注册的人员的用户方人员ID（只有当error_code为336时，接口才会返回existCustomPersonId字段）	String	否
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）（注意：其他非可选值一律认为是未知性别）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号（成员字段）	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String

1.2 人员列表（分页）

1.2.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/pageable

Method: get

接口描述: 人员列表查询

1.2.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
idType	请求路径参数id类型（默认1） 1、乘风人员id 2、客户方人员id	Integer	是
name	人员姓名	String	否
groupId	人员组id	String	否
idList	人员id列表。格式为使用“,” (英文逗号) 拼接的字符串	String	否
pageNo	页码，大于等于1。默认为1	Integer	否
pageSize	页大小，默认为10（取值范围1～50）	Integer	否

Body

参数名	说明	数据类型	是否必填

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.TreeMap;
import java.util.UUID;

public class PersonPageable {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personPageable() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间，客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        Integer personType = 1;
        Integer idType = 1;
        Integer pageNo =  1;
        Integer pageSize =  10;
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("personType", personType);
        map.put("idType", idType);
        map.put("pageNo", pageNo);
        map.put("pageSize", pageSize);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("businessSign", businessSign);
        map.put("access_token", accessToken);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/pageable";
        String result = HttpUtil.get(map, url);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args) {
        PersonPageable.personPageable();
    }
}

1.2.3 返回数据

Response

{
    "success":true,
    "error_code":0,
        "error_msg": ""，
    "page":{
        "pageNo":1,
        "pageSize":10,
        "totalCount":2,
        "hasMore":true,
        "totalAvatarCount":1,
        "result":[
     {
         "name":"刘xx",
                    "personType" : 1,
         "groupList":[
             {
                                     "groupId":"id_1",
                                     "groupName":"name_1"
             }
         ],
           "memberDetail":{ （该对象仅成员返回）
                    "sex":"male",（成员字段）（注意：其他非可选值一律认为是未知性别）
                    "internalNum":"B00",（成员字段）
                    "cardId":"3278957248935789",（成员字段）
                   "passWord":"199010",（成员字段）
                    "entryDate":"2020-10-28",（成员字段）
                    "birthDate":"1990-10-18"（成员字段）
           },
        "guestDetail":{（该对象仅访客返回）
            "startTime":"2020-10-28T10:00:00Z",（访客字段）
           "endTime":"2020-10-28T12:00:00Z",（访客字段）
           "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
            "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
           "purpose":"商务谈判",（访客字段）
           "expiredClearFlag":0 （访客字段）
            },
                    "phoneNum":"17221614782",（成员字段）
         "email":"liu@baidu.com",
         "backUp":"无备注",（访客没有）
         "hint":"欢迎光临",
         "avatar":"967624519a0f.jpg",
         "avatarPath":"http://XXXX/967624519a0f.jpg",
         "showAvatar":"967624519a0f.jpg",
         "showAvatarPath":"http://XXXX/967624519a0f.jpg",
                    "appId": "807949663664",
         "createTime":"2019-07-22T04:08:54Z",
         "id":"hdjafhak_112",
             "customPersonId":"customPerson1371",
             "customExtends":""
     },
          { ... }
        ]
    }
}

1.2.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
page	page对象	map	是
+pageNo	页码	Integer	是
+pageSize	页大小	Integer	是
+totalCount	总条数	Integer	是
+hasMore	是否还有更多数据	boolean	是
+totalAvatarCount	带头像数据条数	Long
+result	结果详情描述	list	是
++name	人员姓名	String
++personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
++groupList	成员组实体数组	实体数组
++memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+++sex	性别。（成员字段）（注意：其他非可选值一律认为是未知性别）可选值 "male" "female"	String
+++internalNum	成员编号（成员字段）	String
+++cardId	卡号（成员字段）	String
+++passWord	密码（成员字段）	String
+++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
+++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
++guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
+++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
+++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
+++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
+++purpose	来访目的（访客字段）	String
+++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
++phoneNum	手机号（成员字段）	String	否
++email	邮箱	String
++backUp	备注（访客没有）	String
++hint	自定义提示语	String
++avatar	注册照的key，图片通过上传接口上传后取得	String
++showAvatar	展示照的key，图片通过上传接口上传后取得	String
++avatarPath	注册照的路径，图片通过上传接口上传后取得	String
++showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
++appId	应用id	String
++createTime	创建时间（UTC时间）	Date
++id	人员ID	String
++customPersonId	开放接口用户方的人员ID（限长50）	String
++customExtends	开放接口用户扩展字段（限长200）	String

1.3 人员详情

1.3.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/detail

Method: get

接口描述: 查询人员的详情，按人员类型参数区分

1.3.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
id	人员的唯一标识	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
idType	请求路径参数id类型（默认1） 1、乘风人员id 2、客户方人员id	Integer	是

Body

参数名	说明	数据类型	是否必填

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.TreeMap;
import java.util.UUID;

public class PersonDetail {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personDetail() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间，客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String id =  "MEM_815265821110_1032";
        String personType =  "1";
        String idType =  "1";
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("id", id);
        map.put("personType", personType);
        map.put("idType", idType);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("businessSign", businessSign);
        map.put("access_token", accessToken);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/detail";
        String result = HttpUtil.get(map, url);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args) {
        PersonDetail.personDetail();
    }

}

1.3.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{       （该对象仅成员返回）
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{    （该对象仅成员返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判",（访客字段）
        "expiredClearFlag":0（访客字段）
        },
        "phoneNum":"17221614782",（成员字段）
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":""
    }
}

1.3.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号（成员字段）	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String

1.4 修改人员

1.4.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/update

Method: post

接口描述: 修改人员，按人员类型参数区分

1.4.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
id	人员的唯一标识	String	是

Body

参数名	说明	数据类型	是否必填
name	姓名（限长40，超过长度部分会被截去）	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
idType	请求路径参数id类型（默认1） 1、乘风人员id 2、客户方人员id	Integer	是
groupIdList	人员组id	String数组	否
memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+sex	性别。（添加成员时可填）（注意：其他非可选值一律认为是未知性别）可选值 "male" "female"	String	否
+internalNum	成员编号（添加成员时可填）	String	否
+cardId	卡号（添加成员时可填）	String	否
+passWord	密码（添加成员时可填）	String	否
+entryDate	入职日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
+birthDate	出生日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+startTime	到访起始时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+endTime	到访结束时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+purpose	来访目的（添加访客时可填）	String	否
+receiveMemId	受访人员id（添加访客时可填），该字段必须传乘风平台人员id	String	否
+expiredClearFlag	访客过期清除标志（只有两种值 0：不清除; 1：清除）	Integer	否
phoneNum	手机号（成员字段）	String	否
email	邮箱	String	否
backUp	备注（访客没有）	String	否
hint	自定义提示语	String	否
avatar	注册照的key，图片通过上传接口上传后取得	String	否
showAvatar	展示照的key，图片通过上传接口上传后取得	String	否
customPersonId	开放接口用户方的人员ID（限长50）（请确保该字段唯一性，否则可能导致不能根据该字段进行查询）	String	否
customExtends	开放接口用户扩展字段（限长200）	String	否

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.request.GuestDetail;
import com.baidu.demo.request.MemberDetail;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.PersonAddRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.HashMap;
import java.util.Map;

public class PersonUpdate {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personUpdate() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String id = "MEM_815265821110_76882";
        Integer idType = 1;
        String name = "新小明";
        Integer personType = 1;
        String groupId = "测试人员组";
        String sex = "male";
        String internalNum = "45678977";
        String cardId = "123478";
        String passWord = "12453";
        String entryDate = "2021-06-10";
        String birthDate = "1995-06-10";
        String company = "某公司";
        String position = "某职位";
        String startTime = "2021-06-17T08:00:00Z";
        String endTime = "2021-06-17T18:00:00Z";
        String purpose = "访问";
        String receiveMemId = "MEM_815265821110_1032";
        String phoneNum = "13290606065";
        String email = "13290606065@163.com";
        String backUp = "backUp";
        String hint = "欢迎您";
        // 调用人像上传返回参数的key,不是filePath
        String avatar = "153ef41326ee45b413db762795967dac";
        // 调用人像上传返回参数的key,不是filePath
        String showAvatar = "153ef41326ee45b413db762795967dac";
        String customPersonId = "cd12321423";
        String customExtends = "123456";
        // 2.签名
        PersonAddRequest personUpdateRequest =  PersonAddRequest.builder()
                .name(name)
                .personType(personType)
                .groupIdList(new String[]{groupId})
                .idType(idType)
                .memberDetail(MemberDetail.builder()
                        .sex(sex)
                        .internalNum(internalNum)
                        .cardId(cardId)
                        .passWord(passWord)
                        .entryDate(entryDate)
                        .birthDate(birthDate)
                        .company(company)
                        .position(position)
                        .build())
                .guestDetail(GuestDetail.builder()
                        .startTime(startTime)
                        .endTime(endTime)
                        .purpose(purpose)
                        .receiveMemId(receiveMemId)
                        .build())
                .phoneNum(phoneNum)
                .email(email)
                .backUp(backUp)
                .hint(hint)
                .avatar(avatar)
                .showAvatar(showAvatar)
                .customPersonId(customPersonId)
                .customExtends(customExtends)
                .build();
        Map<String, String> personUpdateParams = new HashMap<>();
        personUpdateParams.put("id" , id) ;
        OpenAPIRequest sign = SignUtil.sign(personUpdateRequest, personUpdateParams, key);
        // 3.转化参数
        String param = GsonUtils.toJson(sign);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/update?access_token="+ accessToken +"&id="+ id;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args) {
        PersonUpdate.personUpdate();
    }
}

1.4.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",（限长40，超过长度部分会被截去）
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{       （该对象仅成员返回） 
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{    （该对象仅访客返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判",（访客字段）
        "expiredClearFlag":0（访客字段）
        },
        "phoneNum":"17221614782",
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":""
    }
}

Error Response Example

{
    "success":false,
    "error_code":336,
    "error_msg":{
        "global": "头像已被人员 MEM_12345_1 注册"
    },
    "result":{
        "existPersonId": "MEM_12345_1",
        "existCustomPersonId": "111111"
    }
}

1.4.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
+existPersonId	失败提示额外信息，头像已被注册的人员id（只有当error_code为336时，接口才会返回existPersonId字段）	String	否
+existCustomPersonId	失败提示额外信息，头像已被注册的人员的用户方人员ID（只有当error_code为336时，接口才会返回existCustomPersonId字段）	String	否
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号（成员字段）	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String

1.5 删除人员

1.5.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/delete

Method: post

接口描述: 批量删除人员的接口，可以批量删除成员、访客、黑名单，但一次只能删除一种人员，按人员类型参数区分

1.5.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
idList	人员id数组	String数组	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
idType	请求路径参数id类型（默认1） 1、乘风人员id 2、客户方人员id	Integer	是

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.PersonDelRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.TreeMap;

public class PersonDelete {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupDelete() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String[] idList = {"MEM_815265821110_1038"};
        Integer personType = 1;
        Integer idType = 1;
        // 2.签名
        PersonDelRequest groupAdd = PersonDelRequest.builder()
                .idList(idList)
                .personType(personType)
                .idType(idType)
                .build();
        OpenAPIRequest sign = SignUtil.sign(groupAdd, key);
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("idList", idList);
        map.put("personType", personType);
        map.put("idType", idType);
        map.put("businessTimestamp", sign.getBusinessTimestamp());
        map.put("nonce", sign.getNonce());
        map.put("businessSign", sign.getBusinessSign());
        String param = GsonUtils.toJson(map);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/delete?access_token=" + accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: " + result);
    }

    public static void main(String[] args){
        PersonDelete.groupDelete();
    }
}

1.5.3 返回数据

Response

{
    "success":true,
    "error_code":0,
         "error_msg": ""，
    "result":{
        "successIdList":[
            "fsdafa1","dsafdas2"
        ],
        "failIdList":[
            "fsdafa3"
        ]
    }
}

1.5.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+successIdList	删除成功ID列表	字符串数组	是
+failIdList	删除失败ID列表	字符串数组	是

1.6 创建人员

1.6.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/create

Method: post

接口描述: 人员不存在即添加（调用添加人员接口），存在即更新（调用人员更新），具体响应信息取决于是调用添加还是更新接口。

1.6.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
id	乘风人员id（不可传客户方人员id）	String	否

Body

参数名	说明	数据类型	是否必填
name	姓名（限长40，超过长度部分会被截去）	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
groupIdList	人员组id	String数组	否
memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+sex	性别。（添加成员时可填）（注意：其他非可选值一律认为是未知性别）可选值 "male" "female"	String	否
+internalNum	成员编号（添加成员时可填）	String	否
+cardId	卡号（添加成员时可填）	String	否
+passWord	密码（添加成员时可填）	String	否
+entryDate	入职日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
+birthDate	出生日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+startTime	到访起始时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+endTime	到访结束时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+purpose	来访目的（添加访客时可填）	String	否
+receiveMemId	受访人员id（添加访客时可填），该字段必须传乘风平台人员id	String	否
+expiredClearFlag	访客过期清除标志（只有两种值 0：不清除; 1：清除）	Integer	否
phoneNum	手机号（成员字段）	String	否
email	邮箱	String	否
backUp	备注（访客没有）	String	否
hint	自定义提示语	String	否
avatar	注册照的key，图片通过上传接口上传后取得	String	否
showAvatar	展示照的key，图片通过上传接口上传后取得	String	否
customPersonId	开放接口用户方的人员ID（限长50），即客户方人员id（请确保该字段唯一性，否则可能导致不能根据该字段进行查询）	String	否
customExtends	开放接口用户扩展字段（限长200）	String	否

示例代码

package com.baidu.demo.test.person;

import com.baidu.demo.request.GuestDetail;
import com.baidu.demo.request.MemberDetail;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.PersonAddRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.HashMap;
import java.util.Map;

public class PersonCreate {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personCreate() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String id = "MEM_815265821110_81793";
        String name = "新小明";
        Integer personType = 1;
        String groupId = "测试人员组";
        String sex = "male";
        String internalNum = "45678977";
        String cardId = "123478";
        String passWord = "12453";
        String entryDate = "2021-06-10";
        String birthDate = "1995-06-10";
        String company = "某公司";
        String position = "某职位";
        String startTime = "2021-06-17T08:00:00Z";
        String endTime = "2021-06-17T18:00:00Z";
        String purpose = "访问";
        String receiveMemId = "MEM_815265821110_1032";
        String phoneNum = "13290606065";
        String email = "13290606065@163.com";
        String backUp = "backUp";
        String hint = "欢迎您";
        // 调用人像上传返回参数的key,不是filePath
        String avatar = "153ef41326ee45b413db762795967dac";
        // 调用人像上传返回参数的key,不是filePath
        String showAvatar = "153ef41326ee45b413db762795967dac";
        String customPersonId = "cd12321423";
        String customExtends = "123456";
        // 2.签名
        PersonAddRequest personUpdateRequest =  PersonAddRequest.builder()
                .name(name)
                .personType(personType)
                .groupIdList(new String[]{groupId})
                .memberDetail(MemberDetail.builder()
                        .sex(sex)
                        .internalNum(internalNum)
                        .cardId(cardId)
                        .passWord(passWord)
                        .entryDate(entryDate)
                        .birthDate(birthDate)
                        .company(company)
                        .position(position)
                        .build())
                .guestDetail(GuestDetail.builder()
                        .startTime(startTime)
                        .endTime(endTime)
                        .purpose(purpose)
                        .receiveMemId(receiveMemId)
                        .build())
                .phoneNum(phoneNum)
                .email(email)
                .backUp(backUp)
                .hint(hint)
                .avatar(avatar)
                .showAvatar(showAvatar)
                .customPersonId(customPersonId)
                .customExtends(customExtends)
                .build();
        Map<String, String> personUpdateParams = new HashMap<>();
        personUpdateParams.put("id" , id) ;
        OpenAPIRequest sign = SignUtil.sign(personUpdateRequest, personUpdateParams, key);
        // 3.转化参数
        String param = GsonUtils.toJson(sign);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/create?access_token="
                + accessToken +"&id="+ id;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        PersonCreate.personCreate();
    }
}

1.6.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",（限长40，超过长度部分会被截去）
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{       （该对象仅成员返回） 
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{    （该对象仅访客返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判",（访客字段）
        "expiredClearFlag":0（访客字段）
        },
        "phoneNum":"17221614782",
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":""
    }
}

Error Response Example

{
    "success":false,
    "error_code":336,
    "error_msg":{
        "global": "头像已被人员 MEM_12345_1 注册"
    },
    "result":{
        "existPersonId": "MEM_12345_1",
        "existCustomPersonId": "111111"
    }
}

1.5.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
+existPersonId	失败提示额外信息，头像已被注册的人员id（只有当error_code为336时，接口才会返回existPersonId字段）	String	否
+existCustomPersonId	失败提示额外信息，头像已被注册的人员的用户方人员ID（只有当error_code为336时，接口才会返回existCustomPersonId字段）	String	否
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号（成员字段）	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String

2 人员头像管理

2.1 人像上传

2.1.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/file/image/avatar

Method: post

接口描述: 注册照人像上传接口，返回人像访问路径和人像key

2.1.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	multipart/form-data	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
file	上传文件	MultipartFile	是
needVerify	是否需要人像校验，默认为 true。上传人员注册照时，请使用true，展示照使用false	boolean	否

示例代码

package com.baidu.demo.test.person.image;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.io.File;
import java.util.TreeMap;
import java.util.UUID;

public class PersonFileImageAvatar {

    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personFileImageAvatar(){
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        // 您需要上传的照片的路径
        String pathName = "src/main/resources/63e6fd01gy1gi002sl62nj23dw4fe1kz.jpg";
        Boolean needVerify =  true;
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("needVerify", needVerify);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("businessSign", businessSign);
        map.put("access_token", accessToken);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/file/image/avatar?access_token="+accessToken;
        String result = HttpUtil.uploadFile(url, new File(pathName), map);
        // 5.获取结果
        System.out.println(result);
    }

    public static void main(String[] args) throws Exception {
        PersonFileImageAvatar.personFileImageAvatar();
    }
}

2.1.3 返回数据

Response

{
    "success":true,
    "error_code":0,
        "error_msg": ""，
    "result":{
        "key":"image1",
        "filePath":"http://xxxx/image1"
    }
}

2.1.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+key	注册照的key	String
+filePath	图片的url	String

2.2 人像上传（base64）

2.2.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/base64/image/avatar

Method: post

接口描述: 注册照人像(base64格式)上传接口，返回人像访问路径和人像key

2.2.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
image	上传文件(base64)	String	是
needVerify	是否需要人像校验，默认为 true。上传人员注册照时，请使用true，展示照使用false	boolean	否

示例代码

package com.baidu.demo.test.person.image;

import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.Base64;
import java.util.TreeMap;
import java.util.UUID;

public class PersonBase64ImageAvatar {
    /**
     * @Title: GetImageStrFromPath
     * @Description: TODO(将一张本地图片转化成Base64字符串)
     * @param imgPath
     * @return
     */
    private static String GetImageStrFromPath(String imgPath) {
        InputStream in = null;
        byte[] data = null;
        // 读取图片字节数组
        try {
            in = new FileInputStream(imgPath);
            data = new byte[in.available()];
            in.read(data);
            in.close();
        } catch (IOException e) {
            e.printStackTrace();
        }
        // 对字节数组Base64编码
        // 返回Base64编码过的字节数组字符串
        return Base64.getEncoder().encodeToString(data);
    }
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void personBase64ImageAvatar(){
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        // 图片的地址
        String imagePath = "src/main/resources/63e6fd01gy1gi002sl62nj23dw4fe1kz.jpg";
        String base64Image = GetImageStrFromPath(imagePath);
        String image = base64Image;
        Boolean needVerify =  true;
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("needVerify", needVerify);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("image", image);
        map.put("businessSign", businessSign);
        String param = GsonUtils.toJson(map);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/base64/image/avatar?access_token="+accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println(result);
    }

    public static void main(String[] args) throws Exception {
        PersonBase64ImageAvatar.personBase64ImageAvatar();
    }
}

2.2.3 返回数据

Response

{
    "success":true,
    "error_code":0,
        "error_msg": ""，
    "result":{
        "key":"image1",
        "filePath":"http://xxxx/image1"
    }
}

2.2.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+key	注册照的key	String
+filePath	图片的url	String

3 人员直接同步

3.1 人员直接添加同步接口

3.1.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/issued/relate/add

Method: post

接口描述: 添加人员到设备组，并将人员与时间计划共同下发到设备

3.1.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
name	人员姓名（限长40，超过长度部分会被截去）	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
groups	人员组列表（数组限长2。如果传了groups，则groups会和deviceIds对应的设备产生关联，进而人员信息不仅会下发到deviceIds（设备号列表）对应的设备，也会下发到组原先关联的设备上。）	对象数组	否
+groupId	组id（传递人员组时必填）	String	是
+groupName	组名（传递人员组时必填）	String	是
memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+sex	性别。（添加成员时可填）可选值 "male" "female"	String	否
+internalNum	成员编号（添加成员时可填）	String	否
+cardId	卡号（添加成员时可填）	String	否
+passWord	密码（添加成员时可填）	String	否
+entryDate	入职日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
+birthDate	出生日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+startTime	到访起始时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+endTime	到访结束时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+purpose	来访目的（添加访客时可填）	String	否
+receiveMemId	受访人员id（添加访客时可填），该字段必须传乘风平台人员id	String	否
+expiredClearFlag	访客过期清除标志（只有两种值 0：不清除; 1：清除）	Integer	否
phoneNum	手机号	String	否
email	邮箱	String	否
backUp	备注（访客没有）	String	否
hint	自定义提示语	String	否
avatar	注册照的key，图片通过上传接口上传后取得	String	否
showAvatar	展示照的key，图片通过上传接口上传后取得	String	否
customPersonId	开放接口用户方的人员ID（限长50）（请确保该字段唯一性，否则可能导致不能根据该字段进行查询）	String	否
customExtends	开放接口用户扩展字段（限长200）	String	否
deviceIds	设备号列表（数组限长10，仅有效设备id可以被下发）	string数组	是
periods	时段列表（每人最多三个时间段）	list	是
+startTime	时段开始时间（例如："00:00"，注意小时的取值范围是0-23，分的取值范围是0-59）	Date	是
+endTime	时段结束时间（例如："00:00"，注意小时的取值范围是0-23，分的取值范围是0-59）	Date	是

示例代码

package com.baidu.demo.test.person.issued;

import com.alibaba.fastjson.JSONObject;
import com.baidu.demo.request.Group;
import com.baidu.demo.request.GuestDetail;
import com.baidu.demo.request.MemberDetail;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.Period;
import com.baidu.demo.request.PersonAddRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.ArrayList;
import java.util.List;
import java.util.TreeMap;

public class PersonIssuedRelateAdd {
    /**
     * request,utils文件夹请从接口文档中下载
     *
     */
    public static void personIssuedRelateAdd() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String name = "小明";
        Integer personType = 1;
        String groupId = "MEM_815265821110_68";
        String groupName = "测试人员组";
        String sex = "女";
        String internalNum = "45678977";
        String cardId = "123478";
        String passWord = "12453";
        String entryDate = "2021-06-10";
        String birthDate = "1995-06-10";
        String company = "某公司";
        String position = "某职位";
        String startTime = "2021-06-17T08:00:00Z";
        String endTime = "2021-06-17T18:00:00Z";
        String purpose = "访问";
        String receiveMemId = "MEM_815265821110_1032";
        String phoneNum = "13290606065";
        String email = "13290606065@163.com";
        String backUp = "backUp";
        String hint = "欢迎您";
        // 调用人像上传返回参数的key,不是filePath
        String avatar = "153ef41326ee45b413db762795967dac";
        // 调用人像上传返回参数的key,不是filePath
        String showAvatar = "153ef41326ee45b413db762795967dac";
        String customPersonId = "cd123214234";
        String customExtends = "123456";
        String[] deviceIds = {"DMCM020MYC21A00082"};
        List<Period> periods = new ArrayList<>() ;
        periods.add(Period.builder()
                .startTime("00:00")
                .endTime("10:00")
                .build()) ;
        periods.add(Period.builder()
                .startTime("19:00")
                .endTime("20:00")
                .build()) ;
        // 2.签名
        PersonAddRequest personAddRequest =  PersonAddRequest.builder()
                .name(name)
                .personType(personType)
                .groups(new Group[]{Group.builder().groupId(groupId).groupName(groupName).build()})
                .memberDetail(MemberDetail.builder()
                        .sex(sex)
                        .internalNum(internalNum)
                        .cardId(cardId)
                        .passWord(passWord)
                        .entryDate(entryDate)
                        .birthDate(birthDate)
                        .company(company)
                        .position(position)
                        .build())
                .guestDetail(GuestDetail.builder()
                        .startTime(startTime)
                        .endTime(endTime)
                        .purpose(purpose)
                        .receiveMemId(receiveMemId)
                        .build())
                .phoneNum(phoneNum)
                .email(email)
                .backUp(backUp)
                .hint(hint)
                .avatar(avatar)
                .showAvatar(showAvatar)
                .customPersonId(customPersonId)
                .customExtends(customExtends)
                .deviceIds(deviceIds)
                .periods(periods)
                .build();
        OpenAPIRequest sign = SignUtil.sign(personAddRequest, key);
        // 2.组装参数
        TreeMap map = JSONObject.parseObject(JSONObject.toJSONString(personAddRequest), TreeMap.class);
        map.put("businessTimestamp", sign.getBusinessTimestamp());
        map.put("nonce", sign.getNonce());
        map.put("businessSign",sign.getBusinessSign());
        String param = GsonUtils.toJson(map);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/add?access_token="+ accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        PersonIssuedRelateAdd.personIssuedRelateAdd();
    }
}

3.1.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{      （该对象仅成员返回） 
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{ （该对象仅访客返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判",（访客字段）
        "expiredClearFlag": 0
        },
        "phoneNum":"17221614782",
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":"",
        "deviceIds": [
            "chengfeng-test-android-demo",
            "DMCM000BLC21A00006"
        ],
        "syncIds": [
            "SYNC_87902196c37d4a078cb768eb554a56d5",
            "SYNC_06bb413a6b754a9ebb3b54b6ed265e0c"
        ]
    }
}

Error Response Example

{
    "success":false,
    "error_code":336,
    "error_msg":{
        "global": "头像已被人员 MEM_12345_1 注册"
    },
    "result":{
        "existPersonId": "MEM_12345_1",
        "existCustomPersonId": "111111"
    }
}

3.1.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String
+deviceIds	设备号列表	string数组
+syncIds	同步任务id列表	string数组

3.2 人员直接更新同步接口

3.2.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/issued/relate/update

Method: post

接口描述: 更新人员信息，并将人员与时间计划共同下发到设备

3.2.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
id	人员的唯一标识	String	是

Body

参数名	说明	数据类型	是否必填
name	人员姓名（限长40，超过长度部分会被截去）	String	是
personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
idType	请求路径参数id类型（默认1） 1、乘风人员id 2、客户方人员id	Integer	是
groups	人员组列表（数组限长2。如果传了groups，则groups会和deviceIds对应的设备产生关联，进而人员信息不仅会下发到deviceIds（设备号列表）对应的设备，也会下发到组原先关联的设备上。）	对象数组	否
+groupId	组id（传递人员组时必填）	String	是
+groupName	组名（传递人员组时必填）	String	是
memberDetail	成员详情（添加成员需要加传该对象）	Object	否
+sex	性别。（添加成员时可填）可选值 "male" "female"	String	否
+internalNum	成员编号（添加成员时可填）	String	否
+cardId	卡号（添加成员时可填）	String	否
+passWord	密码（添加成员时可填）	String	否
+entryDate	入职日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
+birthDate	出生日期，格式为 "yyyy-MM-dd"（添加成员时可填）	String	否
guestDetail	访客详情（添加访客需要加传该对象）	Object	否
+startTime	到访起始时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+endTime	到访结束时间（添加访客时必填），UTC时间，格式 yyyy-MM-dd'T'HH:mm:ss'Z'	String	是
+purpose	来访目的（添加访客时可填）	String	否
+receiveMemId	受访人员id（添加访客时可填），该字段必须传乘风平台人员id	String	否
+expiredClearFlag	访客过期清除标志（只有两种值 0：不清除; 1：清除）	Integer	否
phoneNum	手机号	String	否
email	邮箱	String	否
backUp	备注（访客没有）	String	否
hint	自定义提示语	String	否
avatar	注册照的key，图片通过上传接口上传后取得	String	否
showAvatar	展示照的key，图片通过上传接口上传后取得	String	否
customPersonId	开放接口用户方的人员ID（限长50）（请确保该字段唯一性，否则可能导致不能根据该字段进行查询）	String	否
customExtends	开放接口用户扩展字段（限长200）	String	否
deviceIds	设备号列表（数组限长10，仅有效设备id可以被下发）	string数组	是
periods	时段列表（每人最多三个时间段）	list	是
+startTime	时段开始时间（例如："00:00"，注意小时的取值范围是0-23，分的取值范围是0-59）	Date	是
+endTime	时段结束时间（例如："00:00"，注意小时的取值范围是0-23，分的取值范围是0-59）	Date	是

示例代码

package com.baidu.demo.test.person.issued;

import com.alibaba.fastjson.JSONObject;
import com.baidu.demo.request.Group;
import com.baidu.demo.request.GuestDetail;
import com.baidu.demo.request.IssuedUpdateRequest;
import com.baidu.demo.request.MemberDetail;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.request.Period;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;

public class PersonIssuedRelateUpdate {
    /**
     * request,utils文件夹请从接口文档中下载
     *
     */
    public static void personIssuedRelateUpdate() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String id = "MEM_815265821110_1354";
        String name = "小明";
        Integer personType = 1;
        Integer idType = 1;
        String groupId = "MEM_815265821110_68";
        String groupName = "测试人员组";
        String sex = "男";
        String internalNum = "45678977";
        String cardId = "123478";
        String passWord = "12453";
        String entryDate = "2021-06-10";
        String birthDate = "1995-06-10";
        String company = "某公司";
        String position = "某职位";
        String startTime = "2021-06-17T08:00:00Z";
        String endTime = "2021-06-17T18:00:00Z";
        String purpose = "访问";
        String receiveMemId = "MEM_815265821110_1032";
        String phoneNum = "13290606065";
        String email = "13290606065@163.com";
        String backUp = "backUp";
        String hint = "欢迎您";
        // 调用人像上传返回参数的key,不是filePath
        String avatar = "153ef41326ee45b413db762795967dac";
        // 调用人像上传返回参数的key,不是filePath
        String showAvatar = "153ef41326ee45b413db762795967dac";
        String customPersonId = "cd123214234";
        String customExtends = "123456";
        String[] deviceIds = {"DMCM020MYC21A00082"};
        List<Period> periods = new ArrayList<>() ;
        periods.add(Period.builder()
                .startTime("00:00")
                .endTime("11:00")
                .build()) ;
        periods.add(Period.builder()
                .startTime("19:00")
                .endTime("20:00")
                .build()) ;
        // 2.签名
        IssuedUpdateRequest personAddRequest =  IssuedUpdateRequest.builder()
                .name(name)
                .idType(idType)
                .personType(personType)
                .groups(new Group[]{Group.builder().groupId(groupId).groupName(groupName).build()})
                .memberDetail(MemberDetail.builder()
                        .sex(sex)
                        .internalNum(internalNum)
                        .cardId(cardId)
                        .passWord(passWord)
                        .entryDate(entryDate)
                        .birthDate(birthDate)
                        .company(company)
                        .position(position)
                        .build())
                .guestDetail(GuestDetail.builder()
                        .startTime(startTime)
                        .endTime(endTime)
                        .purpose(purpose)
                        .receiveMemId(receiveMemId)
                        .build())
                .phoneNum(phoneNum)
                .email(email)
                .backUp(backUp)
                .hint(hint)
                .avatar(avatar)
                .showAvatar(showAvatar)
                .customPersonId(customPersonId)
                .customExtends(customExtends)
                .deviceIds(deviceIds)
                .periods(periods)
                .build();
        Map<String, String> issuedRelateParams = new HashMap<>() ;
        issuedRelateParams.put("id" , id) ;
        OpenAPIRequest sign = SignUtil.sign(personAddRequest, issuedRelateParams, key);
        // 2.组装参数
        TreeMap map = JSONObject.parseObject(JSONObject.toJSONString(personAddRequest), TreeMap.class);
        map.put("businessTimestamp", sign.getBusinessTimestamp());
        map.put("nonce", sign.getNonce());
        map.put("businessSign",sign.getBusinessSign());
        String param = GsonUtils.toJson(map);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/person/update?access_token="+ accessToken +"&id="+ id;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        PersonIssuedRelateUpdate.personIssuedRelateUpdate();
    }
}

3.2.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg": ""，
    "result":{
        "name":"刘xx",
        “personType”:1
        "groupList":[
            {
                           "groupId":"id_1",
                           "groupName":"name_1"
            }
        ],
        "memberDetail":{      （该对象仅成员返回） 
                "sex":"male",（成员字段）
                "internalNum":"B00",（成员字段）
                "cardId":"3278957248935789",（成员字段）
                "passWord":"199010",（成员字段）
                "entryDate":"2020-10-28",（成员字段）
                "birthDate":"1990-10-18"（成员字段）
        },
    "guestDetail":{ （该对象仅访客返回）
        "startTime":"2020-10-28T10:00:00Z",（访客字段）
        "endTime":"2020-10-28T12:00:00Z",（访客字段）
        "status":"ineffective", （访客字段）// 状态，可选值 “ineffective” “effective” “invalid”，分别表示 未生效、生效中、已失效
        "receiveMemId":"dasfasfafd",（访客字段），该字段必须传乘风平台人员id
        "purpose":"商务谈判", （访客字段）
        "expiredClearFlag": 0  （访客字段）
        },
        "phoneNum":"17221614782",
        "email":"liu@baidu.com",
        "backUp":"无备注",（访客没有）
        "hint":"欢迎光临",
        "avatar":"967624519a0f.jpg",
        "avatarPath":"http://XXXX/967624519a0f.jpg",
        "showAvatar":"967624519a0f.jpg",
        "showAvatarPath":"http://XXXX/967624519a0f.jpg",
        "createTime":"2019-07-22T04:08:54Z",
        "id":"hdjafhak_112",
        "customPersonId":"customPerson1371",
        "customExtends":"",
        "deviceIds": [
            "chengfeng-test-android-demo",
            "DMCM000BLC21A00006"
        ],
        "syncIds": [
            "SYNC_87902196c37d4a078cb768eb554a56d5",
            "SYNC_06bb413a6b754a9ebb3b54b6ed265e0c"
        ]
    }
}

Error Response Example

{
    "success":false,
    "error_code":336,
    "error_msg":{
        "global": "头像已被人员 MEM_12345_1 注册"
    },
    "result":{
        "existPersonId": "MEM_12345_1",
        "existCustomPersonId": "111111"
    }
}

3.2.4 返回字段说明

参数名	说明	数据类型	是否必传
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+name	人员姓名	String	是
+personType	人员类型 1:成员 2:访客 3:黑名单	Integer	是
+groupList	人员组实体数组	实体数组
+memberDetail	成员详情（添加成员需要加传该对象）	Object	否
++sex	性别。（成员字段）可选值 "male" "female"	String
++internalNum	成员编号（成员字段）	String
++cardId	卡号（成员字段）	String
++passWord	密码（成员字段）	String
++entryDate	入职日期，格式为 "yyyy-MM-dd"（成员字段）	String
++birthDate	出生日期，格式为 "yyyy-MM-dd"（成员字段）	String
+guestDetail	访客详情（添加访客需要加传该对象）	Object	否
++startTime	到访起始时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++endTime	到访结束时间，UTC时间，格式（访客字段） yyyy-MM-dd'T'HH:mm:ss'Z'	String
++status	访问状态（访客字段），可选值 “ineffective” “effective” “invalid”，分别表示未生效、生效中、已失效	String
++receiveMemId	受访人员id（访客字段），该字段必须传乘风平台人员id	String
++purpose	来访目的（访客字段）	String
++expiredClearFlag	访客过期清除标志(0：不清除 1：清除)（访客字段）	Integer
+phoneNum	手机号	String	否
+email	邮箱	String
+backUp	备注（访客没有）	String
+hint	自定义提示语	String
+avatar	注册照的key，图片通过上传接口上传后取得	String
+avatarPath	注册照的路径，图片通过上传接口上传后取得	String
+showAvatar	展示照的key，图片通过上传接口上传后取得	String
+showAvatarPath	展示照的路径，图片通过上传接口上传后取得	String
+createTime	创建时间（UTC时间）	Date
+id	人员ID	String
+customPersonId	开放接口用户方的人员ID（限长50）	String
+customExtends	开放接口用户扩展字段（限长200）	String
+deviceIds	设备号列表	string数组	是
+syncIds	同步任务id列表	string数组

(二) 人员组API

1 人员组管理

1.1 添加人员组

1.1.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/add

Method: post

接口描述: 添加人员组，按人员组类型参数区分

1.1.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
groupName	组名称	String	是
groupType	组类型 1:成员 2:访客 3:黑名单	Integer	是
idList	人员id数组	String数组	否

示例代码

package com.baidu.demo.test.group;

import com.baidu.demo.request.GroupAddRequest;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

public class GroupAdd {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupAdd() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String groupName = "postman测试人员组6";
        Integer groupType = 1;
        String[] idList = {"MEM_815265821110_1025"};
        // 2.签名
        GroupAddRequest groupAdd = GroupAddRequest.builder()
                .groupType(groupType)
                .groupName(groupName)
                .idList(idList)
                .build();
        OpenAPIRequest sign = SignUtil.sign(groupAdd, key);
        // 3.转化参数
        String param = GsonUtils.toJson(sign);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/add?access_token="+ accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        GroupAdd.groupAdd();
    }
}

1.1.3 返回数据

Response

{
    "success":true,
    "error_code":0,
        "error_msg": ""，
    "result":{
        "groupName":"人员组1",
        "personList":[
            {
                "id":"sdjkafjklasf",
                "name":"百同学",
                "internalNum":"B00",(成员带有此字段)
                                   "status":"ineffective",(访客带有此字段)
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            },
            {
                "id":"sdjkafjklasf",
                "name":"度同学",
                "internalNum":"B00",(成员带有此字段)
                "status":"ineffective",(访客带有此字段)
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            }
        ],
        "groupId":"5d3536d675549f21aac6f522"
    }
}

1.1.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+groupName	组名	String
+personList	人员列表	实体Array
++id	人员ID	String
++name	人员姓名	String
++internalNum	内部成员编号(成员带有此字段)	String
++status	访客状态(访客带有此字段)	String
++avatarPath	成员头像url路径(成员带有此字段)	String
+groupId	人员组ID	String

1.2 人员组列表（分页）

1.2.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/pageable

Method: get

接口描述: 人员组列表查询，按人员组类型参数区分

1.2.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
groupName	人员组名称	String	否
groupType	组类型 1:成员 2:访客 3:黑名单	Integer	是
pageNo	页码，大于等于1。默认为1	Integer	否
pageSize	页大小，默认为10（取值范围1～50）	Integer	否

Body

参数名	说明	数据类型	是否必填

示例代码

package com.baidu.demo.test.group;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.TreeMap;
import java.util.UUID;

public class GroupPageable {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupPageable() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间，客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String groupType =  "1";
        Integer pageNo =  1;
        Integer pageSize =  10;
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("groupType", groupType);
        map.put("pageNo", pageNo);
        map.put("pageSize", pageSize);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("businessSign", businessSign);
        map.put("access_token", accessToken);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/pageable";
        String result = HttpUtil.get(map, url);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args) {
        GroupPageable.groupPageable();
    }
}

1.2.3 返回数据

Response

{
    "success":true,
    "error_code":0,
         "error_msg": ""，
    "page":{
        "pageNo":1,
        "pageSize":10,
        "totalCount":2,
        "result":[
            {
                "groupId":"sdjkafjklasf",
                "groupName":"默认人员组",
                                   "count":5
            },
            {
                "groupId":"sdjkafjklasg",
                "groupName":"人员组1",
                "count":3
            }
        ]
    }
}

1.2.4 返回字段说明

参数名	说明	数据类型
success	请求是否成功	boolean
error_code	状态码	Integer
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象
page	page对象	map
+pageNo	页码	Integer
+pageSize	页大小	Integer
+totalCount	查询结果总条数	Integer
+result	结果详情描述	list
++groupId	人员组id	String
++groupName	人员组名称	String
++count	人员数	int

1.3 人员组批量删除

1.3.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/delete

Method: post

接口描述: 批量删除人员组，按组类型区分，一次只能删除一组同类人员组（例如删除一组访客组或者黑名单组），不可混合

1.3.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是

Body

参数名	说明	数据类型	是否必填
groupIdList	人员组id数组	String数组	是
groupType	组类型 1:成员 2:访客 3:黑名单	Integer	是

示例代码

package com.baidu.demo.test.group;

import com.baidu.demo.request.GroupDeleteRequest;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

import java.util.TreeMap;

public class GroupDelete {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupDelete() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        Integer groupType = 1;
        String[] groupIdList = {"MEM_815265821110_85"};
        // 2.签名
        GroupDeleteRequest groupAdd = GroupDeleteRequest.builder()
                .groupType(groupType)
                .groupIdList(groupIdList)
                .build();
        OpenAPIRequest sign = SignUtil.sign(groupAdd, key);
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("groupType", groupType);
        map.put("groupIdList", groupIdList);
        map.put("businessTimestamp", sign.getBusinessTimestamp());
        map.put("nonce", sign.getNonce());
        map.put("businessSign", sign.getBusinessSign());
        String param = GsonUtils.toJson(map);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/delete?access_token=" + accessToken;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: " + result);
    }

    public static void main(String[] args){
        GroupDelete.groupDelete();
    }
}

1.3.3 返回数据

Response

{
    "success":true,
    "error_code":0,
         "error_msg": ""，
    "result":{
        "successIdList":[
            "fsdafa1","dsafdas2"
        ],
        "failIdList":[
            "fsdafa3"
        ]
    }
}

1.3.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+successIdList	删除成功id列表	String数组
+failIdList	删除失败id列表	String数组

1.4 修改人员组

1.4.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/update

Method: post

接口描述: 对人员组进行修改，可以更新人员组的名称和包含的人员id列表，按人员组类型参数区分

1.4.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
groupId	人员组唯一标识	String	是

Body

参数名	说明	数据类型	是否必填
groupName	人员组名称	String	是
idList	人员id数组	String数组	否
groupType	组类型 1:成员 2:访客 3:黑名单	Integer	是

示例代码

package com.baidu.demo.test.group;

import com.baidu.demo.request.GroupAddRequest;
import com.baidu.demo.request.OpenAPIRequest;
import com.baidu.demo.utils.GsonUtils;
import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;

public class GroupUpdate {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupUpdate() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间， 客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String groupId =  "MEM_815265821110_994";
        String groupName =  "测试人员组444444444";
        Integer groupType =  1;
        String[] idList = {"MEM_815265821110_81793"};
        // 2.签名
        GroupAddRequest groupAdd = GroupAddRequest.builder()
                .groupId(groupId)
                .groupType(groupType)
                .groupName(groupName)
                .idList(idList)
                .build();
        OpenAPIRequest sign = SignUtil.sign(groupAdd, key);
        // 3.转化参数
        String param = GsonUtils.toJson(sign);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/update?access_token="+ accessToken +"&groupId="+ groupId;
        String result = HttpUtil.post(url, param);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args){
        GroupUpdate.groupUpdate();
    }
}

1.4.3 返回数据

Response

{
    "success":true,
    "error_code":0,
         "error_msg": "",
    "result":{
        "groupName":"人员组1",
        "personList":[
            {
                "id":"sdjkafjklasf",
                "name":"百同学",
                "internalNum":"B00",(成员列表带有)
                "status":"ineffective",(访客列表带有)
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            },
            {
                "id":"sdjkafjklasf",
                "name":"度同学",
                "internalNum":"B00",(成员列表带有)
                "status":"ineffective",(访客列表带有)
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            }
        ],
        "groupId":"5d3536d675549f21aac6f522"
    }
}

1.4.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+groupName	组名	String
+personList	人员列表	实体Array
++id	人员ID	String
++name	人员姓名	String
++internalNum	内部成员编号(成员列表带有)	String
++status	访客状态(访客列表带有)	String
++avatarPath	人员头像url路径	String
+groupId	人员组ID	String

1.5 人员组详情

1.5.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/detail

Method: get

接口描述: 查询人员组详情，按人员组类型参数区分

1.5.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
groupType	组类型 1:成员 2:访客 3:黑名单	Integer	是
groupId	人员组唯一标识	String	是

Body

参数名	说明	数据类型	是否必填

示例代码

package com.baidu.demo.test.group;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;
import java.util.TreeMap;
import java.util.UUID;

public class GroupDetail {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void groupDetail() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间，客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String groupId =  "MEM_815265821110_68";
        String groupType =  "1";
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("groupId", groupId);
        map.put("groupType", groupType);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign = SignUtil.sign(map, key);
        map.put("businessSign", businessSign);
        map.put("access_token", accessToken);
        // 4.发送请求
        String url = "https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/group/detail";
        String result = HttpUtil.get(map, url);
        // 5.获取结果
        System.out.println("响应结果: "+ result);
    }

    public static void main(String[] args) {
        GroupDetail.groupDetail();
    }

}

1.5.3 返回数据

Response

{
    "success":true,
    "error_code":0,
    "error_msg":"",
    "result":{
        "groupName":"人员组1",
        "personList":[
            {
                "id":"sdjkafjklasf",
                "name":"百同学",
                "internalNum":"B00",（成员带有）
                "status":"ineffective",（访客带有）
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            },
            {
                "id":"sdjkafjklasf",
                "name":"度同学",
                "internalNum":"B00",
                "status":"ineffective",
                "avatarPath":"http://XXXX/967624519a0f.jpg"
            }
        ],
        "groupId":"5d3536d675549f21aac6f522"
    }
}

1.5.4 返回字段说明

参数名	说明	数据类型	是否必填
success	请求是否成功	boolean	是
error_code	状态码	Integer	是
error_msg	失败提示信息（只有当success为 false 时，接口才会返回message字段）	json对象	是
result	请求结果	String	是
+groupName	组名	String
+personList	人员列表	实体Array
++id	人员ID	String
++name	人员姓名	String
++internalNum	内部成员编号（成员带有）	String
++status	访客状态（访客带有）	String
++avatarPath	人员头像url路径	String
+groupId	人员组ID	String

(三) 设备API

1 设备信息

1.1 获取设备列表

1.1.1 基本信息

Path: https://aip.baidubce.com/rest/2.0/chengfeng/openapi/v1/device/list

Method: get

接口描述: 查询设备列表

1.1.2 请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Path 变量

参数名称	说明	数据类型	是否必填

RequestParam

参数名	说明	数据类型	是否必填
access_token	请求接口token	String	是
pageNo	页码，大于等于1。默认为1	Integer	否
pageSize	页大小，默认为10（取值范围1～50）	Integer	否
deviceNameSn	搜索使用的设备名称或者sn	string	否
deviceTypeId	搜索使用的设备类型	string	否
deviceCodeId	设备型号	string	否
workStatusId	搜索使用的设备工作状态	string	否

Body

参数名	说明	数据类型	是否必填

示例代码

package com.baidu.demo.test.device;

import com.baidu.demo.utils.HttpUtil;
import com.baidu.demo.utils.SignUtil;
import java.util.TreeMap;
import java.util.UUID;

public class DeviceList {
    /**
     * request,utils文件夹请从接口文档, 接口示例代码工程中下载
     *
     */
    public static void deviceList() {
        // 1.定义参数
        // 注意这里仅为了简化编码每一次请求都去获取access_token，线上环境access_token有过期时间，客户端可自行缓存，过期后重新获取。
        String accessToken = "[调用鉴权接口获取的token]";
        String key = "[乘风平台页面-个人中心-验签密钥]";
        String groupType =  "1";
        Integer pageNo =  1;
        Integer pageSize =  10;
        String businessTimestamp = System.currentTimeMillis()+"";
        String nonce = UUID.randomUUID().toString();
        // 2.组装参数
        TreeMap<String, Object> map = new TreeMap<>();
        map.put("groupType", groupType);
        map.put("pageNo", pageNo);
        map.put("pageSize", pageSize);
        map.put("businessTimestamp", businessTimestamp);
        map.put("nonce",nonce);
        // 3.签名
        String businessSign =

百度智能云

人脸识别

人脸识别

接口文档

乘风平台接口文档

一. 前言

(一) 文档说明

(二) 访问限制

(三) 接入流程及签名规则

1.获取access_token

2. 获取key（验签密钥）

3.构建businessSign(签名)

3.1 签名须知

3.2签名规则

3.3 注意事项

4.参考示例

(四) Postman请求工具和示例工程

1.Postman请求工具（推荐使用，解决验签失败问题）

2. 接口示例代码工程

(五) 接口调用顺序

1.常规模式（推荐）

1.1 流程

1.2 说明

2.快捷模式

2.1流程

2.2说明

(六)返回体的数据格式

(七)数据推送

二. 接口详情

接口公共字段

(一) 人员API

1 人员管理

1.1 添加人员

1.1.1 基本信息

1.1.2 请求参数

1.1.3 返回数据

1.1.4 返回字段说明

1.2 人员列表（分页）

1.2.1 基本信息

1.2.2 请求参数

1.2.3 返回数据

1.2.4 返回字段说明