物联网开发平台绑定与分享

本文介绍腾讯云物联网（IoT）应用端 SDK 中家庭管理（TXIoTFamilyManager）和设备管理（TXIoTDeviceManager）相关 API 的使用方法。完成快速接入并登录 SDK 后，您可以通过本文完成家庭创建、房间管理、成员邀请、设备绑定、设备列表查询、设备分享等功能。
前提条件
在调用本文 API 前，请确保已完成以下准备工作：
已开通腾讯云物联网相关服务，并在控制台完成实例、应用和设备的准备工作。可参见 开通服务。
已在客户端工程中集成 IoT 应用端 SDK。
已通过业务后台生成登录签名，并调用 TXIoTEngine 完成登录。
如果尚未完成 SDK 集成与登录，请先参考 Android 快速接入 或 iOS 快速接入。
获取管理对象
在 Android 和 iOS 上，登录成功后，均可通过 TXIoTEngine 单例调用 getFamilyManager() 和 getDeviceManager() 获取对应的管理对象。
说明：
如果获取到的 TXIoTFamilyManager 或 TXIoTDeviceManager 为 null（iOS 为 nil），通常是因为 SDK 尚未登录或登录已过期，请先完成登录后再使用相关能力。
家庭管理
家庭是设备和成员管理的基础容器。设备绑定、设备列表查询、房间归属、家庭成员邀请等操作都需要使用 familyId。
查询或创建家庭
客户端通常先查询家庭列表。如果当前用户没有家庭，可创建一个默认家庭。创建成功后，接口返回 TXIoTFamilyInfo 结构体，请从中取出 familyId 并保存，供后续绑定设备或查询设备使用。
方法
说明
﻿getFamilyList﻿
查询当前用户的家庭列表，返回 TXIoTFamilyInfo 列表。
﻿createFamily﻿
创建家庭，返回 TXIoTFamilyInfo（含 familyId）。
Android
iOS
// 获取家庭列表
familyManager.getFamilyList(new TXIoTCallback<List<TXIoTFamilyInfo>>() {
    @Override
    public void onSuccess(List<TXIoTFamilyInfo> result) {
        if (result != null && !result.isEmpty()) {
            String familyId = result.get(0).familyId;
            // 使用 familyId 继续管理房间、成员和设备。
        }
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 查询家庭列表失败，请根据错误码和错误信息处理。
    }
});
﻿
// 创建家庭
familyManager.createFamily("我的家庭", new TXIoTCallback<TXIoTFamilyInfo>() {
    @Override
    public void onSuccess(TXIoTFamilyInfo familyInfo) {
        String familyId = familyInfo.familyId;
        // 创建成功后，可继续创建房间或绑定设备。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 创建家庭失败，请根据错误码和错误信息处理。
    }
});
// 查询家庭
TXIoTCallback<NSArray<TXIoTFamilyInfo *> *> *familyListCallback = [TXIoTCallback new];
familyListCallback.onSuccess = ^(NSArray<TXIoTFamilyInfo *> *result) {
    if (result.count > 0) {
        NSString *familyId = result.firstObject.familyId;
        // 使用 familyId 继续管理房间、成员和设备。
        return;
    }
};
familyListCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 查询家庭列表失败，请根据错误码和错误信息处理。
};
[familyManager getFamilyList:familyListCallback];
﻿
// 创建家庭
TXIoTCallback<TXIoTFamilyInfo *> *createCallback = [TXIoTCallback new];
createCallback.onSuccess = ^(TXIoTFamilyInfo *familyInfo) {
    NSString *familyId = familyInfo.familyId;
    // 创建成功后，可继续创建房间或绑定设备。
};
createCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 创建家庭失败，请根据错误码和错误信息处理。
};
[familyManager createFamily:@"我的家庭" callback:createCallback];
管理房间
房间用于对家庭下的设备进行分组。房间是可选的：设备刚绑定时默认不属于任何房间，加入房间只是为了在 App 中对设备做分组展示，不影响设备的绑定状态和功能使用。创建房间后，您可以通过设备管理接口将设备加入或移出房间。
注意：
如果您的业务不需要对设备做分组，可以跳过房间相关接口，直接绑定设备并使用设备列表。
方法
说明
﻿createRoom﻿
在指定家庭下创建房间，返回 TXIoTRoomInfo（含 roomId）。
Android
iOS
familyManager.createRoom(familyId, "客厅", new TXIoTCallback<TXIoTRoomInfo>() {
    @Override
    public void onSuccess(TXIoTRoomInfo roomInfo) {
        String roomId = roomInfo.roomId;
        // 后续可调用 addDeviceToRoom 将设备加入该房间。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 创建房间失败，请根据错误码和错误信息处理。
    }
});
TXIoTCallback<TXIoTRoomInfo *> *roomCallback = [TXIoTCallback new];
roomCallback.onSuccess = ^(TXIoTRoomInfo *roomInfo) {
    NSString *roomId = roomInfo.roomId;
    // 后续可调用 addDeviceToRoom 将设备加入该房间。
};
roomCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 创建房间失败，请根据错误码和错误信息处理。
};
[familyManager createRoom:familyId name:@"客厅" callback:roomCallback];
邀请成员加入家庭
家庭管理员可创建邀请 Token，并将邀请 Token 通过业务自有渠道发送给其他用户。被邀请用户登录 SDK 后，调用加入家庭接口即可成为家庭成员。
注意：
邀请 Token 属于敏感凭据，请通过可信渠道发送给目标用户，并避免在日志中明文输出。
方法
说明
﻿createFamilyInviteToken﻿
家庭管理员创建邀请 Token。
﻿joinFamilyAsMember﻿
被邀请用户使用邀请 Token 加入家庭。
Android
iOS
// 家庭管理员创建邀请 Token。
familyManager.createFamilyInviteToken(familyId, new TXIoTCallback<String>() {
    @Override
    public void onSuccess(String inviteToken) {
        // 将 inviteToken 通过业务自有渠道发送给被邀请用户。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 创建邀请 Token 失败，请根据错误码和错误信息处理。
    }
});
﻿
// 被邀请用户使用邀请 Token 加入家庭。
familyManager.joinFamilyAsMember(inviteToken, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 加入家庭成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 加入家庭失败，请根据错误码和错误信息处理。
    }
});
// 家庭管理员创建邀请 Token。
TXIoTCallback<NSString *> *tokenCallback = [TXIoTCallback new];
tokenCallback.onSuccess = ^(NSString *inviteToken) {
    // 将 inviteToken 通过业务自有渠道发送给被邀请用户。
};
tokenCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 创建邀请 Token 失败，请根据错误码和错误信息处理。
};
[familyManager createFamilyInviteToken:familyId callback:tokenCallback];
﻿
// 被邀请用户使用邀请 Token 加入家庭。
TXIoTVoidCallback *joinCallback = [TXIoTVoidCallback new];
joinCallback.onSuccess = ^{
    // 加入家庭成功。
};
joinCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 加入家庭失败，请根据错误码和错误信息处理。
};
[familyManager joinFamilyAsMember:inviteToken callback:joinCallback];
设备管理
TXIoTDeviceManager 用于完成设备绑定、解绑、列表查询、房间归属、设备分享和别名修改。
设备上下线通知
SDK 登录后，可通过 TXIoTEngine 的推送回调 onReceivePushMessage 接收设备在线、离线状态变更。收到通知后，您可以根据 deviceId 刷新本地设备列表或设备详情。
Android
iOS
iotEngine.addListener(new TXIoTEngineListener() {
    @Override
    public void onReceivePushMessage(TXIoTPushMessage pushMessage) {
        if (pushMessage.type == TXIoTPushMessageType.STATUS_CHANGE) {
            TXIoTDeviceId deviceId = pushMessage.deviceId;
            if (pushMessage.subType == TXIoTPushMessageSubType.ONLINE) {
                // 设备上线。
            } else if (pushMessage.subType == TXIoTPushMessageSubType.OFFLINE) {
                // 设备离线。
            }
        }
    }
});
- (void)onReceivePushMessage:(TXIoTPushMessage *)pushMessage {
    if (pushMessage.type == TXIoTPushMessageTypeStatusChange) {
        TXIoTDeviceId *deviceId = pushMessage.deviceId;
        if (pushMessage.subType == TXIoTPushMessageSubTypeOnline) {
            // 设备上线。
        } else if (pushMessage.subType == TXIoTPushMessageSubTypeOffline) {
            // 设备离线。
        }
    }
}
绑定与解绑设备
设备绑定需要提供 familyId 和 deviceBindSignature。绑定成功后，SDK 返回 TXIoTDeviceInfo，其中包含设备标识、所属家庭 ID、所属房间 ID、设备状态等信息。当用户不再使用设备或需要将设备迁移到其他家庭时，可调用解绑接口，解绑后该设备会从指定家庭中移除。
说明：
deviceBindSignature 由业务后台生成，用于校验设备绑定权限，请通过您的业务服务端获取后传入。
方法
说明
﻿bindDevice﻿
绑定设备，需 familyId 与 deviceBindSignature，返回 TXIoTDeviceInfo。
﻿unbindDevice﻿
解绑设备，将其从指定家庭中移除，deviceId 为 TXIoTDeviceId。
Android
iOS
// 绑定设备。
deviceManager.bindDevice(familyId, deviceBindSignature, new TXIoTCallback<TXIoTDeviceInfo>() {
    @Override
    public void onSuccess(TXIoTDeviceInfo deviceInfo) {
        TXIoTDeviceId deviceId = deviceInfo.deviceId;
        // 绑定成功后，可查询设备列表、下发命令或查询属性。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 绑定失败，请检查设备绑定签名是否正确、是否过期，以及设备是否已绑定。
    }
});
﻿
// 解绑设备。
deviceManager.unbindDevice(familyId, deviceId, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 解绑成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 解绑失败，请根据错误码和错误信息处理。
    }
});
// 绑定设备。
TXIoTCallback<TXIoTDeviceInfo *> *bindCallback = [TXIoTCallback new];
bindCallback.onSuccess = ^(TXIoTDeviceInfo *deviceInfo) {
    TXIoTDeviceId *deviceId = deviceInfo.deviceId;
    // 绑定成功后，可查询设备列表、下发命令或查询属性。
};
bindCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 绑定失败，请检查设备绑定签名是否正确、是否过期，以及设备是否已绑定。
};
[deviceManager bindDevice:familyId deviceBindSignature:deviceBindSignature callback:bindCallback];
﻿
// 解绑设备。
TXIoTVoidCallback *unbindCallback = [TXIoTVoidCallback new];
unbindCallback.onSuccess = ^{
    // 解绑成功。
};
unbindCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 解绑失败，请根据错误码和错误信息处理。
};
[deviceManager unbindDevice:familyId deviceId:deviceId callback:unbindCallback];
查询设备列表
设备列表接口为分页接口。首次查询时传入空字符串，返回结果中的 nextPageToken 为空字符串时表示没有更多数据。
方法
说明
﻿getDeviceList﻿
分页查询家庭下的设备列表，返回 TXIoTPageResult<TXIoTDeviceInfo>。
Android
iOS
deviceManager.getDeviceList(familyId, "", new TXIoTCallback<TXIoTPageResult<TXIoTDeviceInfo>>() {
    @Override
    public void onSuccess(TXIoTPageResult<TXIoTDeviceInfo> result) {
        List<TXIoTDeviceInfo> deviceList = result.dataList;
        String nextPageToken = result.nextPageToken;
        // nextPageToken 为 "" 时表示没有更多数据，否则可传入下一次 getDeviceList 继续分页查询。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 查询设备列表失败，请根据错误码和错误信息处理。
    }
});
TXIoTCallback<TXIoTPageResult<TXIoTDeviceInfo *> *> *listCallback = [TXIoTCallback new];
listCallback.onSuccess = ^(TXIoTPageResult<TXIoTDeviceInfo *> *result) {
    NSArray<TXIoTDeviceInfo *> *deviceList = result.dataList;
    NSString *nextPageToken = result.nextPageToken;
    // nextPageToken 为 @"" 时表示没有更多数据，否则可传入下一次 getDeviceList 继续分页查询。
};
listCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 查询设备列表失败，请根据错误码和错误信息处理。
};
[deviceManager getDeviceList:familyId nextPageToken:@"" callback:listCallback];
将设备加入房间
绑定设备后，可调用 addDeviceToRoom 将设备加入指定房间。若需要从房间移除设备，可调用 removeDeviceFromRoom。房间仅用于分组，因此将设备加入房间是可选操作。
方法
说明
﻿addDeviceToRoom﻿
将设备加入指定房间，deviceId 为 TXIoTDeviceId 类型。
﻿removeDeviceFromRoom﻿
将设备从房间移除，deviceId 为 TXIoTDeviceId 类型。
Android
iOS
deviceManager.addDeviceToRoom(deviceId, familyId, roomId, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 添加设备到房间成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 添加设备到房间失败，请根据错误码和错误信息处理。
    }
});
TXIoTVoidCallback *addCallback = [TXIoTVoidCallback new];
addCallback.onSuccess = ^{
    // 添加设备到房间成功。
};
addCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 添加设备到房间失败，请根据错误码和错误信息处理。
};
[deviceManager addDeviceToRoom:deviceId familyId:familyId roomId:roomId callback:addCallback];
修改设备别名
设备别名用于在 App 中展示设备名称，不会修改设备的产品 ID 或设备名称。
方法
说明
﻿modifyAliasName﻿
修改设备别名，deviceId 为 TXIoTDeviceId 类型。别名仅 App 展示名称，不影响产品 ID 或设备名。
Android
iOS
deviceManager.modifyAliasName(deviceId, "客厅摄像头", new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 修改设备别名成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 修改设备别名失败，请根据错误码和错误信息处理。
    }
});
TXIoTVoidCallback *aliasCallback = [TXIoTVoidCallback new];
aliasCallback.onSuccess = ^{
    // 修改设备别名成功。
};
aliasCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 修改设备别名失败，请根据错误码和错误信息处理。
};
[deviceManager modifyAliasName:deviceId aliasName:@"客厅摄像头" callback:aliasCallback];
设备分享
设备分享适用于设备拥有者将单个设备授权给其他用户使用的场景。设备拥有者创建分享 Token，被分享用户使用该 Token 绑定共享设备。
注意：
设备分享 Token 与家庭邀请 Token 不同。家庭邀请 Token 用于加入家庭，设备分享 Token 仅用于绑定指定共享设备。
分享设备与接受分享
设备拥有者调用 createDeviceSharingToken 生成分享 Token，并通过业务自有渠道发送给被分享用户。
被分享用户登录 SDK 后，调用 bindDeviceSharedWithMe 并传入该 Token，即可绑定这台共享设备。
此外，被分享用户还可以调用 getDeviceListSharedWithMe 分页查询所有被分享给自己的设备列表。
方法
说明
﻿createDeviceSharingToken﻿
设备拥有者生成设备分享 Token，deviceId 为 TXIoTDeviceId 类型。
﻿bindDeviceSharedWithMe﻿
被分享用户使用 Token 绑定共享设备，deviceId 为 TXIoTDeviceId 类型。
﻿getDeviceListSharedWithMe﻿
查询所有别人分享给我的设备列表。
Android
iOS
// 设备拥有者：创建设备分享 Token 并发送给被分享用户。
deviceManager.createDeviceSharingToken(familyId, deviceId, new TXIoTCallback<String>() {
    @Override
    public void onSuccess(String shareToken) {
        // 将 shareToken 通过业务自有渠道发送给被分享用户。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 创建设备分享 Token 失败，请根据错误码和错误信息处理。
    }
});
﻿
// 被分享用户：使用分享 Token 绑定共享设备。
deviceManager.bindDeviceSharedWithMe(deviceId, shareToken, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 绑定共享设备成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 绑定共享设备失败，请根据错误码和错误信息处理。
    }
});
// 设备拥有者：创建设备分享 Token 并发送给被分享用户。
TXIoTCallback<NSString *> *shareCallback = [TXIoTCallback new];
shareCallback.onSuccess = ^(NSString *shareToken) {
    // 将 shareToken 通过业务自有渠道发送给被分享用户。
};
shareCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 创建设备分享 Token 失败，请根据错误码和错误信息处理。
};
[deviceManager createDeviceSharingToken:familyId deviceId:deviceId callback:shareCallback];
﻿
// 被分享用户：使用分享 Token 绑定共享设备。
TXIoTVoidCallback *bindSharedCallback = [TXIoTVoidCallback new];
bindSharedCallback.onSuccess = ^{
    // 绑定共享设备成功。
};
bindSharedCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 绑定共享设备失败，请根据错误码和错误信息处理。
};
[deviceManager bindDeviceSharedWithMe:deviceId shareToken:shareToken callback:bindSharedCallback];
管理共享关系
设备拥有者可以查询设备已分享用户列表，也可以移除指定共享用户。被分享用户可查询共享给自己的设备列表，或取消绑定共享设备。
方法
说明
﻿getDeviceSharedUsers﻿
设备拥有者查询已分享给哪些用户，deviceId 为 TXIoTDeviceId，异步回调 TXIoTUserInfo 列表。
﻿removeDeviceSharedUser﻿
设备拥有者移除指定共享用户，deviceId 为 TXIoTDeviceId，被移除的用户将无法再访问该设备。
﻿getDeviceListSharedWithMe﻿
查询别人分享给我的设备列表，异步回调 TXIoTPageResult<TXIoTDeviceInfo>，支持分页。首次查询传空字符串，nextPageToken 为空字符串时表示没有更多数据。
﻿unbindDeviceSharedWithMe﻿
取消绑定别人分享给我的设备，deviceId 为 TXIoTDeviceId，取消绑定后不再拥有该设备的访问权限。
Android
iOS
// 设备拥有者：查询已分享用户列表
deviceManager.getDeviceSharedUsers(deviceId, new TXIoTCallback<List<TXIoTUserInfo>>() {
    @Override
    public void onSuccess(List<TXIoTUserInfo> userList) {
        // 查询成功，userList 为已分享的用户列表。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 查询失败，请根据错误码和错误信息处理。
    }
});
﻿
// 设备拥有者：移除指定共享用户
deviceManager.removeDeviceSharedUser(deviceId, userId, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 移除成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 移除失败，请根据错误码和错误信息处理。
    }
});
﻿
// 被分享用户：查询共享设备列表（首次传空字符串）
deviceManager.getDeviceListSharedWithMe("", new TXIoTCallback<TXIoTPageResult<TXIoTDeviceInfo>>() {
    @Override
    public void onSuccess(TXIoTPageResult<TXIoTDeviceInfo> pageResult) {
        // 查询成功，pageResult.data 为设备列表。pageResult.nextPageToken 为空字符串时表示没有更多数据。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 查询失败，请根据错误码和错误信息处理。
    }
});
﻿
// 被分享用户：取消绑定共享设备
deviceManager.unbindDeviceSharedWithMe(deviceId, new TXIoTCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        // 取消成功。
    }
﻿
    @Override
    public void onError(TXIoTErrorCode errorCode, String errorMessage) {
        // 取消失败，请根据错误码和错误信息处理。
    }
});
// 设备拥有者：查询已分享用户列表
TXIoTCallback<NSArray<TXIoTUserInfo*>*> *sharedUsersCallback = [TXIoTCallback new];
sharedUsersCallback.onSuccess = ^(NSArray<TXIoTUserInfo*> *userList) {
    // 查询成功，userList 为已分享的用户列表。
};
sharedUsersCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 查询失败，请根据错误码和错误信息处理。
};
[deviceManager getDeviceSharedUsers:deviceId callback:sharedUsersCallback];
﻿
// 设备拥有者：移除指定共享用户
TXIoTVoidCallback *removeCallback = [TXIoTVoidCallback new];
removeCallback.onSuccess = ^{
    // 移除成功。
};
removeCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 移除失败，请根据错误码和错误信息处理。
};
[deviceManager removeDeviceSharedUser:deviceId userId:userId callback:removeCallback];
﻿
// 被分享用户：查询共享设备列表（首次传空字符串）
TXIoTCallback<TXIoTPageResult<TXIoTDeviceInfo*>*> *sharedDevCallback = [TXIoTCallback new];
sharedDevCallback.onSuccess = ^(TXIoTPageResult<TXIoTDeviceInfo*> *pageResult) {
    // 查询成功，pageResult.data 为设备列表。pageResult.nextPageToken 为空字符串时表示没有更多数据。
};
sharedDevCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 查询失败，请根据错误码和错误信息处理。
};
[deviceManager getDeviceListSharedWithMe:@"" callback:sharedDevCallback];
﻿
// 被分享用户：取消绑定共享设备
TXIoTVoidCallback *unbindCallback = [TXIoTVoidCallback new];
unbindCallback.onSuccess = ^{
    // 取消成功。
};
unbindCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 取消失败，请根据错误码和错误信息处理。
};
[deviceManager unbindDeviceSharedWithMe:deviceId callback:unbindCallback];
错误处理
家庭和设备管理常见错误码如下，完整错误码定义见 TXIoTErrorCode。
Android
iOS
错误码
说明
建议处理方式
ERR_INVALID_PARAMETER
参数不合法。
检查 familyId、deviceId、Token 或 JSON 字符串是否为空或格式错误。
ERR_INVALID_ACCESS_TOKEN
登录凭证无效。
重新登录 SDK。
ERR_RATE_LIMITED
请求被限频。
降低调用频率后重试。
ERR_UNAUTHORIZED_OPERATION
当前用户无权限。
检查当前用户是否为家庭管理员或是否具备设备操作权限。
ERR_DEVICE_BOUND
设备已绑定。
检查设备是否已绑定到当前或其他家庭。
ERR_BIND_TOKEN_NOT_EXIST
绑定 Token 不存在。
重新获取设备绑定签名。
ERR_BIND_TOKEN_IS_EXPIRED
绑定 Token 已过期。
重新获取设备绑定签名后再次绑定。
ERR_BIND_TOKEN_NO_PAIR_WITH_DEVICE
绑定 Token 与设备不匹配。
确认设备绑定签名对应的设备与当前设备一致。
ERR_FAMILY_DEVICE_LIMIT_EXCEEDED
家庭设备数量达到上限。
清理无用设备或调整家庭设备数量。
ERR_CAN_NOT_BIND_SAME_FAMILY
不能重复绑定到同一家庭。
避免重复绑定同一设备。
ERR_FAMILY_NOT_EXIST
家庭不存在。
重新查询家庭列表，确认 familyId 是否有效。
ERR_PRODUCT_NOT_EXIST
产品不存在。
检查 productId 是否正确。
ERR_DEVICE_NOT_EXIST
设备不存在。
检查 deviceName 和 productId 是否正确。
ERR_DEVICE_OFFLINE
设备离线。
引导用户检查设备网络状态后重试。
错误码
说明
建议处理方式
TXIoTErrorCodeInvalidParameter
参数不合法。
检查 familyId、deviceId、Token 或 JSON 字符串是否为空或格式错误。
TXIoTErrorCodeInvalidAccessToken
登录凭证无效。
重新登录 SDK。
TXIoTErrorCodeRateLimited
请求被限频。
降低调用频率后重试。
TXIoTErrorCodeUnauthorizedOperation
当前用户无权限。
检查当前用户是否为家庭管理员或是否具备设备操作权限。
TXIoTErrorCodeDeviceBound
设备已绑定。
检查设备是否已绑定到当前或其他家庭。
TXIoTErrorCodeBindTokenNotExist
绑定 Token 不存在。
重新获取设备绑定签名。
TXIoTErrorCodeBindTokenIsExpired
绑定 Token 已过期。
重新获取设备绑定签名后再次绑定。
TXIoTErrorCodeBindTokenNoPairWithDevice
绑定 Token 与设备不匹配。
确认设备绑定签名对应的设备与当前设备一致。
TXIoTErrorCodeFamilyDeviceLimitExceeded
家庭设备数量达到上限。
清理无用设备或调整家庭设备数量。
TXIoTErrorCodeCanNotBindSameFamily
不能重复绑定到同一家庭。
避免重复绑定同一设备。
TXIoTErrorCodeFamilyNotExist
家庭不存在。
重新查询家庭列表，确认 familyId 是否有效。
TXIoTErrorCodeProductNotExist
产品不存在。
检查 productId 是否正确。
TXIoTErrorCodeDeviceNotExist
设备不存在。
检查 deviceName 和 productId 是否正确。
TXIoTErrorCodeDeviceOffline
设备离线。
引导用户检查设备网络状态后重试。
﻿

方法	说明
getFamilyList	查询当前用户的家庭列表，返回 TXIoTFamilyInfo 列表。
createFamily	创建家庭，返回 TXIoTFamilyInfo（含 `familyId`）。

方法	说明
createRoom	在指定家庭下创建房间，返回 TXIoTRoomInfo（含 `roomId`）。

方法	说明
createFamilyInviteToken	家庭管理员创建邀请 Token。
joinFamilyAsMember	被邀请用户使用邀请 Token 加入家庭。

方法	说明
bindDevice	绑定设备，需 `familyId` 与 `deviceBindSignature`，返回 TXIoTDeviceInfo。
unbindDevice	解绑设备，将其从指定家庭中移除，`deviceId` 为 TXIoTDeviceId。

方法	说明
getDeviceList	分页查询家庭下的设备列表，返回 TXIoTPageResult<TXIoTDeviceInfo>。

方法	说明
addDeviceToRoom	将设备加入指定房间，`deviceId` 为 TXIoTDeviceId 类型。
removeDeviceFromRoom	将设备从房间移除，`deviceId` 为 TXIoTDeviceId 类型。

方法	说明
modifyAliasName	修改设备别名，`deviceId` 为 TXIoTDeviceId 类型。别名仅 App 展示名称，不影响产品 ID 或设备名。

方法	说明
createDeviceSharingToken	设备拥有者生成设备分享 Token，`deviceId` 为 TXIoTDeviceId 类型。
bindDeviceSharedWithMe	被分享用户使用 Token 绑定共享设备，`deviceId` 为 TXIoTDeviceId 类型。
getDeviceListSharedWithMe	查询所有别人分享给我的设备列表。

方法	说明
getDeviceSharedUsers	设备拥有者查询已分享给哪些用户，`deviceId` 为 TXIoTDeviceId，异步回调 TXIoTUserInfo 列表。
removeDeviceSharedUser	设备拥有者移除指定共享用户，`deviceId` 为 TXIoTDeviceId，被移除的用户将无法再访问该设备。
getDeviceListSharedWithMe	查询别人分享给我的设备列表，异步回调 TXIoTPageResult<TXIoTDeviceInfo>，支持分页。首次查询传空字符串，`nextPageToken` 为空字符串时表示没有更多数据。
unbindDeviceSharedWithMe	取消绑定别人分享给我的设备，`deviceId` 为 TXIoTDeviceId，取消绑定后不再拥有该设备的访问权限。

错误码	说明	建议处理方式
`ERR_INVALID_PARAMETER`	参数不合法。	检查 `familyId`、`deviceId`、Token 或 JSON 字符串是否为空或格式错误。
`ERR_INVALID_ACCESS_TOKEN`	登录凭证无效。	重新登录 SDK。
`ERR_RATE_LIMITED`	请求被限频。	降低调用频率后重试。
`ERR_UNAUTHORIZED_OPERATION`	当前用户无权限。	检查当前用户是否为家庭管理员或是否具备设备操作权限。
`ERR_DEVICE_BOUND`	设备已绑定。	检查设备是否已绑定到当前或其他家庭。
`ERR_BIND_TOKEN_NOT_EXIST`	绑定 Token 不存在。	重新获取设备绑定签名。
`ERR_BIND_TOKEN_IS_EXPIRED`	绑定 Token 已过期。	重新获取设备绑定签名后再次绑定。
`ERR_BIND_TOKEN_NO_PAIR_WITH_DEVICE`	绑定 Token 与设备不匹配。	确认设备绑定签名对应的设备与当前设备一致。
`ERR_FAMILY_DEVICE_LIMIT_EXCEEDED`	家庭设备数量达到上限。	清理无用设备或调整家庭设备数量。
`ERR_CAN_NOT_BIND_SAME_FAMILY`	不能重复绑定到同一家庭。	避免重复绑定同一设备。
`ERR_FAMILY_NOT_EXIST`	家庭不存在。	重新查询家庭列表，确认 `familyId` 是否有效。
`ERR_PRODUCT_NOT_EXIST`	产品不存在。	检查 `productId` 是否正确。
`ERR_DEVICE_NOT_EXIST`	设备不存在。	检查 `deviceName` 和 `productId` 是否正确。
`ERR_DEVICE_OFFLINE`	设备离线。	引导用户检查设备网络状态后重试。

绑定与分享

本页目录：

前提条件

获取管理对象

家庭管理

查询或创建家庭

管理房间

邀请成员加入家庭

设备管理

设备上下线通知

绑定与解绑设备

查询设备列表

将设备加入房间

修改设备别名

设备分享

分享设备与接受分享

管理共享关系

错误处理