방송 템플릿
개요
oe.templates.*는 방송 템플릿을 관리합니다. 템플릿은 컨텐츠와 대상(그룹 또는 개별 디바이스 목록)을 묶은 재사용 가능한 방송 구성 단위이며, 예약 방송에 필수입니다.
시작하기 전에
방송 템플릿을 다루기 전에 아래를 준비하세요.
- 파트너 앱에
TEMPLATEcapability grant 가 있어야 합니다. 없으면CapabilityDenied에러가 발생합니다. - 템플릿 생성에는 컨텐츠와 대상이 필요합니다. 컨텐츠는 방송 컨텐츠에서, 대상은 디바이스 또는 디바이스 그룹에서 준비하세요.
참고: capability 는 부여 등급(READ·MANAGE)에 따라 사용할 수 있는 API 가 다릅니다. 메서드별 등급은 컨트롤 플레인 개요의 Capability 요약에서 확인하세요.
템플릿 생성 — oe.templates.create()
컨텐츠와 대상을 묶어 템플릿을 만듭니다. 대상은 그룹(groupHandle) 또는 개별 디바이스 목록(deviceHandles) 중 정확히 하나의 모드로 지정합니다.
기본 정보
| 메서드 | 앱 capability | 참조 handle 조건 | 반환 타입 |
|---|---|---|---|
oe.templates.create(input) | TEMPLATE + CONTENT + (DEVICE×N 또는 DEVICE_GROUP) | contentHandle 은 resolve 되고 실행 권한 grant 가 있어야 함. deviceHandles 는 각 handle 이 디바이스로 resolve 되어야 함(all-or-none). groupHandle 은 이 앱이 읽을 수 있는 그룹이어야 함 | Promise<TemplateView> |
요청
| 이름 | 타입 | 설명 | 기본값 | 필수 |
|---|---|---|---|---|
name | string | 템플릿 이름 | - | O |
contentHandle | string | 방송에 사용할 컨텐츠 handle | - | O |
groupHandle | string | 대상 그룹 handle | - | 조건부 |
deviceHandles | string[] | 대상 디바이스 handle 다중 지정 | - | 조건부 |
languageOrder | string | 언어 재생 순서(쉼표 구분, 예 "ko,en") | - | X |
주의:
groupHandle과deviceHandles는 동시에 지정할 수 없습니다. 둘 중 정확히 하나만 지정하세요.
참고:
languageOrder는 이 API에서는 쉼표로 구분한 문자열("ko,en")입니다.oe.broadcast.tts.fromContent()의languageOrder는 배열(["ko", "en"])이므로 형식이 다릅니다.
응답
TemplateView — 필드는 아래 "템플릿 상세 조회" 절의 응답 표와 같습니다.
예제
// 그룹 대상 템플릿
await oe.templates.create({
name: "오전 안내 방송",
contentHandle,
groupHandle: "grp_1f",
languageOrder: "ko,en",
});
// 개별 디바이스 대상 템플릿
await oe.templates.create({
name: "1층 안내 방송",
contentHandle,
deviceHandles,
});
대표 에러
| 에러 | HTTP 상태 | 원인 | 해결 방법 |
|---|---|---|---|
CapabilityDenied | 403 | 앱에 TEMPLATE 또는 CONTENT capability grant 가 없음 | Open Echo 지원 채널로 grant 를 요청하세요 |
TargetUnresolved | 404 | contentHandle/groupHandle/deviceHandles 를 해석할 수 없거나 필요한 권한이 없음 | handle 이 유효한지, 필요한 권한이 있는지 확인하세요 |
템플릿 목록 조회 — oe.templates.list()
이 앱이 소유한 템플릿 목록을 조회합니다.
기본 정보
| 메서드 | 앱 capability | 참조 handle 조건 | 반환 타입 |
|---|---|---|---|
oe.templates.list() | TEMPLATE | 없음 — capability 만으로 게이트되고, 이후 이 앱이 소유한 템플릿만 반환됩니다 | Promise<TemplateView[]> |
요청
입력 파라미터가 없습니다.
응답
TemplateView[] — 각 항목의 필드는 아래 "템플릿 상세 조회" 절의 응답 표와 같습니다.
예제
const templates = await oe.templates.list();
for (const t of templates) {
console.log(t.handle, t.name);
}
대표 에러
| 에러 | HTTP 상태 | 원인 | 해결 방법 |
|---|---|---|---|
CapabilityDenied | 403 | 앱에 TEMPLATE capability grant 가 없음 | Open Echo 지원 채널로 grant 를 요청하세요 |
템플릿 상세 조회 — oe.templates.get()
기본 정보
| 메서드 | 앱 capability | 참조 handle 조건 | 반환 타입 |
|---|---|---|---|
oe.templates.get(handle) | TEMPLATE | handle 이 이 앱이 소유한 템플릿으로 resolve 되어야 함 | Promise<TemplateView> |
요청
| 이름 | 타입 | 설명 | 기본값 | 필수 |
|---|---|---|---|---|
handle | string | 조회할 템플릿 handle | - | O |
응답
| 이름 | 타입 | 설명 |
|---|---|---|
handle | string | 템플릿 handle |
name | string | 템플릿 이름 |
contentHandle | string | 사용 중인 컨텐츠 handle |
targetMode | string | 대상 지정 방식(그룹 또는 개별 디바이스) |
languageOrder | string | null | undefined | 언어 재생 순서 |
groupHandle | string | null | undefined | 대상 그룹 handle(그룹 모드일 때) |
deviceHandles | string[] | null | undefined | 대상 디바이스 handle 목록(개별 디바이스 모드일 때). 조회 시점의 실효 노출 기준으로 다시 계산되며, 노출이 사라진 디바이스는 제외됩니다 |
예제
const template = await oe.templates.get("tpl_morning");
console.log(template.name, template.contentHandle);
대표 에러
| 에러 | HTTP 상태 | 원인 | 해결 방법 |
|---|---|---|---|
CapabilityDenied | 403 | 앱에 TEMPLATE capability grant 가 없음 | Open Echo 지원 채널로 grant 를 요청하세요 |
TargetUnresolved | 404 | handle 을 해석할 수 없음 | 템플릿 handle 이 유효한지 목록을 다시 조회해 확인하세요 |
템플릿 수정 — oe.templates.update()
이름과 언어 재생 순서만 변경할 수 있습니다. 컨텐츠와 대상은 수정할 수 없습니다.
기본 정보
| 메서드 | 앱 capability | 참조 handle 조건 | 반환 타입 |
|---|---|---|---|
oe.templates.update(handle, input) | TEMPLATE | handle 이 이 앱이 소유한 템플릿으로 resolve 되어야 함 | Promise<TemplateView> |
요청
| 이름 | 타입 | 설명 | 기본값 | 필수 |
|---|---|---|---|---|
name | string | 템플릿 이름 | - | O |
languageOrder | string | 언어 재생 순서 | - | X |
응답
TemplateView — 필드는 위 "템플릿 상세 조회" 절의 응답 표와 같습니다.
예제
await oe.templates.update("tpl_morning", {
name: "오전 인사 방송",
languageOrder: "ko",
});
대표 에러
| 에러 | HTTP 상태 | 원인 | 해결 방법 |
|---|---|---|---|
CapabilityDenied | 403 | 앱에 TEMPLATE capability grant 가 없음 | Open Echo 지원 채널로 grant 를 요청하세요 |
TargetUnresolved | 404 | handle 을 해석할 수 없음 | 템플릿 handle 이 유효한지 확인하세요 |
템플릿 삭제 — oe.templates.delete()
기본 정보
| 메서드 | 앱 capability | 참조 handle 조건 | 반환 타입 |
|---|---|---|---|
oe.templates.delete(handle) | TEMPLATE | handle 이 이 앱이 소유한 템플릿으로 resolve 되어야 함 | Promise<void> |
요청
| 이름 | 타입 | 설명 | 기본값 | 필수 |
|---|---|---|---|---|
handle | string | 삭제할 템플릿 handle | - | O |
응답
반환값이 없습니다(Promise<void>).
예제
await oe.templates.delete("tpl_morning");
대표 에러
| 에러 | HTTP 상태 | 원인 | 해결 방법 |
|---|---|---|---|
CapabilityDenied | 403 | 앱에 TEMPLATE capability grant 가 없음 | Open Echo 지원 채널로 grant 를 요청하세요 |
TargetUnresolved | 404 | handle 을 해석할 수 없음 | 템플릿 handle 이 유효한지 확인하세요 |
참고: 이 템플릿을 참조하는 예약이 남아있으면 삭제할 수 없습니다. 먼저 참조 예약을 삭제하거나 다른 템플릿으로 교체하세요.
참고 코드
레퍼런스 앱의 방송 템플릿 화면 구현은 partner-app/src/features/templates/Templates.tsx에서 확인할 수 있습니다.