PutMedia - Amazon Kinesis Video Streams
Sintaxis de la solicitudURIParámetros de solicitudCuerpo de la solicitudSintaxis de la respuestaElementos de respuestaErroresEjemplosVéase también

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

PutMedia

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

nota

Primero debe llamar al 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 HTTP los encabezados 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. El cuerpo de la solicitud se utiliza para enviar los datos multimedia. Kinesis Video Streams solo admite el formato contenedor Matroska MKV () para enviar datos multimedia mediante este formato. API

Dispone de las siguientes opciones para enviar datos mediante este método: 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.

Al usarloAPI, tenga en cuenta las siguientes consideraciones:

  • Debe especificar streamName o streamARN, pero no ambos.

  • Para poder reproducir el contenido multimedia en la consola o a través de ellaHLS, la pista 1 de cada fragmento debe contener vídeo codificado en H.264, el codecID de los metadatos del fragmento debe ser «V_ MPEGISO/AVC» y los metadatos del fragmento deben incluir datos privados del códec h.264 AVCC formateados. Opcionalmente, la pista 2 de cada fragmento debe contener audio AAC codificado, el codeCid de los metadatos del fragmento debe ser «A_AAC» y los metadatos del fragmento deben incluir datos privados del AAC códec.

  • 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 a 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.

Se aplican los siguientes límites cuando se utiliza PutMediaAPI:

  • 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 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 la confirmación 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 marca de tiempo del fragmento anterior.

  • Una MKV secuencia que contenga más de un MKV segmento o que contenga MKV elementos no permitidos (por ejemplotrack*) también generará la confirmación del 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:

  • MKVLos encabezados 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 AWS SDK para Java. No se admite en AWS SDKs otros idiomas.

nota

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

nota

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

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

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

Tanto el código de HTTP estado 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

URIParámetros de solicitud

La solicitud utiliza los siguientes URI parámetros.

FragmentTimecodeType

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

Indica si los códigos de tiempo de los fragmentos (carga útil, cuerpo de la HTTP solicitud) 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 API la descripción general.

Valores válidos: ABSOLUTE | RELATIVE

Obligatorio: sí

ProducerStartTimestamp

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

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 pasa como encabezado. x-amzn-stream-arn HTTP

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 elstreamName.

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 pasa como x-amzn-stream-name HTTP encabezado.

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 solo segmento. MKV Un segmento puede contener uno o más clústeres.

nota

Cada MKV clúster 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 de HTTP 200.

La respuesta devuelve lo siguiente como HTTP cuerpo.

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, en primer lugar, envía una respuesta de 200. HTTP

A continuación, el servicio devuelve una secuencia que contiene una serie de JSON objetos (Acknowledgementobjetos) separados por nuevas líneas. 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 consta 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 actualmente. 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 errores IDs y sus códigos de error y mensajes de error correspondientes:

    • 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 de 50 MB.

    • 4002 - MAX _ _ FRAGMENT DURATION _ REACHED - La duración del fragmento es superior al límite máximo permitido.

    • 4003 - MAX _ _ CONNECTION DURATION _ REACHED - La duración de la conexión es superior al 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 PutMedia llamada, no se pueden enviar fragmentos desordenados).

    • 4005 - MORE _ _ THAN _ ALLOWED TRACKS _ FOUND - Se encuentra más de una pista. MKV (obsoleto)

    • 4006 - INVALID _ MKV _ DATA - No se pudo analizar el flujo de entrada como un formato válidoMKV.

    • 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 pistas de un MKV fotograma no coincidía con las pistas del MKV encabezado.

    • 4011 - FRAMES _ MISSING _ FOR _ TRACK - El fragmento no contenía fotogramas para al menos una de las pistas del MKV encabezado.

    • 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 KMS clave especificada de la transmisión.

    • 4501 - KMS _ KEY _ DISABLED - La KMS clave especificada en la transmisión está deshabilitada.

    • 4502 - KMS _ _ KEY VALIDATION _ ERROR - No se pudo validar la KMS clave especificada de la transmisión.

    • 4503 - KMS _ KEY _ UNAVAILABLE - La KMS clave especificada de la transmisión no está disponible.

    • 4504 - KMS _ _ KEY INVALID _ USAGE - Uso no válido de la clave especificada KMS de la transmisión.

    • 4505 - KMS _ KEY _ INVALID _ STATE - La KMS clave especificada en la transmisión no es válida.

    • 4506 - KMS _ _ KEY NOT _ FOUND - No se encuentra la KMS clave especificada de 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.

HTTPCódigo de estado: 400

ConnectionLimitExceededException

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

HTTPCódigo de estado: 400

InvalidArgumentException

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

HTTPCódigo de estado: 400

InvalidEndpointException

La persona que llamó usó 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.

HTTPCódigo de estado: 400

NotAuthorizedException

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

HTTPCódigo de estado: 401

ResourceNotFoundException

Código de estado: 404, la transmisión con el nombre de pila no existe.

HTTPCódigo de estado: 404

Ejemplos

Formato de reconocimiento

El formato del reconocimiento es el siguiente:

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

Véase también

Para obtener más información sobre cómo usarlo API en uno de los idiomas específicos AWS SDKs, consulte lo siguiente: