华为云用户手册

上报升级结果 根据PCP协议约定的交互流程，设备在执行完软件升级后，将会向物联网平台上报升级的结果。 设备发送的请求消息 根据PCP消息结构的定义可以得出，设备向物联网平台上报升级结果，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为18。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为17字节，转换为十六进制为：0011。 数据区：结果码，以上报升级成功为例，结果码为00。当前版本号：升级完成后的版本号，与物联网平台下发的软件版本一致，即v1.0，转换为十六进制为：56312E30000000000000000000000000。 字段 数据类型 描述及要求 结果码 BYTE 0X00升级成功。 0X01设备使用中。 0X04电量不足。 0X05剩余空间不足。 0X09内存不足。 0X0A安装升级包失败。 0X7F内部异常。 当前版本号 BYTE[16] 设备当前版本号。 设备向物联网平台上报升级结果的消息为：FFFE 01 18 0000 0011 0056312E30000000000000000000000000（CRC16校验前），经CRC16计算得到校验码为：C7D2。则替换校验码后设备向物联网平台上报升级结果码流为：FFFE0118C7D200110056312E30000000000000000000000000。 物联网平台发送的应答消息 物联网平台收到设备上报的升级结果消息后，将对设备进行应答，各个消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：18。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，升级任务不存在80。本示例以返回00处理成功为例进行说明。 字段 数据类型 描述及要求 结果码 BYTE 0X00处理成功。 0X80升级任务不存在。 物联网平台向设备的应答消息为：FFFE 01 18 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：AFA1。则替换校验码后物联网平台返回的应答消息为：FFFE0118AFA1000100 。 至此，设备的软件升级功能适配就完成了，赶紧动手试一试吧。

上报下载结果 根据PCP协议约定的交互流程，设备接收完所有分片数据并组装完软件包后，需要向物联网平台上报软件包的下载结果。 设备发送的请求消息 根据PCP消息结构的定义可以得出，设备向物联网平台发送的上报软件包下载结果消息，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为16。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为1个字节，转换为十六进制为：0001。 数据区：上报软件包的下载结果，比如下载成功，设备侧上报00。 字段 数据类型 描述及要求 下载状态 BYTE 0X00下载成功。 0X05剩余空间不足。 0X06下载超时。 0X07升级包校验失败。 0X08升级包类型不支持。 设备向物联网平台发送升级包下载结果的消息为：FFFE 01 16 0000 0001 00（CRC16校验前），经CRC16计算得到校验码为：850E。则替换校验码后设备发送的升级包下载结果的消息为：FFFE0116850E000100。 物联网平台的应答消息 物联网平台收到设备上报的软件包下载结果后，将会向设备返回应答消息，各个消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：16。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，处理失败返回80。本示例以返回00处理成功为例进行说明。 字段 数据类型 描述及要求 结果码 BYTE 0X00处理成功。 0X80升级任务不存在。 物联网平台向设备应答的消息为：FFFE 01 16 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：850E。则替换校验码后物联网平台向设备应答的消息为：FFFE0116850E000100。

执行软件升级 根据PCP协议约定的交互流程，物联网平台收到设备发送的软件包下载结果通知后，需要通知设备进行升级操作。 物联网平台发送的请求消息 根据PCP消息结构的定义可以得出，物联网平台向设备发送执行软件升级消息，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为17。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出无数据区，即为0字节，转换为十六进制为：0000。 数据区：无数据区，无需携带该字段。 字段 数据类型 描述及要求 无数据区 物联网平台向设备下发的执行软件升级的消息为：FFFE 01 17 0000 0000（CRC16校验前），经CRC16计算得到校验码为：CF90。则替换校验码后物联网平台向设备发送的消息为：FFFE0117CF900000。 设备发送的应答消息 设备收到物联网平台下发的执行升级消息后，将对收到消息后的执行动作进行应答，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：17。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，其它处理结果请参考数据区定义。本示例以返回00处理成功为例进行说明。 字段 数据类型 描述及要求 结果码 BYTE 0X00处理成功。 0X01设备使用中。 0X04电量不足。 0X05剩余空间不足。 0X09内存不足。 设备向物联网平台应答的消息为：FFFE 01 17 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：B725。则替换校验码后设备返回的响应消息为：FFFE0117B725000100 。

下载升级包 根据PCP协议约定的交互流程，物联网平台通知设备有新的软件版本时，设备向物联网平台请求下载软件包，按照分片的序号进行下载。 设备发送的请求消息 根据PCP消息结构的定义可以得出，设备向物联网平台发送的请求软件包分片的第一条消息，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：查询消息码表可知请求升级包的消息码为21，转换为十六进制为：15。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为18个字节，转换为十六进制为：0012。 数据区：目标版本号为平台下发的新版本通知版本号，即v1.0，转换为十六进制为56312E30000000000000000000000000，分片序号为第0个分片，即0000。 字段 数据类型 描述及要求 目的版本号 BYTE[16] 目的版本号，由ASCII字符组成，位数不足时，后补“0X00”。 分片序号 WORD 表示请求获取的分片序号，从0开始计算，分片的总数为软件包大小除以每个分片的大小并向上取整获得。设备可以保存已经收到的分片，下次直接从缺失的分片开始请求，达到断点续传的效果。 设备向物联网平台发送请求软件包分片的第一条消息为：FFFE 01 15 0000 0012 56312E30000000000000000000000000 0000（CRC16校验前），经CRC16计算得到校验码为：5618。则替换校验码后设备发送的第一条请求分片消息为：FFFE01155618001256312E300000000000000000000000000000。 其它分片请求的消息流只需要替换分片序号后，重新计算并替换CRC16校验码即可，此处就不再展开。 物联网平台的应答消息 物联网平台收到设备的请求软件包分片消息后，将会给设备下发分片的数据。物联网平台向设备响应的第一条请求分片的消息，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：15。 校验码：CRC16计算前先用0000替代。 数据区：先讲数据区再讲数据区长度。结果码：00，分片序号：第0个分片：0000，分片数据：跟软件包定义的内容有关，我们假设软件包内容为HELLO, IoT SOTA!，经ASCII码转换为十六进制为：48454C4C4F2C20496F5420534F544121，共16字节。用户上传软件包时手动输入升级包分片大小为500byte，即最大长度为500字节。这种情况下，无需在数据的后面补充0。 字段 数据类型 描述及要求 结果码 BYTE 0X00处理成功。 0X80升级任务不存在。 0X81指定的分片不存在。 分片序号 WORD 表示返回的分片序号。 分片数据 BYTE[n] 分片的内容，n为实际的分片大小。如果结果码不为0，则不带此字段。 数据区长度：根据数据区的字段定义得出该数据长度为19，转换为十六进制为：0013。 物联网平台向设备发送的第一个软件包分片消息为：FFFE 01 15 0000 0013 00 0000 48454C4C4F2C20496F5420534F544121（CRC16校验前），经CRC16计算得到校验码为：E107。则替换校验码后物联网平台向设备发送的第一个软件包分片消息为：FFFE0115E107001300000048454C4C4F2C20496F5420534F544121。 其它软件包分片的消息流只需要替换分片序号和分片数据后，重新计算并替换CRC16校验码即可，此处就不再展开。

下载新版本软件包通知 根据PCP协议约定的交互流程，查询完版本号后，物联网平台下发指令让设备下载新版本的软件包。 物联网平台发送消息 根据PCP消息结构的定义可以得出，物联网平台向设备下发下载新版本软件包通知时，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：此处为新版本通知，查询消息码表可以知道新版本通知为20，转换为十六进制为14。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的消息字段可以得出，数据区长度为22个字节，转换为十六进制为：0016。 数据区：根据数据区的定义可知。 目标版本号：由16个字节组成，假设升级的目标版本号为v1.0版本，转换为十六进制并在后面14个字节补充0后得到：56312E30000000000000000000000000。 升级包分片大小：由2个字节组成，单位为byte，用户上传软件包时可以手动输入升级包分片大小，如果不设置默认为500byte，大小为32~500之间。假设为500byte，转换为十六进制后为：01F4。 升级包分片总数：由2个字节组成，由软件包大小除以每个分片的大小并向上取整获得。假设软件包大小为500byte，则分片数量为1，转换为十六进制后为：0001。 检验码：由2个字节组成，目前已废弃，固定为：0000。 字段 数据类型 描述及要求 目的版本号 BYTE[16] 目的版本号，由ASCII字符组成，位数不足时，后补“0X00”。 升级包分片大小 WORD 每个分片的大小 升级包分片总数 WORD 升级包分片总数 升级包校验码 WORD 固定为：0000 将下载新版本软件包通知的消息流组合起来得到：FFFE 01 14 0000 0016 56312E30000000000000000000000000 01F4 0001 0000。前面说了，还要将消息流进行CRC16算法计算得到校验码为02F7。因此，物联网平台向设备通知下载新版本软件包的信息，物联网平台向设备发送的消息流为FFFE011402F7001656312E3000000000000000000000000001F400010000。 设备返回的应答消息 设备收到下载新版本软件包通知后，设备向物联网平台返回应答消息，是否允许设备进行升级，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为14。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为1个字节，转换为十六进制为：0001。 数据区：设备根据自身的情况对平台下发的新版本通知进行响应，本示例以设备应答“允许升级”为例进行介绍，得出数据区为：00。其它应答消息请根据应答消息字段进行适配。 字段 数据类型 描述及要求 结果码 BYTE “0X00”允许升级 “0X01”设备使用中 “0X02”信号质量差 “0X03”已经是最新版本 “0X04”电量不足 “0X05”剩余空间不足 “0X09”内存不足 “0X7F”内部异常 将设备给物联网平台的应答消息流组合起来得到：FFFE 01 14 0000 0001 00。前面说了，还要将消息流进行CRC16算法计算得到校验码为D768。因此，设备向平台返回的应答消息流为FFFE0114D768000100。

概述 设备的OTA软件升级是基于华为定义的PCP协议进行的，设备侧需根据PCP协议定义的交互流程进行适配开发。下面我们将结合物联网平台与设备的软件升级交互流程，介绍终端设备将如何基于PCP协议构建交互过程中的请求消息和应答消息，帮助您更好的根据PCP协议进行终端侧的软件升级功能开发。 下面我们先了解下PCP消息的结构，PCP协议的请求消息和应答消息都遵循相同的消息结构，主要由这几部分组成： PCP协议消息由：起始标识位、版本号、消息码、校验码、数据区长度和数据区组成，各字段的要求和描述如下表所示。 字段名 字段类型 描述和要求 起始标识 WORD 起始标识，固定为0XFFFE。 版本号 BYTE 高四位预留；低四位表示协议版本号，当前为1。 消息码 BYTE 标识物联网平台与设备之间的请求消息类型，应答消息的消息码和请求消息相同。消息码的定义为： 0-18：预留消息码，暂未使用。 19：查询设备版本。 20：下载新版本软件包通知。 21：请求下载升级包。 22：上报升级包下载结果。 23：执行软件升级。 24：上报升级结果。 25-127：预留消息码，暂未使用。 校验码 WORD 从起始标识到数据区的最后一个字节的CRC16校验值，计算前先把校验码字段置为0，计算完成后把结果写到校验码字段。 说明： CRC16算法：CRC16/CCITT x16+x12+x5+1 数据区长度 WORD 数据区的长度。 数据区 BYTE[n] 可变长度，具体由各个指令定义，可参考下面介绍的各个指令对应的请求消息和应答消息定义。 数据类型 描述 BYTE 无符号一字节整数 WORD 无符号二字节整数 DWORD 无符号四字节整数 BYTE[n] n字节的十六进制数 STRING 字符串

查询设备版本号 从设备的软件升级流程（本流程只描述物联网平台与设备基于PCP协议交互的流程，完整的软件升级流程请参考LwM2M协议设备软件升级流程）可以看到，首先物联网平台向设备下发查询版本号信息，设备进行应答。 物联网平台发送消息 根据PCP消息结构的定义可以得出，物联网平台向设备下发查询版本号时，各消息字段的填写如下： 起始标识：固定为消息流的前2个字节，固定为FFFE。 版本号：数据类型为1个字节整数，且固定为1，即在消息流中为01。 消息码：数据类型为1个字节整数，查询设备版本的消息码为19，转换为十六进制为13。 校验码：数据类型为2个字节整数，先将校验码置为0000，然后将完整的消息码流进行CRC16的算法计算得到校验码，再将得到的校验码替换原消息中的0000。 数据区长度：数据类型为2个字节整数，代表数据区的消息长度，根据数据区的数据结构可以得出该条消息无数据区，即数据区长度为0000。 数据区：数据区代表要真正发送给设备的数据，根据查询版本信息的数据区定义，该条消息是没有实际要传送的数据的，即无需数据区字段。 字段 数据类型 描述及要求 无数据区 因此将查询版本消息的码流组合起来得到：FFFE 01 13 0000 0000。前面的校验码时讲了，需要将组合后的消息码流进行CRC16算法（物联网平台提供了基于JAVA和C语言的CRC16算法代码样例，您可以直接使用）得到校验码4C9A，然后将该校验码替换原码流中的0000后得到FFFE01134C9A0000，该消息码流即为物联网平台发送给设备的查询版本信息的消息码流。 设备返回的应答消息 设备收到物联网平台要查询设备的软件版本号消息，设备要向物联网平台反馈查询的结果，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为13。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为17个字节，转换为十六进制为：0011。 数据区：根据数据区的定义可知，处理成功的结果码为00，版本号信息假设为V0.9，将V0.9进行ASCII转码得到56302E39，由于版本号的数据类型为BYTE[16]，即16个字节，当前只有4个字节，因此需要在版本号数据后面补0，得到56302E39000000000000000000000000。因此，数据区合并后为0056302E39000000000000000000000000。 字段 数据类型 描述及要求 结果码 BYTE “0X00”处理成功 当前版本号 BYTE[16] 当前版本号，由ASCII字符组成，位数不足时，后补“0X00”。 将查询版本信息的消息流组合起来得到：FFFE 01 13 0000 0011 0056302E39000000000000000000000000。前面讲到，还要将消息流进行CRC16算法计算得到校验码为8DE3。因此，物联网平台向设备查询版本号信息，设备向平台返回的消息流为FFFE01138DE300110056302E39000000000000000000000000。

上传软件包 创建批量设备软件升级任务前需要上传软件升级包，平台支持两种方式上传软件包： 应用服务器通过调用“创建OTA升级包”API接口，创建OTA升级包，详情请参考创建OTA升级包。 通过控制台，在软固件升级页面上传软件升级包，详情请参考软固件包上传。 通过API接口创建的OTA升级包，只支持MQTT协议设备升级。 升级包为OBS对象时，无论OBS桶是否配置了CDN域名加速功能，下发的升级包链接都为OBS链接地址。

消息结构 字段名 字段类型 描述和要求 起始标识 WORD 起始标识，固定为0XFFFE。 版本号 BYTE 高四位预留；低四位表示协议版本号，当前为1。 消息码 BYTE 标识物联网平台与设备之间的请求消息类型，应答消息的消息码和请求消息相同。消息码的定义为： 0-18：预留消息码，暂未使用。 19：查询设备版本。 20：下载新版本软件包通知。 21：请求下载升级包。 22：上报升级包下载结果。 23：执行软件升级。 24：上报升级结果。 25-127：预留消息码，暂未使用。 校验码 WORD 从起始标识到数据区的最后一个字节的CRC16校验值，计算前先把校验码字段置为0，计算完成后把结果写到校验码字段。 说明： CRC16算法：CRC16/CCITT x16+x12+x5+1 数据区长度 WORD 数据区的长度。 数据区 BYTE[n] 可变长度，具体由各个指令定义，可参考下面介绍的各个指令对应的请求消息和应答消息定义。

PCP消息识别 由于PCP协议消息和设备业务消息共用一个端口和URL通讯，平台收到设备的消息时，按照如下步骤判断是PCP协议消息还是业务消息： 检查设备是否支持软件升级（根据设备profile的omCapability.upgradeCapability定义），如果不支持，则认为是业务消息。 检查设备软件升级协议是否是PCP，如果不是，则认为是业务消息。 检查消息前两个字节是否为0XFFFE，如果不是，则认为是业务消息。 检查版本号是否合法，如果不合法，则认为是业务消息。 检查消息码是否合法，如果不合法，则认为是业务消息。 检查校验码是否正确，如果不正确，则认为是业务消息。 检查数据区长度是否正确，如果不正确，则认为是业务消息。 如果以上检查都通过，认为是PCP协议消息。 对设备的要求：需要设备保证业务消息的起始字节不是0XFFFE。

响应示例 状态码： 400 Bad Request 示例 1 { "error_code" : "GSL.00020004", "error_msg" : "参数异常"} 示例 2 { "error_code" : "GSL.00027005", "error_msg" : "登录用户没有自定义属性的访问权限。"} 状态码： 500 Internal Server Error { "code" : "GSL.00020003", "message" : "系统繁忙，请稍后重试。"}

URI GET /v1/attributes 表1 Query参数 参数 是否必选 参数类型 描述 cust_attr_name 否 String 自定义属性名称 最大长度：32 limit 否 Long 分页查询时每页显示的记录数，默认值为10，取值范围为10-500的整数 最小值：10 最大值：500 缺省值：10 offset 否 Long 分页查询时的页码数，默认值为1，取值范围为1-1000000的整数 最小值：1 最大值：1000000 缺省值：1 status 否 Integer 自定义属性状态：0 未启用，1 已启用。 最小值：0 最大值：1

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 limit Long 每页记录数 offset Long 页码 count Long 记录总数 attributes Array of CmAttributeVO objects 自定义属性记录 表3 CmAttributeVO 参数 参数类型 描述 id Long 自定义属性标识 default_attr_name_cn String 默认属性名称中文 最大长度：32 default_attr_name_en String 默认属性名称英文 最大长度：32 cust_attr_name String 自定义属性名称 最大长度：32 status Integer 自定义属性状态：0 未启用，1 已启用。 create_time String 创建时间 modify_time String 更新时间 状态码： 400 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512 状态码： 500 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512

响应示例 状态码： 400 Bad Request 示例 1 { "error_code" : "GSL.00020004", "error_msg" : "参数异常"} 示例 2 { "error_code" : "GSL.00027001", "error_msg" : "自定义属性名称不合法，请检查！"} 示例 3 { "error_code" : "GSL.00027002", "error_msg" : "自定义属性名称已存在，请重新输入！"} 示例 4 { "error_code" : "GSL.00027003", "error_msg" : "自定义属性名称和SIM卡管理列字段重复，请重新输入！"} 示例 5 { "error_code" : "GSL.00027004", "error_msg" : "登录用户最多可以创建6个自定义属性。"} 状态码： 500 Internal Server Error { "code" : "GSL.00020003", "message" : "系统繁忙，请稍后重试。"}

响应示例 状态码： 400 Bad Request 示例 1 { "error_code" : "GSL.00020004", "error_msg" : "参数异常"} 示例 2 { "error_code" : "GSL.00027005", "error_msg" : "登录用户没有自定义属性的访问权限。"} 状态码： 500 Internal Server Error { "code" : "GSL.00020003", "message" : "系统繁忙，请稍后重试。"}

响应示例 状态码： 200 OK { "id" : 1000001} 状态码： 400 Bad Request 示例 1 { "error_code" : "GSL.00020004", "error_msg" : "参数异常"} 示例 2 { "error_code" : "GSL.00027001", "error_msg" : "自定义属性名称不合法，请检查！"} 示例 3 { "error_code" : "GSL.00027002", "error_msg" : "自定义属性名称已存在，请重新输入！"} 示例 4 { "error_code" : "GSL.00027003", "error_msg" : "自定义属性名称和SIM卡管理列字段重复，请重新输入！"} 示例 5 { "error_code" : "GSL.00027004", "error_msg" : "登录用户最多可以创建6个自定义属性。"} 状态码： 500 Internal Server Error { "code" : "GSL.00020003", "message" : "系统繁忙，请稍后重试。"}

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 id Long 自定义属性标识 状态码： 400 表3 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512 状态码： 500 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512

SIM卡管理 API 说明 查询SIM卡列表 查询公有云租户下的SIM卡列表。 SIM卡单卡停机 创建停机申请，返回业务受理单号。1~2个工作日完成停机操作。 SIM卡单卡复机 创建复机申请，返回业务受理单号。1~2个工作日完成复机操作。 月用量统计 查看历史月流量，可以查看最多6个月的月用量。 查询SIM卡详情 查询SIM卡的详情信息。 激活实体卡 创建激活实体卡申请，返回业务受理单号。1~2个工作日完成激活操作。 查询SIM卡实名认证信息 实时查询SIM卡实名认证信息，接口仅支持查询中国大陆运营商卡片的实名认证信息。 SIM卡申请断网/恢复在用 SIM卡申请断网/恢复在用，仅支持电信卡调用接口。 SIM卡达量断网/取消达量断网 SIM卡达量断网/取消达量断网，仅支持中国电信的卡和中国联通、中国移动的组池卡调用接口。 SIM卡机卡重绑 支持固定机卡重绑（需要上传IMEI，将SIM卡绑定到指定IMEI的设备）和普通机卡重绑（会清除之前绑定的设备，将SIM卡绑定到正在使用的设备），接口仅支持中国电信卡和中国移动卡调用，中国电信卡单卡每月只允许重绑 2 次, 中国移动卡仅支持普通机卡重绑。 清除实名认证信息 清除实名认证信息，接口仅支持中国电信卡调用。 实体卡限速 实体卡限速接口，仅支持中国电信和中国联通实体卡调用接口。中国联通卡需要个人实名认证后才能使用限速功能。

URI GET /v1/tags 表1 Query参数 参数 是否必选 参数类型 描述 tag_name 否 String 标签名称 最大长度：256 limit 否 Long 分页查询时每页显示的记录数，默认值为10，取值范围为10-500的整数 最小值：10 最大值：500 缺省值：10 offset 否 Long 分页查询时的页码数，默认值为1，取值范围为1-1000000的整数 最小值：1 最大值：1000000 缺省值：1 status 否 Integer 标签状态，0未使用，1使用中。 最小值：0 最大值：1

响应示例 状态码： 400 Parameter Invalid 示例 1 { "code" : "GSL.00010001", "message" : "请求携带的token无效。"} 示例 2 { "code" : "GSL.00012016", "message" : "SIM卡文件不存在，请检查！"} 示例 3 { "code" : "GSL.000160051", "message" : "SIM卡数量必须介于1和500之间，请重新输入！"} 示例 4 { "code" : "GSL.000160052", "message" : "标签数量必须介于0-10之间，请重新输入！"} 示例 5 { "code" : "GSL.000160053", "message" : "以下simCardId/tagId不存在或没有操作权限，请重新输入！simCardId/tagId : [-3333, 111, 656565465]"} 示例 6 { "code" : "GSL.000160054", "message" : "以下simCardId/tagId重复，请重新输入！simCardId/tagId : [2, 3]"} 状态码： 500 Internal Server Error { "code" : "GSL.00010003", "message" : "系统繁忙，请稍后重试。"}

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 limit Long 每页记录数 offset Long 页码 count Long 记录总数 tags Array of CmTagVO objects 标签记录 表3 CmTagVO 参数 参数类型 描述 id Long 标签标识 tag_name String 标签名称 最大长度：100 status Integer 标签状态，0未使用，1使用中。 状态码： 400 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512 状态码： 500 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 最大长度：64 error_msg String 错误描述 最大长度：512

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 表2 请求Body参数 参数 是否必选 参数类型 描述 template_id 否 Long 模板id sms_content 是 String 短信内容 最大长度：1000 cids 否 Array of strings 容器ID order_id 否 Long 批次号 file_temp_id 否 Long 临时文件ID

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 limit Long 每页的记录数 最小值：10 最大值：500 offset Long 页码，最小值是1，最大值为1000000。默认值是1. 最小值：1 最大值：1000000 count Long 记录总数 最小值：0 sms_details Array of SmsSendDetailQueryVo objects 短信发送详情列表 表4 SmsSendDetailQueryVo 参数 参数类型 描述 cid String 容器ID msisdn String MSISDN 最大长度：32 sent_time String 发送时间 received_time String 接收时间 sms_status Integer 短信状态:1发送中 2.已送达 3.失败 sms_content String 短信内容 最大长度：1024

URI GET /v1/sms-send-infos/details 表1 Query参数 参数 是否必选 参数类型 描述 limit 否 Long 分页查询时每页显示的记录数，默认值为10，取值范围为10-500的整数 最小值：10 最大值：500 缺省值：10 offset 否 Long 分页查询时的页码数，默认值为1，取值范围为1-1000000的整数 最小值：1 最大值：1000000 缺省值：1 cid 否 String 容器ID start_time 否 String 开始时间 end_time 否 String 结束时间

响应示例 状态码： 200 OK 示例 1 10 示例 2 1 示例 3 1 示例 4 [ { "cid" : "11669563150033768257", "msisdn" : "861400190692085", "sent_time" : "2022-03-22T00:00:00.000+00:00", "received_time" : "2022-03-22T00:00:00.000+00:00", "sms_status" : 2, "sms_content" : "testadd321"} ]

响应示例 状态码： 200 OK { "iccid" : "898600xxxxxxxxxxxxxx", "real_named" : false} 状态码： 400 Parameter Invalid { "code" : "GSL.00010004", "message" : "参数异常"} 状态码： 500 Internal Server Error { "code" : "GSL.00010003", "message" : "系统繁忙，请稍后重试。"}

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 iccid String ICCID real_named Boolean 是否已实名认证: true表示是，false表示否。 状态码： 400 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码： 500 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

错误码 当您调用API时，如果遇到“APIGW”开头的错误码，请参见API网关错误码API网关错误码进行处理。 状态码 错误码 错误信息 描述 处理措施 400 GSL.00010004 Parameter error 参数错误 请检查请求的参数是否符合API文档的要求。 400 GSL.00011001 The SIM card does not exist or you do not have the permission to access the SIM card. sim卡不存在或没有SIM卡的访问权限！ 请检查ICCID以及该卡是否属于当前账号。 400 GSL.00011010 The number of iccids exceeds the upper limit. iccid 超过个数限制。 请减少ICCID 个数。 400 GSL.00011011 The iccid:[898604031020702XXXX] does not exist. iccid:[898604031020702XXXX] 不存在 请检查SIM卡ICCID。 400 GSL.00011016 Unsupported rate limit 不支持的限制速率 请检查限制速率是否符合API文档的要求。 400 GSL.00012002 The package ID is invalid. The package does not exist. 传入的套餐ID无效，套餐不存在。 请检查套餐ID。 400 GSL.00012016 SIM card file does not exist, please cheak! SIM卡文件不存在，请检查！ 请输入有效的临时文件。 400 GSL.00013012 The SIM card corresponding to the order does not exist and cannot be renewed. Please check. 您操作的订单对应的SIM卡不存在，不能续费，请检查！ 请检查操作的订单是否存在该SIM卡。 400 GSL.00016051 The number of SIM cards list exceeds the limit （1-500）, please check! SIM卡数量必须介于1和500之间，请重新输入！ 请检查输入的SIM卡列表数量。 400 GSL.00016052 The number of tags list exceeds the limit （0-10）, please check! 标签数量必须介于0-10之间，请重新输入！！ 请检查输入的标签列表的数量。 400 GSL.00016053 Below {0} does not exist or no permission, please check! {0} : {1} 以下{0}不存在或没有操作权限，请重新输入！{0} : {1} 请检查相应的simCardId/tagId。 400 GSL.00016054 Below {0} duplicate, please check! {0} : {1} 以下{0}重复，请重新输入！{0} : {1} 请检查相应的simCardId/tagId。 400 GSL.00022001 Tag name illegal, please enter another name! 标签名称不合法，请检查！ 请重新输入标签。 400 GSL.00022002 Tag name already exists, please enter another name! 标签名称已存在，请重新输入！ 请重新输入标签。 400 GSL.00022003 A user can create up to 200 Tags. 登录用户最多可以创建200个标签。 请检查已有标签数量。 400 GSL.00022004 The login user does not have the permission to access the tag. 登录用户没有标签的访问权限。 请检查输入标签是否有效。 400 GSL.00027001 Invalid custom attribute name, please check! 自定义属性名称不合法，请检查！ 请输入其他自定义属性名称，仅支持中文、大小写英文、数字、或者特殊符号'-'和'_'。 400 GSL.00027002 Custom attribute name already exists, please enter another name! 自定义属性名称已存在，请重新输入！ 请输入其他自定义属性名称。 400 GSL.00027003 Custom attribute name cannot be same with SIM cards list column names, please enter another name! 自定义属性名称和SIM卡管理列字段重复，请重新输入！ 请检查输入的自定义属性名称，不能与已有SIM卡管理列字段重复。 400 GSL.00027004 A user can create up to 6 custom attributes. 登录用户最多可以创建6个自定义属性。 创建的自定义属性名不能超过6个。 400 GSL.00027005 The login user does not have the permission to access the custom attribute. 登录用户没有对应自定义属性的访问权限。 请检查输入的自定义属性是否有效。 403 GSL.00010001 The token carried in the request is invalid. 请求携带的token无效。 请检查携带的Token是否有效。 403 GSL.00010002 The user has been frozen and cannot invoke the API. 用户已被冻结，无法调用API。 请检查是否欠费。 403 GSL.00011004 Invalid bill cycle. Please check. 账期不合法，请检查！ 请检查账期格式和账期范围 403 GSL.00011005 The name already exists. Please enter another name. 名称已存在，请重新输入！ 名称已存在，请输入一个新的名称。 403 GSL.00011007 A query service has been delivered. Please try again later. 当前已有查询业务下发，请稍后重试！ 当前已有查询业务下发，请稍后重试！ 403 GSL.00011012 The order you are operating is in the unfinished state and cannot be renewed. Please check. 您操作的订单处于未完成状态，不能续费，请检查！ 未完成状态的订单不能续费。 403 GSL.00011015 The current SIM card does not support the operation. 当前SIM卡不支持操作 受运营商限制，不允许当前操作 403 GSL.00011019 The task_type of the export task is incorrect. 导出任务task_type不对！ 导出任务task_type不对！ 403 GSL.00012003 You do not have the permission to operate the test package. 您没有权限操作测试套餐。 您没有权限操作测试套餐。 403 GSL.00013011 The order you operate has unfinished renewal orders and cannot be renewed. Please check. 您操作的订单仍有未完成的续费订单，不能续费，请检查！ 操作的订单仍有未完成的续费订单，不能续费。 403 GSL.00014003 The traffic pool you want to operate does not exist. Please check. 您操作的流量池不存在，请检查！ 请检查所操作的流量池是否存在。 403 GSL.00016009 The card you operate has unfinished resumption orders. Do not perform the operation again. 您操作的卡仍有未完成的复机受理单，请勿重复操作。 您操作的卡仍有未完成的复机受理单，请等待受理完毕。 403 GSL.00016010 The card you operate has pending suspension orders. Do not perform the operation again. 您操作的卡仍有未完成的停机受理单，请勿重复操作。 您操作的卡仍有未完成的停机受理单，请等待受理完毕。 403 GSL.00016012 The card you operate is suspended due to excessive traffic and cannot be resumed. 您操作的卡，超流量停机，无法发起复机操作。 请购买流量叠加包或联系工作人员处理 403 GSL.00016014 Failed to activate the card because the card status is {0}. 您操作的卡状态已为{0}，无法发起激活操作。 当前卡不支持激活操作。 403 GSL.00016015 The card you operate has pending activation orders. Do not perform the operation again. 您操作的卡仍有未完成的激活受理单，请勿重复操作。 您操作的卡仍有未完成的激活受理单，请等待受理完毕。 403 GSL.00016016 Repeated operations are not allowed within 5 minutes. Please wait. 5分钟内不允许重复操作，请稍作等待。 5分钟内不允许重复操作，请稍作等待。 403 GSL.00016019 You cannot resume the card because the card is not in the disabled state. 您操作的卡状态非停用，无法发起复机操作。 只有停用状态的卡，才能发起复机操作。 403 GSL.00016020 The card you are operating is not in use and cannot initiate this operation 您操作的卡状态非在用，无法发起该操作。 只有在用状态的卡，才能发起停机操作。 500 GSL.00010003 The system is busy. Please try again later. 系统繁忙，请稍后重试！ 系统繁忙，请稍后重试！ 500 GSL.00010005 Service operation failed. 业务操作失败 业务操作失败，请稍后重试！ 500 GSL.00011009 File not exists. 上传文件不存在。 上传文件不存在。 500 GSL.00016005 Unsupported business handling order 不支持的业务受理单 请检查当前业务受理类型

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 sim_card_id Long sim卡id account_id String 账户id cid String 容器ID:不同类型卡含义如下 iccid(实体卡)，eid（eSIM）cid（vSIM) sim_pool_id Long 流量池ID imei String 设备IMEI sim_status Integer sim卡状态： 10.可测试 11.未激活 13.可激活 14.已停用 20.在用 30.已拆机 device_status Integer 设备状态 device_model String 设备模组 act_date String 激活日期 例如2020-01-31T16:00:00.000Z device_status_date String 设备状态变更时间 例如2020-01-31T16:00:00.000Z node_id String 设备标识 iccid String 码号iccid network_type String 网络类型 dbm String 信号强度 signal_level String 信号等级:1.差 2.良 3.良 4.优（该参数只有eSIM,vSIM返回，实体卡不返回） sim_type Integer sim卡类型 1.vSIM 2.eSIM 3.实体卡 tag_names String 标签名 order_id Long 批次号 expire_time String 到期时间 例如2021-06-30T00:00:00.000Z price_plan_name String 在用套餐名 最大长度：128 sim_price_plan_id Long 套餐订购实例ID flow_left Double 剩余流量(单位M)，数据默认截止到昨日24点。 flow_used Double 已用流量(单位M)，数据默认截止到昨日24点。 operator_status Integer 运营商状态 -1.正常（非停机状态） 1.停机（超流量停机） 2.停机（超流量阈值停机） 3.停机（流量池停机） 4.停机（套餐到期停机） 5.停机（主动停机） 6.停机（违规停机） 7.停机（机卡分离停机） msisdn String MSISDN 最大长度：32 imsi String IMSI 最大长度：32 customer_attribute1 String 自定义属性一 最大长度：100 customer_attribute2 String 自定义属性二 最大长度：100 customer_attribute3 String 自定义属性三 最大长度：100 customer_attribute4 String 自定义属性四 最大长度：100 customer_attribute5 String 自定义属性五 最大长度：100 customer_attribute6 String 自定义属性六 最大长度：100 real_named Boolean 是否已实名认证: true表示是，false表示否，系统SIM卡实名认证状态非实时。 cut_net_flag Boolean 是否单独断网 true:断网，false:未断网 （当前只支持联通、移动的组池卡，电信卡不限制） exceed_cut_net_flag Boolean 是否达量断网 true:达量断网，false:未达量断网 （当前只支持联通、移动的组池卡，电信卡不限制） exceed_cut_net_quota Integer 达量断网阈值（单位MB 当前仅电信卡支持） imei_bind_remain_times Integer 本月机卡绑定剩余次数（当前仅电信卡支持） speed_value Integer 网络限制速率（单位Kbps,当前电信联通卡支持） 状态码： 400 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码： 500 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

响应示例 状态码： 200 OK { "sim_card_id" : 10000000000000000, "account_id" : "04eexxxxxxxxx", "cid" : "8986xxxxxxxxxxxxxxxxxxxx", "sim_pool_id" : 10000000000000000, "imei" : null, "sim_status" : 14, "device_status" : null, "device_model" : null, "act_date" : "2022-09-16T01:14:58.000+00:00", "device_status_date" : null, "node_id" : null, "iccid" : "8986xxxxxxxxxxxxxxxx", "network_type" : null, "dbm" : null, "signal_level" : null, "sim_type" : 3, "tag_names" : null, "order_id" : 10000000000000000, "expire_time" : "2023-08-26T15:59:59.000+00:00", "price_plan_name" : "中国联通消费级每月10M联接服务（1年）", "sim_price_plan_id" : 10000000000000000, "flow_left" : 10, "flow_used" : 0, "operator_status" : 5, "msisdn" : "86xxxxxxxx", "imsi" : "46xxxxxxxx", "customer_attribute1" : null, "customer_attribute2" : null, "customer_attribute3" : null, "customer_attribute4" : null, "customer_attribute5" : null, "customer_attribute6" : null, "real_named" : false, "cut_net_flag" : false, "exceed_cut_net_flag" : false, "exceed_cut_net_quota" : null, "imei_bind_remain_times" : null, "speed_value" : null} 状态码： 400 Parameter Invalid { "error_code" : "GSL.00010004", "error_msg" : "参数异常"} 状态码： 500 Internal Server Error { "error_code" : "GSL.00010003", "error_msg" : "系统繁忙，请稍后重试。"}