跳到主要内容

节点共享

你可以将节点的访问权限共享给其他用户，实现设备协同管理。

概览​

RainMaker 中的节点共享可以实现以下功能：

  • 与其他用户共享节点。
  • 对特定用户取消共享。
  • 将节点所有权转移给其他用户。

共享节点​

使用 shareWith 方法将节点共享给其他用户。

try {
  const shareRequest = {
    username: "target_username",
    makePrimary: false,
    metadata: {
      description: "Shared for home automation access",
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Node sharing request created:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

ShareWithRequest 接口​

shareWith 方法需要使用 ShareWithRequest 对象，且包含以下属性：

属性类型必填说明
username*字符串是要共享节点的目标用户名称。
makePrimary布尔值否是否将被共享用户设为主用户。
metadataRecord<string, any>否与共享请求关联的可选元数据。

示例：基础共享​

try {
  const shareRequest = {
    username: "family_member@example.com",
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Sharing request created with ID:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

示例：共享节点并将被共享者设为主用户​

try {
  const shareRequest = {
    username: "admin@example.com",
    makePrimary: true,
    metadata: {
      role: "administrator",
      accessLevel: "full",
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Node shared as primary user:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

示例：携带元数据的共享​

try {
  const shareRequest = {
    username: "guest@example.com",
    makePrimary: false,
    metadata: {
      purpose: "temporary_access",
      expiryDate: "2024-12-31",
      permissions: ["read", "control"],
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Node shared with metadata:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

取消共享​

使用 removeSharingFor 方法为指定用户取消共享当前节点。

try {
  const username = "target_username";
  const response = await node.removeSharingFor(username);
  console.log("Sharing removed successfully:", response);
} catch (error) {
  console.error("Error removing sharing:", error);
}

removeSharingFor API​

参数类型说明
username*字符串要为其取消共享的目标用户名。

返回：Promise<ESPAPIResponse> – 成功移除共享后解析为成功响应的 Promise。

示例：取消共享​

try {
  const username = "former_user@example.com";
  const response = await node.removeSharingFor(username);

  if (response.status === "success") {
    console.log("Sharing removed successfully for:", username);
  }
} catch (error) {
  console.error("Error removing sharing:", error);
}

转移节点​

使用 transferNode 方法创建转移请求，将当前节点转移给指定用户。该操作会把节点的所有权转移给另一位用户。

try {
  const transferRequest = {
    toUserName: "new_owner@example.com",
    selfToSecondary: false,
  };

  const requestId = await node.transferNode(transferRequest);
  console.log("Node transfer request created:", requestId);
} catch (error) {
  console.error("Error transferring node:", error);
}

TransferNodeRequest 接口​

transferNode 方法需要使用 TransferNodeRequest 对象，且包含以下属性：

属性类型必填说明
toUserName*字符串是接收被转移节点的目标用户名称。
selfToSecondary布尔值否转移完成后是否将当前节点所有者设为次要用户。

返回：Promise<string> – 转移请求创建成功后解析为 requestId 的 Promise。

示例：基础转移​

try {
  const transferRequest = {
    toUserName: "new_owner@example.com",
  };

  const requestId = await node.transferNode(transferRequest);
  console.log("Transfer request created with ID:", requestId);
} catch (error) {
  console.error("Error transferring node:", error);
}

示例：转移且保留当前用户为次要用户​

try {
  const transferRequest = {
    toUserName: "new_owner@example.com",
    selfToSecondary: true,
  };

  const requestId = await node.transferNode(transferRequest);
  console.log(
    "Node transfer request created. You will remain as secondary user:",
    requestId
  );
} catch (error) {
  console.error("Error transferring node:", error);
}

示例：完整的转移流程​

try {
  // 第一步：创建转移请求
  const transferRequest = {
    toUserName: "new_owner@example.com",
    selfToSecondary: false,
  };

  const requestId = await node.transferNode(transferRequest);
  console.log("Transfer request created:", requestId);

  // 注意：新的所有者需要接受节点转移请求
  // 新的所有者接受请求后，节点所有权将转移
} catch (error) {
  console.error("Error in transfer workflow:", error);
}

管理共享请求​

可使用 ESPNodeSharingRequest 类管理节点共享请求。共享请求分为两类：

  • 收到的请求：其他用户发送给你的邀请。
  • 发出的请求：你发送给其他用户的邀请。

获取收到的节点共享请求​

使用 getReceivedNodeSharingRequests 方法获取发送给你的节点共享请求（即你收到的邀请）。

try {
  // 获取所有收到的分享请求（使用分页）
  const response = await user.getReceivedNodeSharingRequests();

  console.log("Received requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error fetching received requests:", error);
}

getReceivedNodeSharingRequests API​

参数类型必填说明
resultCount数值否每次请求后获取的结果数量，未提供时将使用默认值。

返回：Promise<ESPNodeSharingResponse> – 返回包含收到的分享请求的分页响应对象。

获取发出的节点共享请求​

使用 getIssuedNodeSharingRequests 方法获取发送给其他用户的节点共享请求。

try {
  // 获取所有发出的分享请求（使用分页）
  const response = await user.getIssuedNodeSharingRequests();

  console.log("Issued requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error fetching issued requests:", error);
}

getIssuedNodeSharingRequests API​

参数类型必填说明
pageCount数值否每次请求后获取的结果数量，未提供时将使用默认值。

返回：Promise<ESPNodeSharingResponse> – 返回包含发出的分享请求的分页响应对象。

接受共享请求​

使用 accept 方法接受发送给你的节点共享请求。

try {
  // 获取接受的共享请求
  const response = await user.getReceivedNodeSharingRequests();
  const receivedRequests = response.sharedRequests;

  // 查找并接受特定的请求
  const requestToAccept = receivedRequests.find((req) => req.id === requestId);

  if (requestToAccept) {
    const acceptResponse = await requestToAccept.accept();
    console.log("Sharing request accepted:", acceptResponse);
  }
} catch (error) {
  console.error("Error accepting sharing request:", error);
}

accept API​

返回：Promise<ESPAPIResponse> – 成功接受后解析为成功响应的 Promise。

注意

用户只能接受共享给自己的邀请（收到的请求）。

拒绝共享请求​

使用 decline 方法拒绝发送给你的节点共享请求。

try {
  // 获取接受的共享请求
  const response = await user.getReceivedNodeSharingRequests();
  const receivedRequests = response.sharedRequests;

  // 查找并拒绝特定的请求
  const requestToDecline = receivedRequests.find((req) => req.id === requestId);

  if (requestToDecline) {
    const declineResponse = await requestToDecline.decline();
    console.log("Sharing request declined:", declineResponse);
  }
} catch (error) {
  console.error("Error declining sharing request:", error);
}

decline API​

返回：Promise<ESPAPIResponse> – 成功拒绝后解析为成功响应的 Promise。

注意

用户只能拒绝共享给自己的邀请（收到的请求）。

移除共享请求​

使用 remove 方法移除之前发送给其他用户的节点共享请求。发送方可用此方法取消处于待处理状态的共享请求。

try {
  // 获取发出的共享请求
  const response = await user.getIssuedNodeSharingRequests();
  const issuedRequests = response.sharedRequests;

  // 找到并移除特定的请求
  const requestToRemove = issuedRequests.find((req) => req.id === requestId);

  if (requestToRemove) {
    const removeResponse = await requestToRemove.remove();
    console.log("Sharing request removed:", removeResponse);
  }
} catch (error) {
  console.error("Error removing sharing request:", error);
}

remove API​

返回：Promise<ESPAPIResponse> – 成功移除后解析为成功响应的 Promise。

注意

用户只能移除由自己发出的请求（发出的请求）。

示例：完整的共享请求流程​

以下示例展示发送方与接收方如何管理共享请求：

// ==================== 发送方 ====================

// 步骤一：发送方共享节点
try {
  const shareRequest = {
    username: "recipient@example.com",
    makePrimary: false,
    metadata: {
      description: "Sharing smart home device",
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Sharing request sent with ID:", requestId);
} catch (error) {
  console.error("Error sending sharing request:", error);
}

// 步骤二：发送方可以检查自己发出的请求
try {
  const response = await user.getIssuedNodeSharingRequests();
  console.log("My issued requests:", response.sharedRequests);

  // 发送方可以在接收方接受请求前取消共享
  const requestToCancel = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (requestToCancel) {
    await requestToCancel.remove();
    console.log("Sharing request cancelled");
  }
} catch (error) {
  console.error("Error managing issued requests:", error);
}

// ==================== 接收方 ====================

// 步骤一：接收方检查收到的共享请求
try {
  const response = await user.getReceivedNodeSharingRequests();
  console.log("Received sharing requests:", response.sharedRequests);

  // 找到特定的请求
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    console.log("Found sharing request from:", incomingRequest.username);
    console.log("Metadata:", incomingRequest.metadata);
  }
} catch (error) {
  console.error("Error fetching received requests:", error);
}

// 步骤二：接收方接受共享请求
try {
  const response = await user.getReceivedNodeSharingRequests();
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    const acceptResponse = await incomingRequest.accept();
    console.log("Sharing request accepted:", acceptResponse);

    // 接收方现在拥有节点权限
    console.log("Node access granted");
  }
} catch (error) {
  console.error("Error accepting sharing request:", error);
}

// 或者：接收方拒绝共享请求
try {
  const response = await user.getReceivedNodeSharingRequests();
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    const declineResponse = await incomingRequest.decline();
    console.log("Sharing request declined:", declineResponse);
  }
} catch (error) {
  console.error("Error declining sharing request:", error);
}

示例：通过分页管理已发出的请求​

通过分页获取并管理已发出的请求：

try {
  // 获取已发出的请求，使用分页（每页 10 条）
  const response = await user.getIssuedNodeSharingRequests(10);

  console.log(`Has more requests: ${response.hasNext}`);
  console.log(`Showing ${response.sharedRequests.length} requests`);

  // 显示所有已发出的请求
  response.sharedRequests.forEach((request, index) => {
    console.log(`${index + 1}. Request to: ${request.username}`);
    console.log(`   Node IDs: ${request.nodeIDs.join(", ")}`);
    console.log(`   Status: ${request.status}`);
  });

  // 删除超过 7 天的待处理请求
  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;

  for (const request of response.sharedRequests) {
    if (request.status === "pending" && request.timestamp < sevenDaysAgo) {
      await request.remove();
      console.log(`Removed old request to ${request.username}`);
    }
  }

  // 如果有下一页，则获取
  if (response.hasNext && response.fetchNext) {
    const nextResponse = await response.fetchNext();
    console.log(`Fetched ${nextResponse.sharedRequests.length} more requests`);
  }
} catch (error) {
  console.error("Error managing issued requests:", error);
}

On this page