记得在很小的时候,还在上小学的时候,每年三月五号学校大扫除,就会整个班级聚集到一起,然后听从班主任的分配,将大家分成几个小组,从事不同的劳动,擦玻璃的,扫厕所的,拖地的。。。;长大后,渐渐接触到一些学习小组,兴趣小组。。。;而小组的概念通常也理解为一些从事相同或相似工作或操作的人的集合;而在提供产品管理和设备管理之外,阿里云IOT也引入了小组的概念,从而提供了分组管理的操作,对于设备分小组的意思通常的理解是物理上,位置和距离相近的一些设备和产品,然后对这些设备和产品进行类似的操作,方便管理。目前提供分组管理的操作通常的理解有创建,更新,查找和删除,另外还有些小组标签的创建和查找接口。下面我们逐一来进行介绍。本次的实验软件验证如下:
http://xysuger.xunyun17.xyz/v0.0.6.rar
读者如果感兴趣的话,可以自行下载运行验证;
第一个接口是创建小组,借口命令CreateDeviceGroup,就是英文直译的名字,容易理解。后面带有一个创建小组名称的参数;这个参数的要求是长度在4到30个字符,字符的意思是包括英文,数字和下划线;我们作为例子,用下面的命令创建一个小组名称为LampGroup的分组;
XYsayFrO.IoT.Srv.CreateDeviceGroup.LampGroup.
返回的结果如下图:
这里返回的结果里有四个参数:前两个分别是小组名称和小组的详细描述;第三个是小组的ID标识符,这个需要记下来,因为后续关于小组的更多的操作都是需要这个小组标识符来作为参数的,才可以进行正常操作的;最后一个参数是小组的创建时间,这个时间是UTC时间,和我们常用的北京时间不一样,差8个小时,所以要转换成北京时间就还需要再加上8个小时,也就是说这个小组的创建时间是早上八点二十八分创建的。
成功创建好一个小组后,我们就可以对这个小组进行更新,主要是小组描述的更新,比如默认的描述是Create_By_XYsuger,我们可以改为This_Is_A_Lamp_Group,是用到的更新命令是:UpdateDeviceGroup,后面带有两个参数,一个是小组的ID标识符,另外一个是要更新后的小组描述信息,所以完成命令如下:
XYsayFrO.IoT.Srv.UpdateDeviceGroup.pKdhc1c3goE3DVkbAskM010200.This_Is_A_Lamp_Group.
当更新成功后,会在返回结果的Success里返回true的值;
更新接口介绍完后,是查询小组信息的接口,命令是QueryDeviceGroupInfo,带有的一个参数的含义是要查询小组的id标识符,所以命令如下:
XYsayFrO.IoT.Srv.QueryDeviceGroupInfo.pKdhc1c3goE3DVkbAskM010200.
运行后,截图如下:
从这里的返回结果,可以看到GroupDesc小组描述的信息,已经有我们上一个更新命令,更改成为This_Is_A_Lamp_Group了;而出了上次介绍的四个返回信息外,还有三个设备相关的状态信息,分别是设备上线的个数,设备激活的个数,和设备总数;由于我们目前只是创建了小组,还没有添加设备,所以暂时三个返回的个数都为0;
查询完小组信息后,我们以后就可以根据具体实际情况,来决定是否删除无用或者废弃的小组,使用的接口名称为DeleteDeviceGroup,传入的唯一一个参数,就是要被删除小组的小组id标识符,所以完成的命令如下所示:
XYsayFrO.IoT.Srv.DeleteDeviceGroup.pKdhc1c3goE3DVkbAskM010200.
当删除返回正确时,可以在使用小组查询命令确认一下:
XYsayFrO.IoT.Srv.QueryDeviceGroupInfo.pKdhc1c3goE3DVkbAskM010200.
从上面的返回结果,可以看到相关信息都为空的,所以可以证明我们刚才删除操作时被正确执行了的;
介绍完,小组的创建,查询和删除,现在开始介绍如何向小组中添加设备,因为毕竟小组是一个抽象的概念,只有小组内有了真真正正的设备,对小组的操作才有实际意义;
添加设备的命令为BatchAddDeviceGroupRelations,目前支持一次添加两个设备。所有后面的四个参数分别为第一个设备的设备名称和产品标识符,以及第二个设备的设备名称和产品标识符,这里将以前创建的两个设备lamp3_dev1和lamp3_dev同时添加到刚刚创建的小组中,完整命令如下:
XYsayFrO.IoT.Srv.BatchAddDeviceGroupRelations.pKdhc1c3goE3DVkbAskM010200.lamp3_dev1.a141rgUXgFl.lamp3_dev.a141rgUXgFl.
成功运行上面的命令后,会返回,正确添加设备的个数为2;再用下面的查询小组信息的命令查询确认一下:
XYsayFrO.IoT.Srv.QueryDeviceGroupList.pKdhc1c3goE3DVkbAskM010200.
可以看到返回的结果截图中,在这个小组中,设备的总数是2,激活的设备个数是1,上线的设备个数是0。和我们添加的操作预计结果一致;
查询在小组内添加设备正确后,可以通过BatchDeleteDeviceGroupRelations接口,移除添加到小组中的设备:
XYsayFrO.IoT.Srv.BatchDeleteDeviceGroupRelations.Wmhlen9xz5XAFE85XnrP010200.lamp3_dev1.a141rgUXgFl.lamp3_dev.a141rgUXgFl.
然后再通过下面的命令查询一下最新的小组设备数量,从而确认删除的是否成功;
XYsayFrO.IoT.Srv.QueryDeviceGroupList.pKdhc1c3goE3DVkbAskM010200.
在返回的信息中,可以看到设备数量又变回0了,表示刚才的删除操作是正确运行的;
开始曾提到小组也有标签的操作,这里介绍下设置小组标签的接口,SetDeviceGroupTags,后面的三个参数,分别为小组标识符,小组标签的类型和小组标签的值;这里给小组设置一个表示生产序列的类型,类型名为Serial,类型的值为8月August,所以完整的命令语句如下:
XYsayFrO.IoT.Srv.SetDeviceGroupTags.Wmhlen9xz5XAFE85XnrP010200.Serial.August.
创建成功后,可以通过查询小组标签的命令QueryDeviceGroupTagList,再加上一个小组的标识符,来确认刚刚设置小组标签的操作成功与否:
XYsayFrO.IoT.Srv.QueryDeviceGroupTagList.Wmhlen9xz5XAFE85XnrP010200.
从上图可以看到,小组的tagkey也就是类型名为Serial,而tagvalue也就是类型值为August,这就表示刚才设置的小组标签操作时正确执行的;
关于小组的接口,除了通过小组标识符来查询小组信息,阿里云iot额外还提供了通过设备信息查询小组信息的操作,这给小组的管理人员提供了更加灵活的操作;通过设备查询小组的接口名称为QueryDeviceGroupByDevice,后面的两个参数为产品关键字和设备名称,这里以上次创建好的设备为例子查询,命令如下:
XYsayFrO.IoT.Srv.QueryDeviceGroupByDevice.a141rgUXgFl.lamp3_dev1.
可以从返回的信息中看到,我们查到小组信息,正是添加这个设备的小组信息;
再回到最开始创建小组的地方,这里考虑到有可能以后设备会非常多,所以创建的小组也会非常多,就会出现一个小组下面可能有多个子小组的可能情况会发生,那么这里就有提供一个创建子小组的接口,这个接口的操作,后面的参数除了像正常创建小组时,提供小组名称作为参数以外,还需要提供一个父小组标识符的参数,以方便表示需要在这个父小组下面创建子小组,举例如下,在最开始创建的小组下面,在创建一个小组名称为SubLampGroup的子小组,具体命令为:
XYsayFrO.IoT.Srv.CreateDeviceGroup.SubLampGroup.Wmhlen9xz5XAFE85XnrP010200.
返回的信息和创建子小组的信息类似,也是四个参数:小组名称,小组描述,小组标识符和小组创建时间;
一旦提供了创建子小组的操作,就有可能存在通过子小组查找父小组的操作,这里用QuerySuperDeviceGroup接口命令,演示一下,如何查询,这个接口带有一个参数,为要查询小组的标识符:
XYsayFrO.IoT.Srv.QuerySuperDeviceGroup.9GzEcN2jVUqcmIrxJDgb010200.
这里返回的信息中,可以看到,一共返回三个参数,父小组的小组名称,小组描述和小组标识符;
下面介绍一个相对有用的操作,通过小组标识符,来查询小组内设备的操作,这个操作只需要带入小组的标识符即可:
XYsayFrO.IoT.Srv.QueryDeviceListByDeviceGroup.Wmhlen9xz5XAFE85XnrP010200.
这个操作返回了目前这个要查询的小组里,一共有两个设备,而且也显示了每个设备的设备名称,产品名称,产品关键字以及相关联的物联网标示符;
最后一个接口操作是根据标签查询小组信息,这个应该属于刚才标签操作一类的,当时漏掉了,算是后面再补上吧;这个操作两个参数,一个是标签类型名,一个是标签类型值,以刚才的标签为例子,查询命令如下:
XYsayFrO.IoT.Srv.QueryDeviceGroupByTags.Serial.August.
从上图可以看到,这个标签所在小组的小组名称和小组标识符;
这次关于小组的操作就介绍到这里;一共13中操作,涵盖了小组操作过程中的各种相关接口;希望读者了解后,对今后阿里云iot设备的操作更加灵活和方便;