PutMedia - Amazon Kinesis Video Streams
Request SyntaxURI요청 파라미터요청 본문Response SyntaxResponse ElementsErrors예시참고

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

PutMedia

이를 API 사용하여 Kinesis 비디오 스트림으로 미디어 데이터를 전송할 수 있습니다.

참고

엔드포인트를 GetDataEndpoint API 가져오려면 먼저 를 호출해야 합니다. 그런 다음 PutMedia --endpoint-url 파라미터를 사용하여 이 엔드포인트로 요청을 전송합니다.

요청에서 HTTP 헤더를 사용하여 매개 변수 정보 (예: 스트림 이름, 타임스탬프, 타임스탬프 값이 절대값인지 아니면 제작자가 녹화를 시작한 시점을 기준으로 하는지 여부) 를 제공합니다. 요청 본문을 사용하여 미디어 데이터를 전송합니다. Kinesis Video Streams는 이를 사용하여 미디어 데이터를 전송하는 Matroska MKV () 컨테이너 형식만 지원합니다. API

이를 사용하여 데이터를 전송하는 옵션은 다음과 같습니다. API

  • 미디어 데이터 실시간 전송: 예를 들어 보안 카메라가 프레임을 생성하면서 실시간으로 프레임을 전송할 수 있습니다. 이 접근 방식은 비디오 녹화와 유선으로 전송되는 데이터 사이의 지연 시간을 최소화합니다. 이를 연속 프로듀서라고 합니다. 이 경우 소비자 애플리케이션은 실시간으로 또는 필요할 때 스트림을 읽을 수 있습니다.

  • 미디어 데이터를 오프라인으로 전송 (일괄): 예를 들어 바디 카메라가 몇 시간 동안 비디오를 녹화하고 이를 기기에 저장할 수 있습니다. 나중에 카메라를 도킹 포트에 연결하면 카메라가 PutMedia 세션을 시작하여 Kinesis 비디오 스트림으로 데이터를 전송할 수 있습니다. 이 시나리오에서는 지연 시간이 문제가 되지 않습니다.

이 API 방법을 사용할 때는 다음 고려 사항을 참고하십시오.

  • streamName 또는 streamARN 중 하나만 지정해야 하지만 두 가지 모두 지정해서는 안 됩니다.

  • 콘솔에서 또는 콘솔을 통해 미디어를 재생하려면 각 프래그먼트의 트랙 1에는 h.264로 인코딩된 비디오가 포함되어야 하고HLS, 프래그먼트 메타데이터의 CodeCid는 “V_ MPEGISO/AVC“여야 하며, 프래그먼트 메타데이터에는 형식이 지정된 h.264 코덱 개인 데이터가 포함되어야 합니다. AVCC 선택적으로 각 프래그먼트의 트랙 2에는 AAC 인코딩된 오디오가 포함되어야 하고, 프래그먼트 메타데이터의 CodeCid는 “A_ AAC “여야 하며, 프래그먼트 메타데이터에는 AAC 코덱 프라이빗 데이터가 포함되어야 합니다.

  • 장기간 실행되는 단일 PutMedia 세션을 사용하고 페이로드에 대량의 미디어 데이터 프래그먼트를 전송하는 것이 더 쉬울 수도 있습니다. Kinesis Video Streams는 수신된 각 프래그먼트에 대해 하나 이상의 승인을 보냅니다. 잠재적인 네트워크 고려 사항으로 인해 이러한 승인이 생성될 때 모든 승인을 받지 못할 수 있습니다.

  • 서비스로부터 모든 승인을 실시간으로 받을 수 있도록 하기 위해 각 세션마다 프래그먼트 수가 적은 연속 PutMedia 세션을 여러 개 선택할 수 있습니다.

참고

여러 개의 동시 PutMedia 세션에서 동일한 스트림으로 데이터를 전송하는 경우 미디어 프래그먼트는 스트림에서 인터리빙됩니다. 애플리케이션 시나리오에서 이 문제가 없는지 확인해야 합니다.

를 사용할 때는 다음과 같은 제한이 적용됩니다 PutMediaAPI.

  • 클라이언트는 스트림당 초당 PutMedia 최대 5회까지 호출할 수 있습니다.

  • 클라이언트는 스트림당 초당 최대 5개의 프래그먼트를 전송할 수 있습니다.

  • Kinesis Video Streams는 세션 중에 최대 12.5MB/초 또는 100Mbps의 속도로 미디어 데이터를 읽습니다. PutMedia

다음 제약 조건에 유의하십시오. 이러한 경우 Kinesis Video Streams는 응답으로 오류 승인을 보냅니다.

  • 최대 허용 한도보다 긴 타임 코드가 있고 50MB를 초과하는 데이터를 포함하는 프래그먼트는 허용되지 않습니다.

  • 3개 이상의 트랙을 포함하는 프래그먼트는 허용되지 않습니다. 모든 프래그먼트의 각 프레임은 프래그먼트 헤더에 정의된 트랙 중 하나와 동일한 트랙 번호를 가져야 합니다. 또한 모든 프래그먼트는 프래그먼트 헤더에 정의된 각 트랙에 대해 하나 이상의 프레임을 포함해야 합니다.

  • 각 프래그먼트는 프래그먼트 메타데이터에 정의된 각 트랙에 대해 하나 이상의 프레임을 포함해야 합니다.

  • 프래그먼트에서 가장 이른 프레임 타임스탬프는 이전 프래그먼트의 최신 프레임 타임스탬프 이후여야 합니다.

  • MKV스트림이 두 개 이상의 MKV 세그먼트를 포함하거나 허용되지 않는 MKV 요소 (예:track*) 를 포함하는 경우에도 오류 확인이 발생합니다.

Kinesis Video Streams는 수신되는 각 프래그먼트와 관련 메타데이터를 소위 “청크”에 저장합니다. 프래그먼트 메타데이터에는 다음이 포함됩니다.

  • 요청 시작 시 제공된 MKV 헤더 PutMedia

  • 프래그먼트에 대한 다음과 같은 Kinesis Video Streams 관련 메타데이터:

    • server_timestamp- Kinesis Video Streams가 프래그먼트 수신을 시작한 시점의 타임스탬프입니다.

    • producer_timestamp- 타임스탬프: 프로듀서가 프래그먼트 녹화를 시작한 시점의 타임스탬프. Kinesis Video Streams는 요청에서 받은 세 가지 정보를 사용하여 이 값을 계산합니다.

      • 요청 본문에서 프래그먼트와 함께 수신된 프래그먼트 타임코드 값입니다.

      • 두 개의 요청 헤더: producerStartTimestamp (제작자가 녹화를 시작한 시점) 및 fragmentTimeCodeType (페이로드의 프래그먼트 타임코드가 절대적인지 상대적인지 여부).

      그러면 Kinesis Video Streams는 다음과 producer_timestamp 같이 프래그먼트에 대한 값을 계산합니다.

      fragmentTimeCodeType상대적인 값인 경우

      producer_timestamp= producerStartTimeStamp + 프래그먼트 타임코드

      fragmentTimeCodeType절대값인 경우

      producer_timestamp= 프래그먼트 타임코드 (밀리초로 변환)

    • Kinesis Video Streams에서 할당한 고유한 프래그먼트 번호입니다.

참고

GetMedia요청을 하면 Kinesis Video Streams는 이러한 청크의 스트림을 반환합니다. 클라이언트는 필요에 따라 메타데이터를 처리할 수 있습니다.

참고

이 작업은 AWS SDK Java용 에서만 사용할 수 있습니다. 다른 언어에서는 AWS SDKs 지원되지 않습니다.

참고

Kinesis Video Streams는 를 통해 수집 및 보관하는 동안 코덱 개인 데이터를 파싱하고 검증하지 않습니다. PutMedia API KVS를 통해 스트림을 사용할 때 코덱 전용 데이터에서 MPEG -TS 및 프래그먼트 패키징에 필요한 정보를 추출하고 MP4 검증합니다. HLS APIs

참고

Kinesis Video Streams 미디어를 호출한 후 오류가 발생하는 경우API, HTTP 상태 코드 및 응답 본문 외에도 다음과 같은 정보가 포함됩니다.

  • x-amz-ErrorTypeHTTP헤더 - HTTP 상태 코드가 제공하는 내용 외에도 보다 구체적인 오류 유형을 포함합니다.

  • x-amz-RequestIdHTTP헤더 — 문제를 신고하려는 경우 지원 팀에서 요청 ID를 제공하면 문제를 더 잘 진단할 수 있습니다. AWS

HTTP상태 코드와 ErrorType 헤더를 모두 사용하여 오류를 재시도할 수 있는지 여부와 조건에 대해 프로그래밍 방식으로 결정할 수 있으며, 클라이언트 프로그래머가 성공적으로 다시 시도하기 위해 취해야 할 조치에 대한 정보도 제공할 수 있습니다.

자세한 내용은 이 항목 하단의 오류 섹션 및 일반적인 오류를 참조하십시오.

Request Syntax

POST /putMedia HTTP/1.1
x-amzn-stream-name: StreamName
x-amzn-stream-arn: StreamARN
x-amzn-fragment-timecode-type: FragmentTimecodeType
x-amzn-producer-start-timestamp: ProducerStartTimestamp

Payload

URI요청 파라미터

요청은 다음 URI 파라미터를 사용합니다.

FragmentTimecodeType

이 값을 x-amzn-fragment-timecode-type HTTP 헤더로 전달합니다.

프래그먼트 (페이로드, HTTP 요청 본문) 의 타임코드가 절대적인지 상대적인지를 나타냅니다. producerStartTimestamp Kinesis Video Streams는 개요에 설명된 대로 이 정보를 사용하여 요청에서 수신한 프래그먼트에 대해 계산합니다producer_timestamp. API

유효 값: ABSOLUTE | RELATIVE

필수 사항 여부: 예

ProducerStartTimestamp

이 값을 x-amzn-producer-start-timestamp HTTP 헤더로 전달합니다.

이는 프로듀서가 미디어 녹화를 시작한 시점의 프로듀서 타임스탬프입니다 (요청에 있는 특정 프래그먼트의 타임스탬프는 아님).

StreamARN

이 값을 헤더로 전달합니다. x-amzn-stream-arn HTTP

미디어 콘텐츠를 작성하려는 Kinesis 비디오 스트림의 Amazon 리소스 이름 (ARN). 를 지정하지 않는 경우 를 지정해야 합니다. streamARN streamName

길이 제약: 최소 길이 1. 최대 길이는 1024입니다.

패턴: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

StreamName

이 값을 x-amzn-stream-name HTTP 헤더로 전달합니다.

미디어 콘텐츠를 작성하려는 Kinesis 비디오 스트림의 이름입니다. 를 지정하지 않는 경우 를 지정해야 합니다. streamName streamARN

길이 제약: 최소 길이 1. 최대 길이는 256입니다.

Pattern: [a-zA-Z0-9_.-]+

요청 본문

요청은 다음의 이진 데이터를 허용합니다.

Payload

Kinesis 비디오 스트림에 쓸 미디어 콘텐츠입니다. 현재 구현에서 Kinesis Video Streams는 단일 세그먼트의 Matroska MKV () 컨테이너 형식만 지원합니다. MKV 세그먼트는 하나 이상의 클러스터를 포함할 수 있습니다.

참고

각 MKV 클러스터는 Kinesis 비디오 스트림 프래그먼트에 매핑됩니다. 어떤 클러스터 기간을 선택하든 프래그먼트 지속 시간이 됩니다.

Response Syntax

HTTP/1.1 200

Payload

Response Elements

작업이 성공하면 서비스는 HTTP 200개의 응답을 다시 보냅니다.

응답은 다음을 HTTP 본문으로 반환합니다.

Payload

Kinesis Video Streams가 요청을 성공적으로 PutMedia 수신한 후 서비스는 요청 헤더를 검증합니다. 그러면 서비스가 페이로드 읽기를 시작하고 먼저 200 응답을 보냅니다. HTTP

그러면 서비스는 줄바꿈으로 구분된 일련의 JSON 객체 (Acknowledgement객체) 를 포함하는 스트림을 반환합니다. 확인은 미디어 데이터가 전송되는 동일한 연결에서 수신됩니다. 요청에는 여러 개의 승인이 있을 수 있습니다. PutMedia Acknowledgement각각은 다음과 같은 키-값 쌍으로 구성됩니다.

  • AckEventType- 승인이 나타내는 이벤트 유형.

    • 버퍼링: Kinesis Video Streams가 프래그먼트를 수신하기 시작했습니다. Kinesis Video Streams는 프래그먼트 데이터의 첫 바이트가 수신되면 첫 번째 버퍼링 승인을 보냅니다.

    • 수신: Kinesis Video Streams가 전체 프래그먼트를 수신했습니다. 데이터를 유지하도록 스트림을 구성하지 않은 경우 프로듀서는 이 확인을 받으면 프래그먼트의 버퍼링을 중단할 수 있습니다.

    • 지속됨: Kinesis Video Streams가 프래그먼트를 유지했습니다 (예: Amazon S3에). 데이터를 유지하도록 스트림을 구성한 경우 이 승인을 받게 됩니다. 이 승인을 받은 후 제작자는 프래그먼트의 버퍼링을 중단할 수 있습니다.

    • 오류: 프래그먼트를 처리하는 동안 Kinesis Video Streams에서 오류가 발생했습니다. 오류 코드를 검토하고 다음 조치를 결정할 수 있습니다.

    • 유휴: PutMedia 세션이 진행 중입니다. 하지만 Kinesis Video Streams는 현재 데이터를 수신하지 않습니다. Kinesis Video Streams는 마지막으로 데이터를 수신한 후 최대 30초 동안 주기적으로 이 확인 메시지를 전송합니다. 30초 내에 데이터가 수신되지 않으면 Kinesis Video Streams는 요청을 종료합니다.

      참고

      이 확인은 생산자가 데이터를 전송하지 않는 경우에도 PutMedia 연결이 활성 상태인지 판단하는 데 도움이 될 수 있습니다.

  • FragmentTimecode- 승인이 전송되는 프래그먼트 타임코드.

    가 Idle인 경우 요소가 누락될 수 있습니다. AckEventType

  • FragmentNumber- Kinesis Video Streams에서 생성한 프래그먼트 번호로서 확인이 전송됩니다.

  • ErrorId및 ErrorCode - 인 경우 AckEventType 이 필드에 해당 오류 Error 코드가 제공됩니다. 다음은 오류 IDs 및 해당 오류 코드 및 오류 메시지 목록입니다.

    • 4000 - STREAM READ _ ERROR - 데이터 스트림을 읽는 중 오류가 발생했습니다.

    • 4001 - MAX _ FRAGMENT SIZE _ REACHED - 프래그먼트 크기가 최대 제한값인 50MB를 초과했습니다 (허용).

    • 4002 - MAX _ FRAGMENT DURATION _ REACHED - 프래그먼트 지속 시간이 최대 허용 한도보다 깁니다.

    • 4003 - MAX _ CONNECTION DURATION _ REACHED - 연결 기간이 최대 허용 임계값보다 깁니다.

    • 4004 - FRAGMENT _ _ TIMECODE LESSER THAN _ PREVIOUS - 프래그먼트 타임코드가 이전 타임코드 타임 코드보다 작습니다 (PutMedia호출 내에서는 프래그먼트를 잘못된 순서로 보낼 수 없음).

    • 4005 - MORE _ _ THAN ALLOWED TRACKS _ FOUND - 에서 트랙이 두 개 이상 있습니다. MKV (더 이상 사용되지 않음)

    • 4006 - INVALID _ MKV _ DATA - 입력 스트림을 유효한 형식으로 파싱하지 못했습니다. MKV

    • 4007 - INVALID _ PRODUCER _ TIMESTAMP - 프로듀서 타임스탬프가 잘못되었습니다.

    • 4008 - STREAM _ NOT _ ACTIVE - 스트림이 더 이상 존재하지 않음 (삭제됨).

    • 4009 - FRAGMENT _ METADATA LIMIT _ REACHED - 프래그먼트 메타데이터 한도에 도달했습니다. 개발자 가이드의 제한 섹션을 참조하십시오.

    • 4010 - TRACK NUMBER _ _ MISMATCH - MKV 프레임의 트랙 번호가 MKV 헤더의 트랙과 일치하지 않습니다.

    • 4011 - FRAMES _ MISSING FOR _ TRACK - 헤더에 있는 트랙 중 하나 이상의 프레임이 프래그먼트에 포함되지 않았습니다. MKV

    • 4012 - INVALID _ FRAGMENT _ METADATA - 프래그먼트 메타데이터 이름은 문자열로 시작할 수 없습니다. AWS_

    • 4500 - KMS _ KEY ACCESS _ DENIED - 스트림의 지정된 KMS 키에 대한 액세스가 거부되었습니다.

    • 4501 - KMS _ KEY _ DISABLED - 스트림의 지정된 KMS 키가 비활성화되었습니다.

    • 4502 - KMS _ KEY VALIDATION _ ERROR - 스트림의 지정된 KMS 키가 검증에 실패했습니다.

    • 4503 - KMS _ KEY _ UNAVAILABLE - 스트림의 지정된 KMS 키를 사용할 수 없습니다.

    • 4504 - KMS _ KEY INVALID _ USAGE - 스트림의 지정된 키가 잘못 사용되었습니다. KMS

    • 4505 - KMS _ KEY INVALID _ STATE - 스트림의 지정된 KMS 키가 잘못된 상태입니다.

    • 4506 - KMS _ KEY NOT _ FOUND - 스트림의 지정된 KMS 키를 찾을 수 없습니다.

    • 5000 - INTERNAL _ ERROR - 내부 서비스 오류입니다.

    • 5001 - ARCHIVAL _ ERROR - Kinesis Video Streams가 데이터 스토어에 프래그먼트를 지속시키지 못했습니다.

참고

제작자는 장기 실행 PutMedia 요청을 위해 페이로드를 전송하는 동안 응답을 읽고 승인을 받아야 합니다. 중간 프록시 서버의 버퍼링으로 인해 프로듀서가 동시에 많은 양의 승인을 받을 수 있습니다. 적시에 승인을 받고자 하는 프로듀서는 각 요청에서 보내는 프래그먼트의 수를 줄일 수 있습니다. PutMedia

Errors

모든 작업에 공통되는 오류에 대한 내용은 일반적인 오류 섹션을 참조하십시오.

ClientLimitExceededException

허용된 클라이언트 호출 한도를 초과했기 때문에 Kinesis Video Streams가 요청 병목 현상을 일으켰습니다. 나중에 전화를 걸어 보세요.

HTTP상태 코드: 400

ConnectionLimitExceededException

허용된 클라이언트 연결 제한을 초과했기 때문에 Kinesis Video Streams가 요청 병목 현상을 일으켰습니다.

HTTP상태 코드: 400

InvalidArgumentException

이 입력 매개변수의 값이 유효하지 않습니다.

HTTP상태 코드: 400

InvalidEndpointException

호출자가 잘못된 엔드포인트를 사용하여 스트림에 데이터를 썼습니다. 이러한 예외를 수신한 사용자는 APIName set GetDataEndpoint to로 PUT_MEDIA 호출하고 응답의 엔드포인트를 사용하여 다음 PutMedia 호출을 호출해야 합니다.

HTTP상태 코드: 400

NotAuthorizedException

호출자가 지정된 스트림에서 작업을 수행할 권한이 없거나 토큰이 만료되었습니다.

HTTP상태 코드: 401

ResourceNotFoundException

상태 코드: 404, 지정한 이름의 스트림이 존재하지 않습니다.

HTTP상태 코드: 404

예시

승인 형식

승인 형식은 다음과 같습니다.

{
       Acknowledgement : {
          "EventType": enum
          "FragmentTimecode": Long,
          "FragmentNumber": Long,
          "ErrorId" : String       
      }
}

참고

언어별 사용 방법에 대한 자세한 내용은 AWS SDKs 다음을 참조하십시오. API