PutMedia

Utilice esta API para enviar datos multimedia a una transmisión de vídeo de Kinesis.

nota

Primero debe llamar a la GetDataEndpoint API para obtener un punto final. A continuación, envíe las PutMedia solicitudes a este punto final mediante el parámetro --endpoint-url.

En la solicitud, usa los encabezados HTTP para proporcionar información sobre los parámetros, por ejemplo, el nombre de la transmisión, la marca de tiempo y si el valor de la marca de tiempo es absoluto o relativo al momento en que el productor comenzó a grabar. Utiliza el cuerpo de la solicitud para enviar los datos multimedia. Kinesis Video Streams solo admite el formato contenedor Matroska (MKV) para enviar datos multimedia mediante esta API.

Dispone de las siguientes opciones para enviar datos mediante esta API:

• Envíe datos multimedia en tiempo real: por ejemplo, una cámara de seguridad puede enviar fotogramas en tiempo real a medida que los genera. Este enfoque minimiza la latencia entre la grabación de vídeo y los datos enviados por cable. Esto se conoce como productor continuo. En este caso, una aplicación de consumo puede leer la transmisión en tiempo real o cuando sea necesario.

• Envía datos multimedia sin conexión (en lotes): por ejemplo, una cámara corporal puede grabar vídeo durante horas y almacenarlo en el dispositivo. Más adelante, cuando conecte la cámara al puerto de acoplamiento, la cámara podrá iniciar una PutMedia sesión para enviar datos a una transmisión de vídeo de Kinesis. En este escenario, la latencia no es un problema.

Cuando utilices esta API, ten en cuenta las siguientes consideraciones:

• Debe especificar streamName o streamARN, pero no ambos.

• Para poder reproducir el contenido multimedia en la consola o mediante HLS, la pista 1 de cada fragmento debe contener vídeo codificado en H.264, el codecID de los metadatos del fragmento debe ser «V_MPEG/ISO/AVC» y los metadatos del fragmento deben incluir datos privados del códec h.264 con formato AVCC. Opcionalmente, la pista 2 de cada fragmento debe contener audio codificado en AAC, el codeCid de los metadatos del fragmento debe ser «A_AAC» y los metadatos del fragmento deben incluir datos privados del códec AAC.

• Puede que le resulte más fácil utilizar una sola PutMedia sesión de larga duración y enviar una gran cantidad de fragmentos de datos multimedia en la carga útil. Por cada fragmento recibido, Kinesis Video Streams envía uno o más acuses de recibo. Es posible que, debido a posibles problemas de red, no reciba todos estos reconocimientos a medida que se generan.

• Puede elegir varias PutMedia sesiones consecutivas, cada una con menos fragmentos, para asegurarse de recibir todos los acuses de recibo del servicio en tiempo real.

nota

Si envías datos a la misma transmisión en varias PutMedia sesiones simultáneas, los fragmentos multimedia se intercalan en la transmisión. Debe asegurarse de que esto es correcto en el escenario de su aplicación.

Al utilizar la PutMedia API, se aplican los siguientes límites:

• Un cliente puede llamar PutMedia hasta cinco veces por segundo por transmisión.

• Un cliente puede enviar hasta cinco fragmentos por segundo por transmisión.

• Kinesis Video Streams lee los datos multimedia a una velocidad de hasta 12,5 MB/segundo o 100 Mbps durante una sesión. PutMedia

Tenga en cuenta las siguientes restricciones. En estos casos, Kinesis Video Streams envía el acuse de recibo de error en la respuesta.

• No se permiten los fragmentos con códigos de tiempo que superen el límite máximo permitido y que contengan más de 50 MB de datos.

• No se permiten los fragmentos que contengan más de tres pistas. Cada fotograma de cada fragmento debe tener el mismo número de pista que una de las pistas definidas en el encabezado del fragmento. Además, cada fragmento debe contener al menos un fotograma para cada pista definida en el encabezado del fragmento.

• Cada fragmento debe contener al menos un fotograma para cada pista definida en los metadatos del fragmento.

• La marca de tiempo del primer fotograma de un fragmento debe ser posterior a la última del fragmento anterior.

• Si una secuencia MKV contiene más de un segmento MKV o contiene elementos MKV no permitidos (por ejemplotrack*), también se reconoce el error.

Kinesis Video Streams almacena cada fragmento entrante y los metadatos relacionados en lo que se denomina un «fragmento». Los metadatos del fragmento incluyen lo siguiente:

• Los encabezados MKV proporcionados al inicio de la solicitud PutMedia

• Los siguientes metadatos específicos de Kinesis Video Streams para el fragmento:

  • server_timestamp- Marca de tiempo en que Kinesis Video Streams empezó a recibir el fragmento.

  • producer_timestamp- Marca de tiempo, cuando el productor empezó a grabar el fragmento. Kinesis Video Streams utiliza tres datos recibidos en la solicitud para calcular este valor.

    • El valor del código de tiempo del fragmento recibido en el cuerpo de la solicitud junto con el fragmento.

    • Dos encabezados de solicitud: producerStartTimestamp (cuando el productor comenzó a grabar) y fragmentTimeCodeType (si el código de tiempo del fragmento de la carga útil es absoluto o relativo).

    A continuación, Kinesis Video Streams calcula producer_timestamp el fragmento de la siguiente manera:

    Si fragmentTimeCodeType es relativo, entonces

    producer_timestamp= producerStartTimeStamp + código de tiempo del fragmento

    Si fragmentTimeCodeType es absoluto, entonces

    producer_timestamp= código de tiempo del fragmento (convertido a milisegundos)

  • Número de fragmento único asignado por Kinesis Video Streams.

nota

Al realizar la GetMedia solicitud, Kinesis Video Streams devuelve una transmisión de estos fragmentos. El cliente puede procesar los metadatos según sea necesario.

nota

Esta operación solo está disponible para el AWS SDK para Java. No se admite en AWS los SDK de otros lenguajes.

nota

Kinesis Video Streams no analiza ni valida los datos privados del códec durante la ingesta y el archivado mediante la API. PutMedia KVS extrae y valida la información necesaria de los datos privados del códec para empaquetar los fragmentos MPEG-TS y MP4 al consumir la transmisión a través de las API de HLS.

nota

Si se produce un error después de invocar una API multimedia de Kinesis Video Streams, además del código de estado HTTP y el cuerpo de la respuesta, se incluye la siguiente información:

• x-amz-ErrorTypeEncabezado HTTP: contiene un tipo de error más específico además del que proporciona el código de estado HTTP.

• x-amz-RequestIdEncabezado HTTP: si quieres informar de un problema AWS, el equipo de soporte puede diagnosticar mejor el problema si se le proporciona el identificador de la solicitud.

Tanto el código de estado HTTP como el ErrorType encabezado se pueden utilizar para tomar decisiones programáticas sobre si los errores se pueden volver a cometer y en qué condiciones, así como para proporcionar información sobre las medidas que el programador del cliente podría tener que tomar para volver a intentarlo correctamente.

Para obtener más información, consulte la sección de errores al final de este tema, así como la sección Errores comunes.

Sintaxis de la solicitud

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

Parámetros de solicitud del URI

La solicitud utiliza los siguientes parámetros URI.

FragmentTimecodeType

Este valor se transfiere como el encabezado HTTP x-amzn-fragment-timecode-type.

Indica si los códigos de tiempo de los fragmentos (carga útil, cuerpo de la solicitud HTTP) son absolutos o relativos a. producerStartTimestamp Kinesis Video Streams utiliza esta información para calcular producer_timestamp el fragmento recibido en la solicitud, tal y como se describe en la descripción general de la API.

Valores válidos: ABSOLUTE | RELATIVE

Obligatorio: sí

ProducerStartTimestamp

Este valor se transfiere como el encabezado HTTP x-amzn-producer-start-timestamp.

Esta es la marca de tiempo del productor en la que el productor comenzó a grabar el contenido multimedia (no la marca de tiempo de los fragmentos específicos de la solicitud).

StreamARN

Este valor se transfiere como el encabezado HTTP x-amzn-stream-arn.

Nombre del recurso de Amazon (ARN) de la transmisión de vídeo de Kinesis en la que desea escribir el contenido multimedia. Si no especifica elstreamARN, debe especificar el. streamName

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 1024 caracteres.

Patrón: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

StreamName

Este valor se transfiere como el encabezado HTTP x-amzn-stream-name.

Nombre de la transmisión de vídeo de Kinesis en la que desea escribir el contenido multimedia. Si no especifica elstreamName, debe especificar elstreamARN.

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 256 caracteres.

Patrón: [a-zA-Z0-9_.-]+

Cuerpo de la solicitud

La solicitud acepta los siguientes datos binarios.

Payload

El contenido multimedia que se grabará en la transmisión de vídeo de Kinesis. En la implementación actual, Kinesis Video Streams solo admite el formato contenedor Matroska (MKV) con un único segmento MKV. Un segmento puede contener uno o más clústeres.

nota

Cada clúster MKV se asigna a un fragmento de transmisión de vídeo de Kinesis. La duración del clúster que elija se convierte en la duración del fragmento.

Sintaxis de la respuesta

HTTP/1.1 200

Payload

Elementos de respuesta

Si la acción se realiza correctamente, el servicio devuelve una respuesta HTTP 200.

La respuesta devuelve lo siguiente como el cuerpo HTTP.

Payload

Cuando Kinesis Video Streams recibe correctamente PutMedia una solicitud, el servicio valida los encabezados de la solicitud. A continuación, el servicio comienza a leer la carga útil y envía primero una respuesta HTTP 200.

A continuación, el servicio devuelve una secuencia que contiene una serie de objetos JSON (Acknowledgementobjetos) separados por líneas nuevas. Los acuses de recibo se reciben en la misma conexión a través de la cual se envían los datos multimedia. Puede haber muchos acuses de recibo para una PutMedia solicitud. Cada uno Acknowledgement se compone de los siguientes pares clave-valor:

• AckEventType- Tipo de evento que representa el acuse de recibo.

  • Almacenamiento en búfer: Kinesis Video Streams ha empezado a recibir el fragmento. Kinesis Video Streams envía el primer acuse de recibo de almacenamiento en búfer cuando se recibe el primer byte de datos fragmentados.

  • Recibido: Kinesis Video Streams recibió el fragmento completo. Si no configuró la transmisión para conservar los datos, el productor puede dejar de almacenar el fragmento en búfer al recibir este acuse de recibo.

  • Persistido: Kinesis Video Streams ha conservado el fragmento (por ejemplo, en Amazon S3). Obtendrá este reconocimiento si configuró la transmisión para conservar los datos. Tras recibir este acuse de recibo, el productor puede dejar de almacenar el fragmento en búfer.

  • Error: Kinesis Video Streams detectó un error al procesar el fragmento. Puede revisar el código de error y determinar el siguiente curso de acción.

  • Inactiva: la PutMedia sesión está en curso. Sin embargo, Kinesis Video Streams no recibe datos en estos momentos. Kinesis Video Streams envía este acuse de recibo periódicamente durante un máximo de 30 segundos después de la última recepción de los datos. Si no se recibe ningún dato en los 30 segundos, Kinesis Video Streams cierra la solicitud.

    nota

    Este reconocimiento puede ayudar al productor a determinar si la PutMedia conexión está activa, incluso si no envía ningún dato.

• FragmentTimecode- Fragmenta el código de tiempo para el que se envía el acuse de recibo.

  Es posible que falte el elemento si AckEventType está inactivo.

• FragmentNumber- Número de fragmento generado por Kinesis Video Streams para el que se envía el acuse de recibo.

• ErrorIdy ErrorCode - Si AckEventType es asíError, este campo proporciona el código de error correspondiente. A continuación se muestra la lista de identificadores de error y sus correspondientes códigos de error y mensajes de error:

  • 4000 - STREAM_READ_ERROR: error al leer el flujo de datos.

  • 4001 - MAX_FRAGMENT_SIZE_REACHED: el tamaño del fragmento supera el límite máximo permitido (50 MB).

  • 4002 - MAX_FRAGMENT_DURATION_REACHED - La duración del fragmento supera el límite máximo permitido.

  • 4003 - MAX_CONNECTION_DURATION_REACHED: la duración de la conexión supera el umbral máximo permitido.

  • 4004 - FRAGMENT_TIMECODE_LESSER_THAN_PREVIOUS - El código de tiempo del fragmento es inferior al código de tiempo anterior (durante una llamada, no se pueden enviar fragmentos desordenados). PutMedia

  • 4005 - MORE_THAN_ALLOWED_TRACKS_FOUND - Se encuentra más de una pista en MKV. (obsoleto)

  • 4006 - INVALID_MKV_DATA - No se pudo analizar el flujo de entrada como un formato MKV válido.

  • 4007 - INVALID_PRODUCER_TIMESTAMP: marca de tiempo del productor no válida.

  • 4008 - STREAM_NOT_ACTIVE: la transmisión ya no existe (eliminada).

  • 4009 - FRAGMENT_METADATA_LIMIT_REACHED - Se ha alcanzado el límite de metadatos de fragmentos. Consulta la sección Límites de la guía para desarrolladores.

  • 4010 - TRACK_NUMBER_MISMATCH - El número de pista de un fotograma MKV no coincide con el de las pistas del encabezado MKV.

  • 4011 - FRAMES_MISSING_FOR_TRACK - El fragmento no contenía fotogramas para al menos una de las pistas del encabezado MKV.

  • 4012 - INVALID_FRAGMENT_METADATA - El nombre de los metadatos del fragmento no puede empezar por la cadena. AWS_

  • 4500 - KMS_KEY_ACCESS_DENIED: se deniega el acceso a la clave KMS especificada en la transmisión.

  • 4501 - KMS_KEY_DISABLED: la clave KMS especificada en la transmisión está deshabilitada.

  • 4502 - KMS_KEY_VALIDATION_ERROR: la clave KMS especificada en la transmisión no se pudo validar.

  • 4503 - KMS_KEY_UNAVAILABLE: la clave KMS especificada en la transmisión no está disponible.

  • 4504 - KMS_KEY_INVALID_USAGE: uso no válido de la clave KMS especificada en la transmisión.

  • 4505 - KMS_KEY_INVALID_STATE - La clave KMS especificada en la transmisión está en un estado no válido.

  • 4506 - KMS_KEY_NOT_FOUND - No se encuentra la clave KMS especificada en la transmisión.

  • 5000 - INTERNAL_ERROR: error de servicio interno.

  • 5001 - ARCHIVAL_ERROR - Kinesis Video Streams no pudo conservar los fragmentos en el almacén de datos.

nota

El productor, al enviar la carga útil para una PutMedia solicitud de larga duración, debería leer la respuesta para ver si hay acuse de recibo. Es posible que un productor reciba varios reconocimientos al mismo tiempo, debido al almacenamiento en búfer de un servidor proxy intermedio. Un productor que desee recibir los acuses de recibo a tiempo puede enviar menos fragmentos en cada solicitud. PutMedia

Errores

Para obtener información acerca de los errores comunes a todas las acciones, consulte Errores comunes.

ClientLimitExceededException

Kinesis Video Streams ha limitado la solicitud porque ha superado el límite de llamadas de clientes permitidas. Intente realizar la llamada más tarde.

Código de estado HTTP: 400

ConnectionLimitExceededException

Kinesis Video Streams ha limitado la solicitud porque ha superado el límite de conexiones de cliente permitidas.

Código de estado HTTP: 400

InvalidArgumentException

El valor de este parámetro de entrada no es válido.

Código de estado HTTP: 400

InvalidEndpointException

La persona que llamó utilizó un punto final incorrecto para escribir datos en una transmisión. Al recibir una excepción de este tipo, el usuario debe llamar GetDataEndpoint con el APIName valor establecido en PUT_MEDIA y utilizar el punto final de respuesta para invocar la siguiente PutMedia llamada.

Código de estado HTTP: 400

NotAuthorizedException

La persona que llama no está autorizada a realizar ninguna operación en la transmisión determinada o el token ha caducado.

Código de estado HTTP: 401

ResourceNotFoundException

Código de estado: 404. La transmisión con el nombre indicado no existe.

Código de estado HTTP: 404

Ejemplos

Formato de reconocimiento

El formato del acuse de recibo es el siguiente:

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

Véase también

Para obtener más información sobre el uso de esta API en uno de los AWS SDK específicos del idioma, consulta lo siguiente:

• Interfaz de la línea de comandos de AWS

• AWS SDK para .NET

• AWS SDK para C++

• AWS SDK para Go

• AWS SDK para Java V2

• AWS SDK para JavaScript V3

• AWS SDK para PHP V3

• AWS SDK para Python

• AWS SDK para Ruby V3