방송 이력

개요

oe.history.*는 방송 이력을 읽기 전용으로 제공합니다. 목록 조회와 단건 조회만 지원합니다.

시작하기 전에

방송 이력을 조회하기 전에 아래를 준비하세요.

• 파트너 앱에 HISTORY capability grant 가 있어야 합니다. 없으면 CapabilityDenied 에러가 발생합니다.

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

HistoryView 필드

목록·상세 조회 모두 아래 필드 구성을 공유합니다.

참고: type 은 SDK가 정규화한 공개 계약값입니다. 서버 wire 값을 직접 비교하지 말고 'TTS'/'MIC'로 비교하세요.

방송 이력 목록 조회 — oe.history.list()

정렬은 서버가 최신순으로 고정합니다.

기본 정보

요청 — 필터 파라미터

응답

예제

const page = await oe.history.list({ page: 0, size: 10 });
console.log(page.content.length, page.totalElements);

// 유형 필터 — TTS 방송만
const tts = await oe.history.list({ page: 0, size: 10, type: "TTS" });

// 제목 검색 — 부분일치·대소문자 무시
const found = await oe.history.list({ page: 0, size: 10, search: "환영" });

참고: 필터나 검색어를 바꿀 때는 page 를 0 으로 되돌리세요.

전체 페이지를 순회하려면 다음과 같이 반복 조회합니다.

async function fetchAllHistory() {
  type Item = Awaited<ReturnType<typeof oe.history.list>>["content"][number];
  const all: Item[] = [];
  let page = 0;
  const size = 20;

  while (true) {
    const result = await oe.history.list({ page, size });
    all.push(...result.content);
    if ((page + 1) * size >= result.totalElements) break;
    page++;
  }

  return all;
}

대표 에러

방송 이력 단건 조회 — oe.history.get()

목록과 달리 deviceHandles(당시 대상)가 채워집니다. 지난 방송 당시 대상 그대로 재방송하는 흐름에서 주로 사용합니다.

기본 정보

요청

응답

HistoryView — 필드는 위 "HistoryView 필드" 절을 참조하세요. 상세 조회에서는 deviceHandles 가 채워집니다.

예제

const item = await oe.history.get(sessionId);
console.log(item.status, item.deviceHandles);

참고: 이 앱이 소유하지 않은 세션은 존재 여부가 노출되지 않습니다.

대표 에러

지난 방송으로 재방송

oe.history.get()으로 받은 contentHandle과 deviceHandles를 그대로 oe.broadcast.tts.fromContent()에 전달하면 지난 방송 당시 대상 그대로 다시 방송할 수 있습니다.

const past = await oe.history.get(sessionId);
if (past.contentHandle && (past.deviceHandles?.length ?? 0) > 0) {
  await oe.broadcast.tts.fromContent({
    contentHandle: past.contentHandle,
    deviceHandles: past.deviceHandles!,
    idempotencyKey: crypto.randomUUID(),
  });
}

• 재방송 후보는 type !== 'MIC'이고 contentHandle이 있는 항목만 고릅니다.
• deviceHandles가 비어 있으면 당시 대상이 더 이상 이 앱에 노출되지 않는 것입니다 — 재방송할 수 없습니다.

방송 실행 상세는 TTS 방송을 참조하세요.

참고 코드

레퍼런스 앱의 방송 이력 화면 구현은 partner-app/src/features/history/History.tsx에서 확인할 수 있습니다. history.get() 기반 재방송 플로우는 partner-app/src/features/tts/TtsBroadcast.tsx에 있습니다.

더보기

• TTS 방송
• Control-Plane 개요
• 에러 처리