디바이스 그룹

개요

oe.groups.*는 디바이스 그룹의 생성, 조회, 멤버십 편집(추가·제거), 삭제를 제공합니다. 그룹에 방송하면 그룹에 속한 대상 디바이스 전체가 방송 대상이 됩니다.

참고: oe.groups에는 수정(update) 메서드가 없습니다. 그룹명 변경은 지원하지 않으며, 그룹 내용 변경은 멤버십 편집(addMembers/removeMembers)으로만 가능합니다.

시작하기 전에

디바이스 그룹을 다루기 전에 아래를 준비하세요.

파트너 앱에 DEVICE_GROUP capability grant 가 있어야 합니다. 없으면 CapabilityDenied 에러가 발생합니다.
멤버십 편집에는 대상 디바이스의 handle 이 필요합니다. oe.targets.list()로 조회합니다.

참고: capability 는 부여 등급(READ·MANAGE)에 따라 사용할 수 있는 API 가 다릅니다. 메서드별 등급은 컨트롤 플레인 개요의 Capability 요약에서 확인하세요.

그룹 생성 — `oe.groups.create()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.create(input)`	`DEVICE_GROUP`	없음(신규 생성 — 참조 handle 없음)	`Promise<GroupView>`

요청

이름	타입	설명	기본값	필수
`name`	`string`	그룹 이름	-	O
`description`	`string`	그룹 설명	-	X

응답

GroupView — 필드는 아래 "그룹 상세 조회" 절의 응답 표와 같습니다.

예제

const group = await oe.groups.create({ name: "1층 스피커" });

const lounge = await oe.groups.create({
  name: "2층 스피커",
  description: "2층 복도·라운지",
});

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요

그룹 목록 조회 — `oe.groups.list()`

이 앱이 소유한 그룹 목록을 조회합니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.list(opts?)`	`DEVICE_GROUP`	없음 — capability 만으로 게이트되고, 이후 이 앱이 소유한 그룹만 반환됩니다	`Promise<GroupView[]>`

요청 — 필터 파라미터

이름	타입	설명	기본값	필수
`search`	`string`	그룹명 부분일치 필터(대소문자 무시)	-	X

응답

GroupView[] — 각 항목의 필드는 아래 "그룹 상세 조회" 절의 응답 표와 같습니다.

예제

const all = await oe.groups.list();

const filtered = await oe.groups.list({ search: "1층" });

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요

그룹 상세 조회 — `oe.groups.get()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.get(handle)`	`DEVICE_GROUP`	`handle` 이 이 앱이 소유한 그룹으로 resolve 되어야 함(불일치 시 존재 은닉)	`Promise<GroupView>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	조회할 그룹 handle	-	O

응답

이름	타입	설명
`handle`	`string`	그룹 handle
`label`	`string`	그룹 이름
`memberCount`	`number`	멤버 디바이스 수
`status`	`string \| undefined`	그룹 상태
`description`	`string \| null \| undefined`	그룹 설명

예제

const group = await oe.groups.get("grp_1f");
console.log(group.label, group.memberCount);

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 을 해석할 수 없음	그룹 handle 이 유효한지 목록을 다시 조회해 확인하세요

멤버 추가 — `oe.groups.addMembers()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.addMembers(handle, deviceHandles)`	`DEVICE_GROUP`	그룹 `handle` 은 이 앱 소유여야 하고, `deviceHandles` 는 각 handle 이 디바이스로 resolve 되어야 함(all-or-none)	`Promise<void>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	대상 그룹 handle	-	O
`deviceHandles`	`string[]`	추가할 디바이스 handle 목록	-	O

응답

반환값이 없습니다(Promise<void>).

예제

await oe.groups.addMembers("grp_1f", deviceHandles);

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	그룹 `handle` 또는 `deviceHandles` 를 해석할 수 없음	handle 이 유효한지 대상 목록을 다시 조회해 확인하세요

멤버 제거 — `oe.groups.removeMembers()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.removeMembers(handle, deviceHandles)`	`DEVICE_GROUP`	추가와 동일 — 그룹 소유 검증 + 각 `deviceHandles` 가 디바이스로 resolve 되어야 함	`Promise<void>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	대상 그룹 handle	-	O
`deviceHandles`	`string[]`	제거할 디바이스 handle 목록	-	O

응답

반환값이 없습니다(Promise<void>).

예제

await oe.groups.removeMembers("grp_1f", deviceHandles);

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	그룹 `handle` 또는 `deviceHandles` 를 해석할 수 없음	handle 이 유효한지 대상 목록을 다시 조회해 확인하세요

그룹 멤버 조회 — `oe.groups.members()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.members(handle)`	`DEVICE_GROUP`	`handle` 이 이 앱이 소유한 그룹으로 resolve 되어야 함	`Promise<DeviceView[]>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	조회할 그룹 handle	-	O

응답

이름	타입	설명
`handle`	`string`	디바이스 handle
`name`	`string`	디바이스 이름
`status`	`string`	디바이스 상태
`online`	`boolean \| undefined`	조회 시점의 온라인 여부를 나타내는 정보 라벨. 방송 시점의 실제 상태를 보장하지 않으므로 대상 선택 제한 근거로 사용하지 마세요

예제

const [targets, members] = await Promise.all([
  oe.targets.list(),
  oe.groups.members("grp_1f"),
]);

const memberHandles = new Set(members.map((m) => m.handle));
const available = targets.filter((d) => !memberHandles.has(d.handle));

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 을 해석할 수 없음	그룹 handle 이 유효한지 확인하세요

그룹 삭제 — `oe.groups.delete()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.groups.delete(handle)`	`DEVICE_GROUP`	`handle` 이 이 앱이 소유한 그룹으로 resolve 되어야 함	`Promise<void>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	삭제할 그룹 handle	-	O

응답

반환값이 없습니다(Promise<void>).

예제

await oe.groups.delete("grp_1f");

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `DEVICE_GROUP` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 을 해석할 수 없음	그룹 handle 이 유효한지 확인하세요

참고 코드

레퍼런스 앱의 디바이스 그룹 화면 구현은 partner-app/src/features/groups/Groups.tsx에서 확인할 수 있습니다.

디바이스 그룹

개요

시작하기 전에

그룹 생성 — oe.groups.create()

기본 정보

요청

응답

예제

대표 에러

그룹 목록 조회 — oe.groups.list()

기본 정보

요청 — 필터 파라미터

응답

예제

대표 에러

그룹 상세 조회 — oe.groups.get()

기본 정보

요청

응답

예제

대표 에러

멤버 추가 — oe.groups.addMembers()

기본 정보

요청

응답

예제

대표 에러

멤버 제거 — oe.groups.removeMembers()

기본 정보

요청

응답

예제

대표 에러

그룹 멤버 조회 — oe.groups.members()

기본 정보

요청

응답

예제

대표 에러

그룹 삭제 — oe.groups.delete()

기본 정보

요청

응답

예제

대표 에러

참고 코드

더보기

그룹 생성 — `oe.groups.create()`

그룹 목록 조회 — `oe.groups.list()`

그룹 상세 조회 — `oe.groups.get()`

멤버 추가 — `oe.groups.addMembers()`

멤버 제거 — `oe.groups.removeMembers()`

그룹 멤버 조회 — `oe.groups.members()`

그룹 삭제 — `oe.groups.delete()`