PutMedia - Amazon Kinesis Video Streams
Sintaxe da SolicitaçãoURIParâmetros de solicitaçãoCorpo da SolicitaçãoSintaxe da respostaElementos de RespostaErrosExemplosConsulte também

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

PutMedia

Use isso API para enviar dados de mídia para um stream de vídeo do Kinesis.

nota

Você deve primeiro ligar GetDataEndpoint API para o para obter um endpoint. Em seguida, envie as PutMedia solicitações para esse endpoint usando o parâmetro --endpoint-url.

Na solicitação, você usa HTTP os cabeçalhos para fornecer informações de parâmetros, por exemplo, nome do stream, carimbo de data/hora e se o valor do timestamp é absoluto ou relativo a quando o produtor começou a gravar. Você usa o corpo da solicitação para enviar os dados de mídia. O Kinesis Video Streams suporta somente o formato de contêiner MKV Matroska () para enviar dados de mídia usando esse formato. API

Você tem as seguintes opções para enviar dados usando issoAPI:

  • Envie dados de mídia em tempo real: por exemplo, uma câmera de segurança pode enviar quadros em tempo real à medida que os gera. Essa abordagem minimiza a latência entre a gravação de vídeo e os dados enviados pela rede. Isso é chamado de produtor contínuo. Nesse caso, um aplicativo consumidor pode ler o stream em tempo real ou quando necessário.

  • Envie dados de mídia off-line (em lotes): por exemplo, uma câmera corporal pode gravar vídeo por horas e armazená-lo no dispositivo. Posteriormente, quando você conecta a câmera à porta de encaixe, a câmera pode iniciar uma PutMedia sessão para enviar dados para um stream de vídeo do Kinesis. Nesse cenário, a latência não é um problema.

Ao usar issoAPI, observe as seguintes considerações:

  • Você precisa especificar o streamName ou o streamARN, mas não os dois.

  • Para poder reproduzir a mídia no console ou viaHLS, a faixa 1 de cada fragmento deve conter vídeo codificado em h.264, o codecid nos metadados do fragmento deve ser “V_MPEG/ISO/AVC“e os metadados do fragmento devem incluir dados privados formatados do codec h.264. AVCC Opcionalmente, a faixa 2 de cada fragmento deve conter áudio AAC codificado, o codecid nos metadados do fragmento deve ser “A_ AAC “e os metadados do fragmento devem incluir dados privados do codec. AAC

  • Talvez você ache mais fácil usar uma única PutMedia sessão de longa duração e enviar um grande número de fragmentos de dados de mídia na carga útil. Para cada fragmento recebido, o Kinesis Video Streams envia uma ou mais confirmações. Possíveis considerações de rede podem fazer com que você não receba todas essas confirmações à medida que elas são geradas.

  • Você pode escolher várias PutMedia sessões consecutivas, cada uma com menos fragmentos, para garantir que você receba todas as confirmações do serviço em tempo real.

nota

Se você enviar dados para o mesmo stream em várias PutMedia sessões simultâneas, os fragmentos de mídia serão intercalados no stream. Você deve se certificar de que isso esteja OK no cenário do seu aplicativo.

Os seguintes limites se aplicam ao usar o PutMediaAPI:

  • Um cliente pode ligar PutMedia até cinco vezes por segundo por stream.

  • Um cliente pode enviar até cinco fragmentos por segundo por stream.

  • O Kinesis Video Streams lê dados de mídia a uma taxa de até 12,5 MB/segundo, ou 100 Mbps durante uma sessão. PutMedia

Observe as seguintes restrições. Nesses casos, o Kinesis Video Streams envia a confirmação de erro na resposta.

  • Fragmentos com códigos de tempo que se estendem por mais do que o limite máximo permitido e que contêm mais de 50 MB de dados não são permitidos.

  • Fragmentos contendo mais de três faixas não são permitidos. Cada quadro em cada fragmento deve ter o mesmo número de faixa de uma das faixas definidas no cabeçalho do fragmento. Além disso, cada fragmento deve conter pelo menos um quadro para cada faixa definida no cabeçalho do fragmento.

  • Cada fragmento deve conter pelo menos um quadro para cada faixa definida nos metadados do fragmento.

  • O carimbo de data/hora do quadro mais antigo em um fragmento deve ser posterior ao carimbo de data/hora do quadro mais recente no fragmento anterior.

  • Um MKV fluxo contendo mais de um MKV segmento ou contendo MKV elementos não permitidos (comotrack*) também resulta na confirmação de erro.

O Kinesis Video Streams armazena cada fragmento de entrada e metadados relacionados no que é chamado de “fragmento”. Os metadados do fragmento incluem o seguinte:

  • Os MKV cabeçalhos fornecidos no início da solicitação PutMedia

  • Os seguintes metadados específicos do Kinesis Video Streams para o fragmento:

    • server_timestamp- Registro de data e hora em que o Kinesis Video Streams começou a receber o fragmento.

    • producer_timestamp- Timestamp, quando o produtor começou a gravar o fragmento. O Kinesis Video Streams usa três informações recebidas na solicitação para calcular esse valor.

      • O valor do timecode do fragmento recebido no corpo da solicitação junto com o fragmento.

      • Dois cabeçalhos de solicitação: producerStartTimestamp (quando o produtor começou a gravar) e fragmentTimeCodeType (se o timecode do fragmento na carga é absoluto ou relativo).

      Em seguida, o Kinesis Video Streams producer_timestamp calcula o fragmento da seguinte forma:

      Se fragmentTimeCodeType for relativo, então

      producer_timestamp= producerStartTimeStamp + código de tempo do fragmento

      Se fragmentTimeCodeType for absoluto, então

      producer_timestamp= timecode do fragmento (convertido em milissegundos)

    • Número de fragmento exclusivo atribuído pelo Kinesis Video Streams.

nota

Quando você faz a GetMedia solicitação, o Kinesis Video Streams retorna um stream desses trechos. O cliente pode processar os metadados conforme necessário.

nota

Essa operação só está disponível para o AWS SDK for Java. Ele não é suportado em AWS SDKs outros idiomas.

nota

O Kinesis Video Streams não analisa e valida os dados privados do codec durante a ingestão e o arquivamento por meio do. PutMedia API KVSextrai e valida as informações necessárias dos dados privados do codec para MPEG -TS e MP4 empacotamento de fragmentos ao consumir o fluxo por meio do. HLS APIs

nota

Se um erro for gerado após invocar uma API mídia do Kinesis Video Streams, além do código de status e HTTP do corpo da resposta, ele incluirá as seguintes informações:

  • x-amz-ErrorTypeHTTPcabeçalho — contém um tipo de erro mais específico, além do que o código de HTTP status fornece.

  • x-amz-RequestIdHTTPcabeçalho — se você quiser relatar um problema AWS, a equipe de suporte poderá diagnosticar melhor o problema se receber o ID da solicitação.

Tanto o código de HTTP status quanto o ErrorType cabeçalho podem ser utilizados para tomar decisões programáticas sobre se os erros podem ser repetidos e sob quais condições, além de fornecer informações sobre quais ações o programador cliente pode precisar realizar para tentar novamente com sucesso.

Para obter mais informações, consulte a seção Erros na parte inferior deste tópico, bem como Erros comuns.

Sintaxe da Solicitação

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

URIParâmetros de solicitação

A solicitação usa os seguintes URI parâmetros.

FragmentTimecodeType

Você passa esse valor como x-amzn-fragment-timecode-type HTTP cabeçalho.

Indica se os timecodes nos fragmentos (carga útil, corpo da HTTP solicitação) são absolutos ou relativos a. producerStartTimestamp O Kinesis Video Streams usa essas informações para producer_timestamp calcular o fragmento recebido na solicitação, conforme descrito na visão geral. API

Valores Válidos: ABSOLUTE | RELATIVE

Obrigatório: Sim

ProducerStartTimestamp

Você passa esse valor como x-amzn-producer-start-timestamp HTTP cabeçalho.

Esse é o timestamp do produtor no qual o produtor começou a gravar a mídia (não o timestamp dos fragmentos específicos na solicitação).

StreamARN

Você passa esse valor como x-amzn-stream-arn HTTP cabeçalho.

Nome de recurso da Amazon (ARN) do stream de vídeo do Kinesis em que você deseja escrever o conteúdo de mídia. Se você não especificar ostreamARN, deverá especificar streamName o.

Restrições de comprimento: tamanho mínimo de 1. Tamanho máximo de 1.024.

Padrão: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

StreamName

Você passa esse valor como x-amzn-stream-name HTTP cabeçalho.

Nome do stream de vídeo do Kinesis em que você deseja gravar o conteúdo de mídia. Se você não especificar ostreamName, deverá especificar streamARN o.

Restrições de tamanho: tamanho mínimo 1. Tamanho máximo de 256.

Padrão: [a-zA-Z0-9_.-]+

Corpo da Solicitação

A solicitação aceita os dados binários a seguir.

Payload

O conteúdo de mídia a ser gravado no stream de vídeo do Kinesis. Na implementação atual, o Kinesis Video Streams suporta somente o formato de contêiner MKV Matroska () com um único segmento. MKV Um segmento pode conter um ou mais clusters.

nota

Cada MKV cluster é mapeado para um fragmento de stream de vídeo do Kinesis. Qualquer que seja a duração do cluster que você escolher, se tornará a duração do fragmento.

Sintaxe da resposta

HTTP/1.1 200

Payload

Elementos de Resposta

Se a ação for bem-sucedida, o serviço retornará uma resposta HTTP de 200.

A resposta retorna o seguinte como HTTP corpo.

Payload

Depois que o Kinesis Video Streams PutMedia recebe com sucesso uma solicitação, o serviço valida os cabeçalhos da solicitação. O serviço então começa a ler a carga e primeiro envia uma resposta de HTTP 200.

Em seguida, o serviço retorna um fluxo contendo uma série de JSON objetos (Acknowledgementobjetos) separados por novas linhas. As confirmações são recebidas na mesma conexão na qual os dados de mídia são enviados. Pode haver muitas confirmações para uma PutMedia solicitação. Cada um Acknowledgement consiste nos seguintes pares de valores-chave:

  • AckEventType- Tipo de evento que a confirmação representa.

    • Armazenamento em buffer: o Kinesis Video Streams começou a receber o fragmento. O Kinesis Video Streams envia a primeira confirmação de buffering quando o primeiro byte do fragmento de dados é recebido.

    • Recebido: o Kinesis Video Streams recebeu o fragmento inteiro. Se você não configurou o stream para manter os dados, o produtor pode parar de armazenar o fragmento em buffer ao receber essa confirmação.

    • Persistente: o Kinesis Video Streams persistiu no fragmento (por exemplo, no Amazon S3). Você receberá essa confirmação se tiver configurado o fluxo para persistir os dados. Depois de receber essa confirmação, o produtor pode parar de armazenar o fragmento em buffer.

    • Erro: o Kinesis Video Streams encontrou um erro ao processar o fragmento. Você pode revisar o código de erro e determinar o próximo curso de ação.

    • Inativo: a PutMedia sessão está em andamento. No entanto, o Kinesis Video Streams não está recebendo dados no momento. O Kinesis Video Streams envia essa confirmação periodicamente por até 30 segundos após os últimos dados recebidos. Se nenhum dado for recebido em 30 segundos, o Kinesis Video Streams fechará a solicitação.

      nota

      Esse reconhecimento pode ajudar o produtor a determinar se a PutMedia conexão está ativa, mesmo que não esteja enviando dados.

  • FragmentTimecode- Fragmente o timecode para o qual a confirmação é enviada.

    O elemento pode estar ausente se AckEventType estiver inativo.

  • FragmentNumber- Número do fragmento gerado pelo Kinesis Video Streams para o qual a confirmação é enviada.

  • ErrorIde ErrorCode - Se AckEventType forError, esse campo fornecerá o código de erro correspondente. A seguir está a lista de erros IDs e seus códigos de erro e mensagens de erro correspondentes:

    • 4000 - STREAM _ READ _ ERROR - Erro ao ler o fluxo de dados.

    • 4001 - MAX _ _ FRAGMENT SIZE _ REACHED - O tamanho do fragmento é maior que o limite máximo, 50 MB, permitido.

    • 4002 - MAX _ _ FRAGMENT DURATION _ REACHED - A duração do fragmento é maior que o limite máximo permitido.

    • 4003 - MAX _ _ CONNECTION DURATION _ REACHED - A duração da conexão é maior que o limite máximo permitido.

    • 4004 - FRAGMENT _ _ TIMECODE _ LESSER THAN _ PREVIOUS - O timecode do fragmento é menor que o timecode anterior (em uma PutMedia chamada, você não pode enviar fragmentos fora de ordem).

    • 4005 - MORE _ THAN _ ALLOWED _ TRACKS _ FOUND - Mais de uma faixa é encontrada emMKV. (obsoleto)

    • 4006 - INVALID _ MKV _ DATA - Falha ao analisar o fluxo de entrada como formato válidoMKV.

    • 4007 - INVALID _ PRODUCER _ TIMESTAMP - Carimbo de data/hora do produtor inválido.

    • 4008 - STREAM _ NOT _ ACTIVE - O fluxo não existe mais (excluído).

    • 4009 - FRAGMENT _ _ METADATA LIMIT _ REACHED - Limite de metadados do fragmento atingido. Consulte a seção Limites do guia do desenvolvedor.

    • 4010 - TRACK _ NUMBER _ MISMATCH - O número da faixa em um MKV quadro não coincide com as faixas no MKV cabeçalho.

    • 4011 - FRAMES _ MISSING _ FOR _ TRACK - O fragmento não continha nenhum quadro para pelo menos uma das faixas no MKV cabeçalho.

    • 4012 - INVALID _ FRAGMENT _ METADATA - O nome dos metadados do fragmento não pode começar com a string. AWS_

    • 4500 - KMS _ _ KEY ACCESS _ DENIED - O acesso à KMS chave especificada do stream é negado.

    • 4501 - KMS _ KEY _ DISABLED - A KMS chave especificada do stream está desativada.

    • 4502 - KMS _ _ KEY VALIDATION _ ERROR - A KMS chave especificada do stream falhou na validação.

    • 4503 - KMS _ KEY _ UNAVAILABLE - A KMS chave especificada do stream não está disponível.

    • 4504 - KMS _ _ KEY INVALID _ USAGE - Uso inválido da chave especificada do fluxo. KMS

    • 4505 - KMS _ _ KEY INVALID _ STATE - A KMS chave especificada do fluxo está em um estado inválido.

    • 4506 - KMS _ _ KEY NOT _ FOUND - A KMS chave especificada do fluxo não foi encontrada.

    • 5000 - INTERNAL _ ERROR - Erro de serviço interno.

    • 5001 - ARCHIVAL _ ERROR - O Kinesis Video Streams falhou em persistir fragmentos no armazenamento de dados.

nota

O produtor, ao enviar a carga útil de uma PutMedia solicitação de longa duração, deve ler a resposta para receber confirmações. Um produtor pode receber partes de confirmações ao mesmo tempo, devido ao buffer em um servidor proxy intermediário. Um produtor que deseja receber confirmações em tempo hábil pode enviar menos fragmentos em cada solicitação. PutMedia

Erros

Para obter informações sobre os erros comuns retornados pelas ações, consulte Erros comuns.

ClientLimitExceededException

O Kinesis Video Streams limitou a solicitação porque você excedeu o limite permitido de chamadas de clientes. Tente fazer a ligação mais tarde.

HTTPCódigo de status: 400

ConnectionLimitExceededException

O Kinesis Video Streams limitou a solicitação porque você excedeu o limite permitido de conexões de clientes.

HTTPCódigo de status: 400

InvalidArgumentException

O valor desse parâmetro de entrada é inválido.

HTTPCódigo de status: 400

InvalidEndpointException

O chamador usou o endpoint errado para gravar dados em um stream. Ao receber essa exceção, o usuário deve chamar GetDataEndpoint com APIName set to PUT_MEDIA e usar o endpoint from response para invocar a próxima PutMedia chamada.

HTTPCódigo de status: 400

NotAuthorizedException

O chamador não está autorizado a realizar uma operação em determinado stream ou o token expirou.

HTTPCódigo de status: 401

ResourceNotFoundException

Código de status: 404, O fluxo com o nome fornecido não existe.

HTTPCódigo de status: 404

Exemplos

Formato de reconhecimento

O formato da confirmação é o seguinte:

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

Consulte também

Para obter mais informações sobre como usar isso API em um idioma específico AWS SDKs, consulte o seguinte: