跳到主要内容

群组共享与节点群组

概述

ESP RainMaker 节点群组功能可高效组织管理物联网设备。

什么是节点群组？
节点群组是节点的逻辑集合，支持按位置（如“客厅设备”）、功能（如“所有灯具”）或元数据（如“型号：X123”）分类。

  • 支持静态群组（明确列出的节点）和动态群组（基于节点型号/类型/固件）。
  • 支持三级层级分组：群组可包含子群组（最多三层嵌套）。

什么是群组共享？
群组共享通过与他人共享节点实现多用户协作，允许他人访问同一物理节点群组，提供两种权限：

  • 主要权限-完全控制：可更新/删除/二次共享。
  • 次要权限-受限控制：仅支持查看和基础操作。

核心功能：

  • 节点的层级化组织。
  • 基于节点属性（类型/型号/固件版本）的动态分组。
  • 多用户间的节点控制与共享。
  • 支持 Matter 协议设备（节点）。
  • 管理员与用户级群组管理。

使用场景​

节点群组解决了物联网设备管理中的多个关键问题：

使用场景说明
设备归类按房间/功能/位置逻辑组织节点。
批量操作同时对多个节点执行操作。
权限控制分级共享节点访问权限。
动态管理根据节点属性自动分组。
Matter 集成兼容 Matter 协议设备与 RainMaker 设备。
OTA 管理高效执行群组固件更新。

功能实体​

用户角色​

管理员用户​

可创建和管理管理员节点群组。

终端用户​

可创建和管理用户节点群组。

  • 主要用户

    1. 设备群组所有者。
    2. 拥有完整共享设置权限。
    3. 可添加/移除次要用户
    4. 可修改共享权限。

  • 次要用户

    1. 共享接收方。
    2. 基于角色限制权限。
    3. 可查看/控制共享节点。
    4. 不可修改共享设置。

节点类型​

ESP RainMaker 注册的物联网节点（唯一 ID 标识）：

  1. RainMaker 节点：标准 ESP RainMaker 设备
  2. Matter 节点：支持 Matter 协议的设备

群组类型​

  1. 管理员群组：由管理员用户创建的群组。
  2. 用户群组：由终端用户创建的群组。
  3. Matter Fabric：用户通过 API 创建的群组，可包含 Matter 和 RainMaker 节点。
  4. 动态群组：
    • 基于分组查询的群组：仅管理员可以创建，创建时需提供 node_type、node_model 和 node_fw_version 中的一项或多项。这类群组会自动匹配现有节点配置，适用于 OTA 任务。
    • 重组功能：仅适用于基于分组查询创建的分组。当某些节点的类型、型号或固件版本发生变更时，重新分组功能会从分组中移除不符合 group_query 条件的节点，并添加新匹配节点。

使用指南​

群组共享 API​

共享群组 PUT /v1/user/node_group/sharing​

  1. 主要用户共享

    group-sharing-1

    功能：授予主要用户完全控制权。

    1. 接收方成为群组主要用户。
    2. 拥有节点完全控制权。
    3. 可继续共享群组。

  2. 次要用户共享

    group-sharing-2

    功能：仅授予查看权限。

    1. 接收方成为次用户。
    2. 仅可查看节点状态。
    3. 不可修改设置或二次共享。

  3. 转移主要权限

    group-sharing-3

    功能：完全移交群组所有权。

    1. 当前用户失去主要权限。
    2. 接收方成为新主要用户。
    3. 当前用户失去访问群组权限。

  4. 转移并保留次要权限

    group-sharing-4

    功能：移交所有权后降级为次要用户。

    1. 当前用户成为次要用户。
    2. 接收方成为主要用户。
    3. 当前用户保留查看权限。

查询共享详情 GET /v1/user/node_group/sharing​

查询类型方法端点说明
i. 基础查询GET/v1/user/node_group/sharing返回用户有权访问的所有群组（主/次要权限）。
ii. 按群组 ID 查询GET/v1/user/node_group/sharing?group_id=group_id1返回指定群组的共享详情。
iii. 包含子群组查询GET/v1/user/node_group/sharing?sub_groups=true返回含子群组的共享详情。
iv. 包含父群组查询GET/v1/user/node_group/sharing?parent_groups=true返回含父群组的共享详情。
v. 包含元数据查询GET/v1/user/node_group/sharing?metadata=true返回共享时设置的元数据。

管理共享请求​

  • 获取共享请求 GET v1/user/node_group/sharing/requests

    此 API 允许主要用户和次要用户获取共享请求信息。

    参数说明

    1. request_id：查询特定请求。
    2. primary_user：布尔值，用于指示是否获取由主要用户发起的共享请求（为 true）或次要用户接收到的请求（为 false）。该标志的默认值为 false。
    3. start_request_id：用于分页。
    4. start_user_name：与 start_request_id 一起用于分页。
    5. num_records：用于指定返回的记录数量。默认值为 10。合法取值范围为 1 到 10。如果提供了无效值，则使用默认值。

  • 接受/拒绝共享请求 PUT /v1/user/node_group/sharing/requests

    用于接受或拒绝分组共享请求。

  • 删除共享请求
    DELETE /v1/user/node_group/sharing/requests?request_id=request_id1

    删除一个待处理的共享请求。

删除节点分组 DELETE /v1/user/node_group​

该 API 可用于删除用户节点分组或 Matter Fabric（如果用户是主要用户）。它允许用户退出自己的分组/Matter Fabric，也允许主要用户取消对其他用户的共享。

参数说明

  1. group_id（必填）
  2. leave（布尔值）：
    • 主要用户或次要用户都可以设置此参数以退出分组。
    • 如果用户是该分组中唯一的主要用户，则不能通过 leave 退出，需直接删除该分组。
    • 如果分组中有多个主要用户，用户可以使用该参数退出。
    • 对于次要用户，若未显式指定该参数，则默认为 true。
  3. remove_sharing（布尔值）：应与 user_name 一起使用。
    • 用于移除对指定 user_name 的共享权限。
    • 次要用户无权执行该操作。
    • 不能对当前请求用户自身使用该参数，请使用 leave 参数替代。
    • 不能取消通过父节点组共享的权限。
    • remove_sharing 与 leave 参数不可同时使用。
  4. user_name（字符串）：需要被移除共享权限的用户的用户名。

前提条件​

  • 每个群组至少保留 1 个主要用户。
  • 单次请求最多添加 100 个节点。
  • Matter 设备仅可加入 Matter Fabric。
  • 动态群组随节点属性变更自动更新。
  • 仅管理员用户可创建动态群组。
  • 动态群组不可包含子群组。
  • 动态群组与静态群组互斥。

On this page