Live Snapshot

Live Snapshot API는 라이브 스트림에서 스틸 이미지를 캡처하여 Object Storage 버킷에 저장합니다. 썸네일, 라이브 미리 보기, 콘텐츠 조정 샘플 및 규정 준수 아카이브에 사용할 수 있습니다.

이 가이드에서는 스냅샷 동작을 구성하고, 일치하는 스트림의 캡처를 자동화하며, 필요에 따라 캡처 세션을 시작하고, 생성된 작업 및 파일 정보를 조회하는 방법을 설명합니다.

시작하기 전에

• 스냅샷 템플릿에서 사용할 Object Storage 대상 및 콜백 엔드포인트를 준비하세요.
• 규칙을 생성하거나 실시간 캡처 세션을 시작하기 전에 스냅샷 매개변수 템플릿을 하나 이상 생성하세요.
• 필요에 따른 캡처를 수행하려면 활성 라이브 스트림의 배포 URL을 준비하세요.
• 작업을 조회할 때는 스냅샷 작업을 처리하는 서비스 리전을 사용하세요: cn, us 또는 sg.

API가 서로 연동되는 방식

스냅샷 워크플로에는 다음 네 가지 구성 요소가 있습니다:

1. 스냅샷 매개변수 템플릿은 스냅샷을 캡처하고 저장하는 방식을 정의합니다.
2. 스냅샷 규칙은 라이브 스트림이 규칙과 일치할 때 템플릿을 자동으로 적용합니다.
3. 실시간 제어는 활성 스트림에 대한 온디맨드 캡처 세션을 시작하거나 중지합니다.
4. 작업 쿼리는 스냅샷 작업을 찾고, 해당 작업의 상태를 모니터링하며, 생성된 이미지 파일에 대한 정보를 반환합니다.

템플릿은 모든 작업의 기반입니다. 스냅샷 규칙과 실시간 제어 기능을 사용하려면 모두 templateId가 필요하므로, 어느 워크플로를 사용하기 전에 템플릿을 생성하고 저장해야 합니다.

일반적인 스냅샷 워크플로

1. 스냅샷 매개변수 템플릿을 생성하고 해당 templateId를 저장합니다.
2. 캡처 시작 방법을 선택합니다:
   • 일치하는 스트림이 라이브 상태가 되면 자동으로 캡처하도록 스냅샷 규칙을 생성합니다.
   • StartRealTimeSnapshot을 호출하여 활성 스트림의 캡처를 필요에 따라 시작합니다.
3. 각 캡처 세션에서 반환되는 persistentId를 저장합니다.
4. QuerySnapshotTaskIds를 사용하여 특정 시간 범위 내의 작업을 검색하거나 작업의 persistentId를 가져옵니다.
5. persistentId를 사용하여 QuerySnapshotTaskDetail을 호출하면 작업을 모니터링하고 생성된 스냅샷 파일을 확인할 수 있습니다.
6. 실시간 세션을 시작한 후 스트림이 종료되기 전에 세션을 종료해야 하는 경우 관련 persistentId를 사용하여 StopRealTimeSnapshot을 호출합니다.

스냅샷 매개변수 템플릿 생성 및 관리

스냅샷 매개변수 템플릿은 서비스에서 이미지를 캡처하고 저장하는 방식을 제어합니다. 이미지 형식, 샘플링 간격, Object Storage 대상, 파일 명명 규칙 및 콜백 URL을 정의합니다.

중요: 활성 규칙에서 템플릿을 참조하고 있는 동안에는 해당 템플릿을 삭제할 수 없습니다. 삭제하기 전에 모든 규칙에서 템플릿을 제거하세요.

규칙으로 스냅샷 자동화

스냅샷 규칙은 templateId를 라이브 스트림과 연결하여, 일치하는 스트림이 라이브 상태일 때 서비스가 이미지를 자동으로 캡처하도록 합니다.

규칙은 다음 세 가지 세분화 수준으로 적용할 수 있습니다:

• 도메인: 지정된 도메인에 속한 스트림에 적용됩니다.
• 애플리케이션 이름: 하나의 애플리케이션에 속한 스트림에 적용됩니다.
• 스트림 이름: 특정 스트림 하나에 적용됩니다.

시스템은 가장 긴 일치 규칙을 사용합니다. 특정 스트림과 일치하는 규칙이 더 포괄적인 애플리케이션 수준 규칙보다 우선하며, 애플리케이션 수준 규칙은 도메인 수준 규칙보다 우선합니다. 기본 캡처 정책에는 포괄적인 규칙을 사용하고, 특정 스트림에 다른 설정이 필요한 경우에는 더 구체적인 규칙을 사용하세요.

중요: 스냅샷을 캡처하는 동안에는 규칙을 삭제할 수 없습니다. 규칙을 삭제하기 전에 스트림이 종료될 때까지 기다리거나 캡처 세션을 중지하세요.

주문형 스냅샷 시작 및 중지

자동 규칙을 사용하지 않고 활성 스트림에서 이미지를 캡처해야 하는 경우 실시간 제어 기능을 사용하세요. 예를 들어 콘텐츠 검토 이벤트, 사용자가 트리거한 미리보기 또는 인시던트 아카이빙에 활용할 수 있습니다.

1. templateId와 최대 5개의 활성 스트림 전송 URL을 사용하여 StartRealTimeSnapshot을 호출합니다.
2. 각 캡처 세션에 대해 반환된 persistentId를 저장합니다.
3. 라이브 스트림과 함께 캡처를 종료하거나, 세션의 persistentId를 사용하여 StopRealTimeSnapshot을 호출해 캡처를 조기에 종료합니다.

중요: 반환된 모든 persistentId를 저장하세요. 특정 실시간 세션을 중지하고 나중에 작업 세부 정보를 조회하려면 persistentId가 필요합니다.

스냅샷 작업 및 파일 조회

캡처를 수동으로 시작한 후 또는 자동 캡처를 확인해야 할 때 작업 조회 API를 사용합니다. 이를 통해 작업을 찾고, 완료 여부를 확인하고, 실패 원인을 조사하고, 생성된 이미지를 찾을 수 있습니다.