Syntaxe de la requête URIParamètres de demande Corps de la demande Syntaxe de la réponse Eléments de réponse Erreurs Exemples consultez aussi

PutMedia

Utilisez-le API pour envoyer des données multimédia vers un flux vidéo Kinesis.

Note

Vous devez d'abord appeler le GetDataEndpoint API pour obtenir un point de terminaison. Envoyez ensuite les PutMedia demandes à ce point de terminaison à l'aide du paramètre --endpoint-url.

Dans la demande, vous utilisez HTTP les en-têtes pour fournir des informations sur les paramètres, par exemple le nom du flux, l'horodatage et si la valeur de l'horodatage est absolue ou relative à la date à laquelle le producteur a commencé à enregistrer. Vous utilisez le corps de la demande pour envoyer les données multimédia. Kinesis Video Streams prend uniquement en charge le format de conteneur Matroska MKV () pour l'envoi de données multimédia à l'aide de ce format. API

Vous disposez des options suivantes pour envoyer des données de cette manière API :

Envoyez des données multimédia en temps réel : par exemple, une caméra de sécurité peut envoyer des images en temps réel au fur et à mesure qu'elle les génère. Cette approche minimise le temps de latence entre l'enregistrement vidéo et les données envoyées sur le fil. C'est ce qu'on appelle un producteur continu. Dans ce cas, une application grand public peut lire le flux en temps réel ou en cas de besoin.
Envoyer des données multimédia hors ligne (par lots) : par exemple, une caméra corporelle peut enregistrer des vidéos pendant des heures et les stocker sur l'appareil. Plus tard, lorsque vous connectez la caméra au port d'accueil, elle peut démarrer une PutMedia session pour envoyer des données vers un flux vidéo Kinesis. Dans ce scénario, la latence n'est pas un problème.

Lorsque vous l'utilisezAPI, tenez compte des considérations suivantes :

Vous devez spécifier streamName ou streamARN, mais pas les deux.
Pour pouvoir lire le contenu multimédia sur console ou viaHLS, la piste 1 de chaque fragment doit contenir une vidéo encodée en h.264, le code code dans les métadonnées du fragment doit être « V_MPEG/ISO/AVC» et les métadonnées du fragment doivent inclure des données privées du codec h.264 AVCC formatées. Facultativement, la piste 2 de chaque fragment doit contenir du son AAC codé, le code code dans les métadonnées du fragment doit être « A_ AAC » et les métadonnées du fragment doivent inclure les données privées du AAC codec.
Vous trouverez peut-être plus facile d'utiliser une seule PutMedia session de longue durée et d'envoyer un grand nombre de fragments de données multimédia dans la charge utile. Pour chaque fragment reçu, Kinesis Video Streams envoie un ou plusieurs accusés de réception. Des considérations liées au réseau peuvent vous empêcher de recevoir tous ces accusés de réception au fur et à mesure qu'ils sont générés.
Vous pouvez choisir plusieurs PutMedia sessions consécutives, chacune contenant moins de fragments, afin de vous assurer de recevoir tous les accusés de réception du service en temps réel.

Note

Si vous envoyez des données au même flux lors de plusieurs PutMedia sessions simultanées, les fragments multimédia sont entrelacés dans le flux. Vous devez vous assurer que cela est correct dans le scénario de votre application.

Les limites suivantes s'appliquent lors de l'utilisation du PutMedia API :

Un client peut appeler PutMedia jusqu'à cinq fois par seconde et par flux.
Un client peut envoyer jusqu'à cinq fragments par seconde et par flux.
Kinesis Video Streams lit les données multimédia à un débit pouvant atteindre 12,5 Mo/seconde, soit 100 Mbits/s au cours d'une session. PutMedia

Notez les contraintes suivantes. Dans ces cas, Kinesis Video Streams envoie l'accusé de réception de l'erreur dans la réponse.

Les fragments dont les codes temporels dépassent la limite maximale autorisée et qui contiennent plus de 50 Mo de données ne sont pas autorisés.
Les fragments contenant plus de trois pistes ne sont pas autorisés. Chaque image de chaque fragment doit avoir le même numéro de piste que l'une des pistes définies dans l'en-tête du fragment. En outre, chaque fragment doit contenir au moins une image pour chaque piste définie dans l'en-tête du fragment.
Chaque fragment doit contenir au moins une image pour chaque piste définie dans les métadonnées du fragment.
L'horodatage d'image le plus ancien d'un fragment doit être postérieur au dernier horodatage d'image du fragment précédent.
Un MKV flux contenant plusieurs MKV segments ou contenant des MKV éléments interdits (commetrack*) entraîne également un accusé de réception de l'erreur.

Kinesis Video Streams stocke chaque fragment entrant et les métadonnées associées dans ce que l'on appelle un « morceau ». Les métadonnées du fragment incluent les éléments suivants :

Les MKV en-têtes fournis au début de la demande PutMedia
Les métadonnées spécifiques à Kinesis Video Streams suivantes pour le fragment :
- server_timestamp- Horodatage auquel Kinesis Video Streams a commencé à recevoir le fragment.
- producer_timestamp- Horodatage, date à laquelle le producteur a commencé à enregistrer le fragment. Kinesis Video Streams utilise trois informations reçues dans la demande pour calculer cette valeur.
  - La valeur du code temporel du fragment reçue dans le corps de la demande en même temps que le fragment.
  - Deux en-têtes de requête : producerStartTimestamp (quand le producteur a commencé à enregistrer) et fragmentTimeCodeType (si le code temporel du fragment dans la charge utile est absolu ou relatif).
  Kinesis Video Streams calcule ensuite producer_timestamp le pour le fragment comme suit :
  
  Si fragmentTimeCodeType c'est relatif, alors
  
  producer_timestamp= producerStartTimeStamp + code temporel du fragment
  
  Si fragmentTimeCodeType c'est absolu, alors
  
  producer_timestamp= code temporel du fragment (converti en millisecondes)
- Numéro de fragment unique attribué par Kinesis Video Streams.

Note

Lorsque vous faites la GetMedia demande, Kinesis Video Streams renvoie un flux de ces segments. Le client peut traiter les métadonnées selon ses besoins.

Note

Cette opération n'est disponible que AWS SDK pour Java. Il n'est pas pris en charge dans AWS SDKs les autres langues.

Note

Kinesis Video Streams n'analyse ni ne valide les données privées du codec lors de l'ingestion et de l'archivage via le. PutMedia API KVSextrait et valide les informations nécessaires à partir des données privées du codec pour MPEG -TS et le packaging des MP4 fragments lors de la consommation du flux via le. HLS APIs

Note

Si une erreur est générée après avoir invoqué un API média Kinesis Video Streams, outre le code d'état et HTTP le corps de la réponse, elle inclut les informations suivantes :

x-amz-ErrorTypeHTTPen-tête : contient un type d'erreur plus spécifique en plus de ce que fournit le code d'HTTPétat.
x-amz-RequestIdHTTPen-tête : si vous souhaitez signaler un problème à AWS, l'équipe d'assistance peut mieux diagnostiquer le problème si elle reçoit l'identifiant de demande.

Le code d'HTTPétat et l' ErrorType en-tête peuvent être utilisés pour prendre des décisions programmatiques quant à savoir si les erreurs peuvent être réessayées et dans quelles conditions, ainsi que pour fournir des informations sur les actions que le programmeur client devra peut-être entreprendre pour réessayer avec succès.

Pour plus d'informations, consultez la section Erreurs au bas de cette rubrique, ainsi que les erreurs courantes.

Syntaxe de la requête


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

URIParamètres de demande

La demande utilise les URI paramètres suivants.

FragmentTimecodeType

Vous transmettez cette valeur comme x-amzn-fragment-timecode-type HTTP en-tête.

Indique si les codes temporels des fragments (charge utile, corps de HTTP requête) sont absolus ou relatifs à. producerStartTimestamp Kinesis Video Streams utilise ces informations pour calculer producer_timestamp le fragment reçu dans la demande, comme décrit dans API la présentation.

Valeurs valides : ABSOLUTE | RELATIVE

Obligatoire : oui

ProducerStartTimestamp

Vous transmettez cette valeur comme x-amzn-producer-start-timestamp HTTP en-tête.

Il s'agit de l'horodatage du producteur auquel le producteur a commencé à enregistrer le média (et non de l'horodatage des fragments spécifiques de la demande).

StreamARN

Vous transmettez cette valeur comme x-amzn-stream-arn HTTP en-tête.

Amazon Resource Name (ARN) du flux vidéo Kinesis dans lequel vous souhaitez écrire le contenu multimédia. Si vous ne spécifiez pas lestreamARN, vous devez spécifier lestreamName.

Contraintes de longueur : Longueur minimum de 1. Longueur maximum de 1024.

Modèle : arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

StreamName

Vous transmettez cette valeur comme x-amzn-stream-name HTTP en-tête.

Nom du flux vidéo Kinesis dans lequel vous souhaitez écrire le contenu multimédia. Si vous ne spécifiez pas lestreamName, vous devez spécifier lestreamARN.

Contraintes de longueur : longueur minimum de 1. Longueur maximum de 256.

Modèle : [a-zA-Z0-9_.-]+

Corps de la demande

La demande accepte les données binaires suivantes.

Payload: Le contenu multimédia à écrire dans le flux vidéo Kinesis. Dans l'implémentation actuelle, Kinesis Video Streams ne prend en charge que le format de conteneur Matroska MKV () avec un seul segment. MKV Un segment peut contenir un ou plusieurs clusters.

Note
Chaque MKV cluster est mappé sur un fragment de flux vidéo Kinesis. Quelle que soit la durée du cluster que vous choisissez, elle devient la durée du fragment.

Syntaxe de la réponse


HTTP/1.1 200

Payload

Eléments de réponse

Si l'action aboutit, le service renvoie une réponse HTTP 200.

La réponse renvoie le HTTP corps suivant.

Payload

Une fois que Kinesis Video Streams a reçu PutMedia une demande avec succès, le service valide les en-têtes de la demande. Le service commence ensuite à lire la charge utile et envoie d'abord une réponse HTTP 200.

Le service renvoie ensuite un flux contenant une série d'JSONobjets (Acknowledgementobjets) séparés par de nouvelles lignes. Les accusés de réception sont reçus sur la même connexion que celle par laquelle les données multimédia sont envoyées. Il peut y avoir de nombreux accusés de réception pour une PutMedia demande. Chacune Acknowledgement comprend les paires clé-valeur suivantes :

AckEventType- Type d'événement représenté par l'accusé de réception.
- Mise en mémoire tampon : Kinesis Video Streams a commencé à recevoir le fragment. Kinesis Video Streams envoie le premier accusé de réception de la mise en mémoire tampon lorsque le premier octet de données de fragment est reçu.
- Reçu : Kinesis Video Streams a reçu l'intégralité du fragment. Si vous n'avez pas configuré le flux pour conserver les données, le producteur peut arrêter de mettre le fragment en mémoire tampon dès réception de cet accusé de réception.
- Persistant : Kinesis Video Streams a conservé le fragment (par exemple, vers Amazon S3). Vous obtenez cet accusé de réception si vous avez configuré le flux pour qu'il conserve les données. Une fois que vous avez reçu cet accusé de réception, le producteur peut arrêter de mettre le fragment en mémoire tampon.
- Erreur : Kinesis Video Streams a rencontré une erreur lors du traitement du fragment. Vous pouvez consulter le code d'erreur et déterminer la marche à suivre.
- Inactif : la PutMedia session est en cours. Cependant, Kinesis Video Streams ne reçoit actuellement aucune donnée. Kinesis Video Streams envoie cet accusé de réception régulièrement pendant 30 secondes maximum après la dernière réception des données. Si aucune donnée n'est reçue dans les 30 secondes, Kinesis Video Streams ferme la demande.
  
  Note
  Cet accusé de réception peut aider le producteur à déterminer si la PutMedia connexion est active, même s'il n'envoie aucune donnée.
FragmentTimecode- Fragment le code temporel pour lequel un accusé de réception est envoyé.

L'élément peut être absent s'il AckEventType est inactif.
FragmentNumber- Numéro du fragment généré par Kinesis Video Streams pour lequel l'accusé de réception est envoyé.
ErrorIdet ErrorCode - Si tel AckEventType est le casError, ce champ fournit le code d'erreur correspondant. Voici la liste des erreurs IDs ainsi que les codes d'erreur et messages d'erreur correspondants :
- 4000 - STREAM _ READ _ ERROR - Erreur lors de la lecture du flux de données.
- 4001 - MAX _ _ FRAGMENT SIZE _ REACHED - La taille du fragment est supérieure à la limite maximale autorisée (50 Mo).
- 4002 - MAX _ _ FRAGMENT DURATION _ REACHED - La durée du fragment est supérieure à la limite maximale autorisée.
- 4003 - MAX _ _ CONNECTION DURATION _ REACHED - La durée de connexion est supérieure au seuil maximum autorisé.
- 4004 - FRAGMENT _ _ TIMECODE _ LESSER THAN _ PREVIOUS - Le code temporel du fragment est inférieur au code temporel précédent (au cours d'un PutMedia appel, vous ne pouvez pas envoyer de fragments dans le désordre).
- 4005 - MORE _ THAN _ ALLOWED _ TRACKS _ FOUND - Plusieurs pistes se trouvent dansMKV. (obsolète)
- 4006 - INVALID _ MKV _ DATA - Impossible d'analyser le flux d'entrée en tant que format valideMKV.
- 4007 - INVALID _ PRODUCER _ TIMESTAMP - Horodatage du producteur non valide.
- 4008 - STREAM _ NOT _ ACTIVE - Le flux n'existe plus (supprimé).
- 4009 - FRAGMENT _ _ METADATA LIMIT _ REACHED - La limite de métadonnées des fragments est atteinte. Consultez la section Limites du guide du développeur.
- 4010 - TRACK _ NUMBER _ MISMATCH - Le numéro de piste d'un MKV cadre ne correspond pas à celui des pistes de l'MKVen-tête.
- 4011 - FRAMES _ MISSING _ FOR _ TRACK - Le fragment ne contenait aucune image pour au moins une des pistes de l'MKVen-tête.
- 4012 - INVALID _ FRAGMENT _ METADATA - Le nom des métadonnées du fragment ne peut pas commencer par la chaîne AWS_.
- 4500 - KMS _ KEY _ ACCESS _ DENIED - L'accès à la KMS clé spécifiée pour le flux est refusé.
- 4501 - KMS _ KEY _ DISABLED - La KMS clé spécifiée pour le flux est désactivée.
- 4502 - KMS _ _ KEY VALIDATION _ ERROR - La validation de la KMS clé spécifiée pour le flux a échoué.
- 4503 - KMS _ KEY _ UNAVAILABLE - La KMS clé spécifiée pour le flux n'est pas disponible.
- 4504 - KMS _ _ KEY INVALID _ USAGE - Utilisation non valide de la KMS clé spécifiée pour le flux.
- 4505 - KMS _ KEY _ INVALID _ STATE - La KMS clé spécifiée pour le flux n'est pas valide.
- 4506 - KMS _ KEY _ NOT _ FOUND - La KMS clé spécifiée pour le flux est introuvable.
- 5000 - INTERNAL _ ERROR - Erreur de service interne.
- 5001 - ARCHIVAL _ ERROR - Kinesis Video Streams n'a pas réussi à conserver les fragments dans le magasin de données.

Note

Le producteur, lorsqu'il envoie la charge utile pour une PutMedia demande de longue durée, doit lire la réponse pour obtenir des accusés de réception. Un producteur peut recevoir de nombreux accusés de réception en même temps, en raison de la mise en mémoire tampon sur un serveur proxy intermédiaire. Un producteur qui souhaite recevoir des accusés de réception en temps opportun peut envoyer moins de fragments à chaque PutMedia demande.

Erreurs

Pour plus d'informations sur les erreurs courantes pour toutes les actions, consultez Erreurs courantes.

ClientLimitExceededException

Kinesis Video Streams a limité le nombre de demandes car vous avez dépassé le nombre maximal d'appels clients autorisés. Essayez de passer l'appel plus tard.

HTTPCode de statut : 400

ConnectionLimitExceededException

Kinesis Video Streams a limité la demande car vous avez dépassé le nombre limite de connexions client autorisées.

HTTPCode de statut : 400

InvalidArgumentException

La valeur de ce paramètre d'entrée n'est pas valide.

HTTPCode de statut : 400

InvalidEndpointException

L'appelant a utilisé le mauvais point de terminaison pour écrire des données dans un flux. À la réception d'une telle exception, l'utilisateur doit appeler GetDataEndpoint avec APIName set to PUT_MEDIA et utiliser le point de terminaison de la réponse pour appeler le prochain PutMedia appel.

HTTPCode de statut : 400

NotAuthorizedException

L'appelant n'est pas autorisé à effectuer une opération sur le flux donné, ou le jeton a expiré.

HTTPCode de statut : 401

ResourceNotFoundException

Code d'état : 404, le flux portant le nom donné n'existe pas.

HTTPCode de statut : 404

Exemples

Format d'accusé de réception

Le format de l'accusé de réception est le suivant :


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

consultez aussi

Pour plus d'informations sur son utilisation API dans l'une des langues spécifiques AWS SDKs, consultez ce qui suit :

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

GetMedia

Amazon Kinesis Video Streams