1. 概述

边缘网关门禁服务通过边缘方案集成本地门禁系统，把本地系统、老旧存量系统接入阿里云IoT云，实现设备、系统上云。

方案支持传统的卡式门禁、二维码门禁，为不同类型的门禁提供了标准数据模型和服务模型。这些标准模型可以由其它平台集成，实现系统控制（下行）和业务感知（数据上行）的业务闭环。

2. 接口定义

2.1通用对象

2.1.1 门禁对象DeviceInfo

字段	类型	是否必传	备注
gatewayProductKey	String	如不传gatewayIotId，此处必填	边缘网关设备的productKey
gatewayDeviceName	String	如不传gatewayIotId，此处必填	边缘网关设备的deviceName
gatewayIotId	String	如不传gatewayProductKey和gatewayDeviceName，此处必填	边缘网关的iotId，
iotId	String	是	设备门禁的iotId
direction	String	否	ENTRANCE，EXIT，如不填不更新
extInfo	String	否	设备扩展信息，用于数据模型透出，如不填不更新

2.1.2 人员信息UserDTO

字段	类型	备注
identityId	String	统一身份ID。
name	String	人员称谓。
extInfo	String	自定义信息。

2.1.3 门禁卡权限CardDTO

字段	类型	备注
iotId	String	门禁设备的iotId
expiryTime	String	有效期，时间格式 yyyy-MM-dd HH:mm:ss"
cardId	String	门禁卡id
identityId	String	统一身份ID

2.1.4 蓝牙卡权限BLECardDTO

字段	类型	备注
iotId	String	门禁设备的iotId
expiryTime	String	有效期，时间格式 yyyy-MM-dd HH:mm:ss"
bleCardId	String	蓝牙id
identityId	String	统一身份ID

2.2人员信息管理

2.2.1添加或更新人员信息

路径	/entrance/paas/user/modify
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
identityId	String	是	统一身份ID。若identityId在库里存在走更新流程，若identityId在库里不存在走创建流程。
name	String	否	人员称谓。在更新的时候，如不传不会对原有值做修改。在创建的时候必须传。
extInfo	String	否	自定义信息。在更新的时候，如不传不会对原有值做修改。在创建时候可以不填。

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 设置参数
request.putParam("identityId","value1");
request.putParam("name","value2");
request.putParam("extInfo","value3");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/user/modify", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 200,
 "message": null,
 "localizedMsg": null,
 "data": null
}

异常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 500,
 "message": "system err",
 "localizedMsg": "系统错误",
 "data": null
}

2.2.2删除人员信息

路径	/entrance/paas/user/delete
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
identityId	String	是	统一身份ID。

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 设置参数
request.putParam("identityId","value1");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/user/delete", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 200,
 "message": null,
 "localizedMsg": null,
 "data": null
}

异常返回示例：

{
  "id":"4a70179d-47d8-4fdf-9067-8a5eedf63483",
  "code": 403,
  "message": "user does not exist",
  "localizedMsg": "用户不存在",
  "data":null
}

2.2.3 查询人员信息

路径	/entrance/paas/user/get
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
identityId	String	是	统一身份ID

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSON	响应结果。

响应结果 data：

名称	类型	描述
identityId	String	统一身份id。
name	String	用户姓名。
extInfo	String	用户扩展信息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 设置参数
request.putParam("identityId","value1");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/user/get", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 200,
 "message": null,
 "localizedMsg": null,
 "data": {
  "identityId": "xx",
  "name": "xxx",
  "extInfo": {}
 }
}

异常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 500,
 "message": "system err",
 "localizedMsg": "系统错误",
 "data": null
}

2.2.4 人员列表

路径	/entrance/paas/user/query
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
pageSize	Integer	是	分页查询一页内的记录数，上限100
pageNo	Integer	是	分页数，从1开始

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONObject	分页数据对象PageDTO

分页数据对象PageDTO：

名称	类型	描述
pageSize	Integer	传入的pageSize
pageNo	Integer	传入的pageNo
total	Long	总记录数
data	JSONArray	数据列表

数据列表：

名称	类型	描述
identityId	String	统一身份id
name	String	用户姓名
extInfo	String	用户扩展信息

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 设置参数
request.putParam("pageSize","value1");
request.putParam("pageNo","value2");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/user/query", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 200,
 "message": null,
 "localizedMsg": null,
 "data": {
  "total": 1,
  "pageNo": 1,
  "pageSize": 10,
  "data": [{
   "identityId": "xxx",
   "name": "xxx",
   "extInfo": {}
  }]
 }
}

异常返回示例：

{
 "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
 "code": 500,
 "message": "system err",
 "localizedMsg": "系统错误",
 "data": null
}

2.3 刷卡&蓝牙门禁权限管理

2.3.1 批量设置门禁卡权限

路径	/entrance/paas/perm/card/batchmodify
版本号	1.0.2
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	25000

请求参数

名称	类型	是否必选	描述
cards	JSONArray	是	待创建门禁卡权限列表，上限200

待创建门禁卡权限列表 cards：

名称	类型	是否必选	描述
iotId	String	是	门禁设备的iotId
cardId	String	是	门禁卡id
identityId	String	是	统一身份ID
expiryTime	String	是	超时时间，时间格式 yyyy-MM-dd HH:mm:ss

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONArray	响应结果。处理失败的记录，建议可以依照这个列表重新添加。

响应结果 data

名称	类型	描述
iotId	String	门禁设备的iotId
cardId	String	门禁卡id
identityId	String	统一身份ID
code	Integer	错误码
message	String	错误信息

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.2");
// 如果需要登录，设置当前的会话的token，token通过登录api获取
request.setIotToken("你的<IoTToken>");
// 设置参数
request.putParam("cards","value1");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/perm/card/batchmodify", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
  "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
  "code": 200,
  "message": null,
  "localizedMsg": null,
    "data": [{
    "identityId": "50acopfd3a94900494085ed2699e052432c34452",
    "iotId":"p2OsgId2N2kXMWThRCQP000101",
    "cardId":"3d8deae9402d38adfji38",
    "code": 460,
    "message": "device offline"
  }]
}

异常返回示例：

{
    "code":403,
    "message":"request forbidden.",
    "localizedMsg":"请求被禁止"
}

2.3.2 删除刷卡门禁上某用户的权限

路径	/entrance/paas/perm/card/batchdelete
版本号	1.0.1
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	25000

请求参数

名称	类型	是否必选	描述
list	JSONArray	是	待删除对象列表 PermDTO

待删除对象列表PermDTO

名称	类型	是否必选	描述
identityId	String	是	统一身份ID
iotId	String	是	门禁id
cardId	String	是	门禁卡id，最大长度255字符

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONArray	删除失败的列表 ModifyResultDTO

删除失败的列表ModifyResultDTO

名称	类型	描述
iotId	String	门禁设备的iotId
cardId	String	门禁卡id
identityId	String	统一身份ID
code	Integer	错误码
message	String	错误信息

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.1");
// 如果需要登录，设置当前的会话的token，token通过登录api获取
request.setIotToken("你的<IoTToken>");
// 设置参数
request.putParam("list","value1");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/perm/card/batchdelete", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "code": 200,
    "data": [
        {
            "cardId": "3d8deae9402d38adfji38",
            "identityId": "50acopfd3a94900494085ed2699e052432c34452",
            "iotId": "p2OsgId2N2kXMWThRCQP000101"
        }
    ],
    "message": "success"
}

异常返回示例：

{
    "code":403,
    "message":"request forbidden.",
    "localizedMsg":"无效的设备ID"
}

2.3.3 查询用户的门禁卡权限信息

路径	/entrance/paas/user/perm/query
版本号	1.0.1
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	20000

请求参数

名称	类型	是否必选	描述
permQueryList	JSONArray	是	需要查询的权限列表，由用户、卡、设备证书（ProductKey、DeviceName、DeviceSecret）构成

需要查询的权限列表 permQueryList

名称	类型	是否必选	描述
iotId	String	是	设备id
identityId	String	是	用户id
cardId	String	是	卡号

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONObject	分页数据对象PermDTO

分页数据对象PermDTO：

名称	类型	描述
identityId	字符串	用户id
iotId	字符串	设备id
cardId	字符串	卡号
status	字符串	权限状态

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.1");
// 设置参数
request.putParam("permQueryList","value1");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/user/perm/query", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
  "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data":[{
    "iotId": "50acopfd3a94900494085ed2699e052432c34452",
    "identityId": "p2OsgId2N2kXMWThRCQP000101",
    "cardId":"3d8deae9402d38adfji38"
  }]

异常返回示例：

{
    "code":403,
    "message":"request forbidden.",
    "localizedMsg":"请求被禁止"
}

2.3.4 查询门禁设备上的权限信息

路径	/entrance/paas/device/perm/query
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
iotId	String	是	刷卡门禁设备的iotId
pageSize	Integer	是	分页查询一页内的记录数，上限100
pageNo	Integer	是	分页数，从1开始

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONObject	分页数据对象PageDTO

分页数据对象PageDTO

名称	类型	描述
pageSize	Integer	传入的pageSize
pageNo	Integer	传入的pageNo
total	Long	总记录数
data	JSONArray	门禁卡权限对象列表

门禁卡权限对象列表：

名称	类型	描述
identityId	String	统一身份ID
iotId	String	设备ID
cardId	String	卡ID
expiryTime	String	过期时间

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 设置参数
request.putParam("iotId","value1");
request.putParam("pageNo","value2");
request.putParam("pageSize","value3");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/device/perm/query", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
  "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
  "code": 200,
  "message": null,
  "localizedMsg": null,
    "data":{
        "total":1,
        "pageSize":10,
        "pageNo":1,
        "data":[
            {
                "identityId":"50acopfd3a94900494085ed2699e052432c34452",
                "iotId":"p2OsgId2N2kXMWThRCQP000101",
                "expiryDate":"2020-03-04 18:00:00",
                "cardId":"3d8deae9402d38adfji38"
            }
        ]
    }
}

异常返回示例：

{
    "code":403,
    "message":"request forbidden.",
    "localizedMsg":"请求被禁止"
}

2.4 二维码门禁通行方式

2.4.1生成二维码

路径	/homelink/common/qrcode/generate
版本号	1.0.1
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
identityId	String	是	申请二维码人员的统一身份ID
codeLength	整型	否	二维码字符串长度

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	String	二维码

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.1");
// 设置参数
request.putParam("identityId","value1");
request.putParam("codeLength","value2");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/homelink/common/qrcode/generate", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null,
    "data": "24DD9END8CD3"
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.4.2 二维码权限配置

路径	/entrance/paas/perm/qrcode/config
版本号	1.0.1
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	20000

请求参数

名称	类型	是否必选	描述
qrCode	String	是	二维码
iotIds	JSONArray	是	待配置权限的门禁设备iotId
identityId	String	是	申请二维码人员的统一身份ID
effectiveTime	String	否	二维码生效期，时间格式 yyyy-MM-dd HH:mm:ss 默认为当前时间
expiryTime	String	是	二维码失效期，时间格式 yyyy-MM-dd HH:mm:ss
maxScanTimes	Integer	否	最大刷码次数，默认为-1不做次数限制
maxScanScope	String	否	最大刷码次数作用范围，默认为每个设备独立计数 SHARE – 共享 DEVICE – 设备

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSONArray	权限配置结果

权限配置结果 data：

名称	类型	描述
code	int	返回码
message	String	错误消息
iotId	String	设备iotId

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.1");
// 如果需要登录，设置当前的会话的token，token通过登录api获取
request.setIotToken("你的<IoTToken>");
// 设置参数
request.putParam("qrCode","value1");
request.putParam("iotIds","value2");
request.putParam("identityId","value3");
request.putParam("expiryTime","value4");
request.putParam("effectiveTime","value5");
request.putParam("maxScanTimes","value6");
request.putParam("maxScanScope","value7");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/perm/qrcode/config", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null,
    "data": [
        {
          "iotId": "p2OsgId2N2kXMWThRCQP000101",
          "code": "200"
        }
      ]
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.4.3 二维码权限删除

路径	/entrance/paas/perm/qrcode/remove
版本号	1.0.1
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	20000

请求参数

名称	类型	是否必选	描述
qrCode	String	是	二维码
identityId	String	是	申请二维码人员的统一身份ID
iotIds	JSONArray	是	门禁设备iotId

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSON	设备结果列表

设备结果列表 data：

名称	类型	描述
code	Int	错误码，200为成功
message	String	错误信息
iotId	String	设备ID

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.1");
// 如果需要登录，设置当前的会话的token，token通过登录api获取
request.setIotToken("你的<IoTToken>");
// 设置参数
request.putParam("qrCode","value1");
request.putParam("iotIds","value2");
request.putParam("identityId","value3");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/entrance/paas/perm/qrcode/remove", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null,
    "data": [
        {
            "code": 200,
            "iotId": "xxxx"
        }
        ]
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.5 远程控制开门

路径	/cloud/thing/service/invoke
版本号	1.0.2
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	15000

请求参数

名称	类型	是否必选	描述
iotId	String	是	门禁设备的iotId
identifier	String	是	固定值“remoteOpen”
args	JSNOObject	是	固定值{}
productKey	String	是	产品的Key，设备证书信息之一。
deviceName	String	是	设备的名称，设备证书信息之一。

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.2");
// 设置参数
request.putParam("iotId","p2OsgId2N2kXMWThRCQP000101");
request.putParam("identifier","remoteOpen");
request.putParam("args", {});
request.putParam("productKey","value4");
request.putParam("deviceName","value5");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/cloud/thing/service/invoke", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
  "code": 200,
  "data": null,
  "message": "success",
  "localizedMsg": ""
}

3. 数据模型定义

3.1 门禁通行事件

模型ID：iot_entrance_event_model

模型版本：1.1

属性列表：

属性名称	属性标识符	数据类型	数据描述	必须
租户	tenantId	String	租户	是
IoT体系用户标示	identityId	String	IoT体系用户标示	是
用户姓名	name	String	用户姓名	是
事件时间	time	Date	事件时间	是
IoT设备标示	iotId	String	IoT设备标示	是
通行类型	type	String	通行类型 - CARD门禁卡 - PASSWORD密码 - QRCODE二维码 - BleCARD蓝牙门禁卡	是
密码号码	number	String	密码号码	否
门禁卡号	cardId	String	门禁卡号，只有type是CARD的时候有效	否
通行方向	direction	String	通行方向，ENTRANCE 进, EXIT 出	否
用户扩展信息	userExtInfo	String	用户扩展信息	否
设备扩展信息	devExtInfo	String	设备扩展信息	否
事件扩展信息	eventExtInfo	String	事件扩展信息 { "code": 0, //0为通行成功 "message": "xxx",//通行失败原因 "remainScanTimes":1//二维码剩余刷码次数 }	否
项目ID	projectId	String	项目ID，如为租户数据则为空	否

3.2 通行失败事件码说明

通行结果（code）	结果说明（message）
0	成功	success
101	二维码未生效	QR code does not take effect
102	二维码已过期	QR code has expired
103	二维码不存在	QR code does not exist
104	二维码刷码次数用尽	QR code have be used up
201	传统卡号未生效	Traditional card number does not take effect
202	传统卡号已过期	Traditional card number has expired
203	传统卡号不存在	Traditional card number does not exist
301	蓝牙卡号未生效	Bluetooth card number does not take effect
302	蓝牙卡号已过期	Bluetooth card number has expired
303	蓝牙卡号不存在	Bluetooth card number does not exist