PutMedia - Flusso di video Amazon Kinesis
Sintassi della richiestaURIParametri della richiestaCorpo della richiestaSintassi della rispostaElementi di rispostaErroriEsempiVedi anche

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

PutMedia

Utilizzatelo API per inviare dati multimediali a un flusso video Kinesis.

Nota

Devi prima chiamare il GetDataEndpoint API per ottenere un endpoint. Quindi invia le PutMedia richieste a questo endpoint utilizzando il parametro --endpoint-url.

Nella richiesta, usi le HTTP intestazioni per fornire informazioni sui parametri, ad esempio il nome dello stream, il timestamp e se il valore del timestamp è assoluto o relativo a quando il produttore ha iniziato la registrazione. Utilizzate il corpo della richiesta per inviare i dati multimediali. Kinesis Video Streams supporta solo il formato contenitore MKV Matroska () per l'invio di dati multimediali utilizzando questo formato. API

Sono disponibili le seguenti opzioni per inviare dati utilizzando questo: API

  • Invia dati multimediali in tempo reale: ad esempio, una telecamera di sicurezza può inviare fotogrammi in tempo reale man mano che li genera. Questo approccio riduce al minimo la latenza tra la registrazione video e i dati inviati via cavo. Questo viene definito produttore continuo. In questo caso, un'applicazione consumer può leggere lo stream in tempo reale o quando necessario.

  • Invia dati multimediali offline (in batch): ad esempio, una body camera potrebbe registrare video per ore e archiviarli sul dispositivo. Successivamente, quando colleghi la videocamera alla porta docking, la videocamera può avviare una PutMedia sessione per inviare dati a un flusso video Kinesis. In questo scenario, la latenza non è un problema.

Quando si utilizza questa opzioneAPI, tenete presente le seguenti considerazioni:

  • È necessario specificare streamName o streamARN, ma non entrambi.

  • Per poter riprodurre i file multimediali sulla console o tramiteHLS, la traccia 1 di ogni frammento deve contenere video con codifica h.264, il CodeCid nei metadati del frammento deve essere «V_ MPEGISO/AVC«e i metadati del frammento devono includere dati privati formattati con codec h.264. AVCC Facoltativamente, la traccia 2 di ogni frammento dovrebbe contenere audio AAC codificato, il CodeCid nei metadati del frammento dovrebbe essere «A_ AAC «e i metadati del frammento dovrebbero includere dati privati del AAC codec.

  • Potrebbe essere più semplice utilizzare una singola PutMedia sessione di lunga durata e inviare un gran numero di frammenti di dati multimediali nel payload. Per ogni frammento ricevuto, Kinesis Video Streams invia uno o più riconoscimenti. Potenziali considerazioni sulla rete potrebbero impedirti di ricevere tutti questi riconoscimenti man mano che vengono generati.

  • Potresti scegliere più PutMedia sessioni consecutive, ognuna con meno frammenti, per assicurarti di ricevere tutti i riconoscimenti dal servizio in tempo reale.

Nota

Se invii dati allo stesso stream in più PutMedia sessioni simultanee, i frammenti multimediali vengono interlacciati nello stream. È necessario assicurarsi che ciò sia corretto nel proprio scenario applicativo.

I seguenti limiti si applicano quando si utilizza PutMediaAPI:

  • Un client può effettuare chiamate PutMedia fino a cinque volte al secondo per stream.

  • Un client può inviare fino a cinque frammenti al secondo per stream.

  • Kinesis Video Streams legge i dati multimediali a una velocità massima di 12,5 MB/secondo o 100 Mbps durante una sessione. PutMedia

Nota i seguenti vincoli. In questi casi, Kinesis Video Streams invia la conferma dell'errore nella risposta.

  • I frammenti con codici temporali superiori al limite massimo consentito e che contengono più di 50 MB di dati non sono consentiti.

  • I frammenti contenenti più di tre tracce non sono consentiti. Ogni fotogramma di ogni frammento deve avere lo stesso numero di traccia di una delle tracce definite nell'intestazione del frammento. Inoltre, ogni frammento deve contenere almeno un fotogramma per ogni traccia definita nell'intestazione del frammento.

  • Ogni frammento deve contenere almeno un fotogramma per ogni traccia definita nei metadati del frammento.

  • Il timestamp del primo fotogramma in un frammento deve essere successivo all'ultimo timestamp del frammento precedente.

  • Un MKV flusso contenente più di un MKV segmento o contenente MKV elementi non consentiti (cometrack*) genera anche la conferma dell'errore.

Kinesis Video Streams archivia ogni frammento in entrata e i relativi metadati in un cosiddetto «blocco». I metadati del frammento includono quanto segue:

  • Le MKV intestazioni fornite all'inizio della richiesta PutMedia

  • I seguenti metadati specifici di Kinesis Video Streams per il frammento:

    • server_timestamp- Data e ora in cui Kinesis Video Streams ha iniziato a ricevere il frammento.

    • producer_timestamp- Timestamp, quando il produttore ha iniziato a registrare il frammento. Kinesis Video Streams utilizza tre informazioni ricevute nella richiesta per calcolare questo valore.

      • Il valore del codice di tempo del frammento ricevuto nel corpo della richiesta insieme al frammento.

      • Due intestazioni di richiesta: producerStartTimestamp (quando il produttore ha iniziato la registrazione) e fragmentTimeCodeType (se il codice di tempo del frammento nel payload è assoluto o relativo).

      Kinesis Video Streams producer_timestamp calcola quindi il frammento nel modo seguente:

      Se è relativofragmentTimeCodeType, allora

      producer_timestamp= producerStartTimeStamp + codice temporale del frammento

      Se fragmentTimeCodeType è assoluto, allora

      producer_timestamp= codice di tempo del frammento (convertito in millisecondi)

    • Numero di frammento univoco assegnato da Kinesis Video Streams.

Nota

Quando si effettua la GetMedia richiesta, Kinesis Video Streams restituisce un flusso di questi blocchi. Il client può elaborare i metadati secondo necessità.

Nota

Questa operazione è disponibile solo AWS SDK per Java. Non è supportata AWS SDKs in altre lingue.

Nota

Kinesis Video Streams non analizza e convalida i dati privati del codec durante l'ingestione e l'archiviazione tramite. PutMedia API KVSestrae e convalida le informazioni necessarie dai dati privati del codec per MPEG -TS e framment packaging quando si consuma lo stream tramite. MP4 HLS APIs

Nota

Se viene generato un errore dopo aver richiamato un API supporto Kinesis Video Streams, oltre al codice di stato e HTTP al corpo della risposta, include le seguenti informazioni:

  • x-amz-ErrorTypeHTTPheader: contiene un tipo di errore più specifico oltre a quello fornito dal codice di stato. HTTP

  • x-amz-RequestIdHTTPheader: se desideri segnalare un problema AWS, il team di supporto può diagnosticare meglio il problema se gli viene fornito il Request Id.

Sia il codice di HTTP stato che l' ErrorType intestazione possono essere utilizzati per prendere decisioni programmatiche sulla possibilità di riprovare gli errori e in quali condizioni, oltre a fornire informazioni sulle azioni che il programmatore del client potrebbe dover intraprendere per riprovare con successo.

Per ulteriori informazioni, consultate la sezione Errori nella parte inferiore di questo argomento, nonché Errori comuni.

Sintassi della richiesta

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

URIParametri della richiesta

La richiesta utilizza i seguenti URI parametri.

FragmentTimecodeType

Si passa questo valore come x-amzn-fragment-timecode-type HTTP intestazione.

Indica se i codici temporali nei frammenti (payload, corpo della HTTP richiesta) sono assoluti o relativi a. producerStartTimestamp Kinesis Video Streams utilizza queste informazioni per producer_timestamp calcolare il frammento ricevuto nella richiesta, come descritto nella panoramica. API

Valori validi: ABSOLUTE | RELATIVE

Campo obbligatorio: sì

ProducerStartTimestamp

Si passa questo valore come intestazione. x-amzn-producer-start-timestamp HTTP

Questo è il timestamp del produttore in cui il produttore ha iniziato a registrare il file multimediale (non il timestamp dei frammenti specifici nella richiesta).

StreamARN

Si passa questo valore come intestazione. x-amzn-stream-arn HTTP

Amazon Resource Name (ARN) dello stream video Kinesis in cui desideri scrivere i contenuti multimediali. Se non specifichi ilstreamARN, devi specificare ilstreamName.

Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 1024 caratteri.

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

StreamName

Si passa questo valore come x-amzn-stream-name HTTP intestazione.

Nome dello stream video Kinesis in cui desideri scrivere i contenuti multimediali. Se non si specifica ilstreamName, è necessario specificare ilstreamARN.

Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 256 caratteri.

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

Corpo della richiesta

La richiesta accetta i seguenti dati binari.

Payload

I contenuti multimediali da scrivere nello stream video di Kinesis. Nell'implementazione attuale, Kinesis Video Streams supporta solo il formato contenitore MKV Matroska () con un singolo segmento. MKV Un segmento può contenere uno o più cluster.

Nota

Ogni MKV cluster viene mappato su un frammento di flusso video Kinesis. Qualunque sia la durata del cluster scelta, diventa la durata del frammento.

Sintassi della risposta

HTTP/1.1 200

Payload

Elementi di risposta

Se l'azione ha esito positivo, il servizio restituisce una risposta di HTTP 200.

La risposta restituisce quanto segue come HTTP corpo.

Payload

Dopo che Kinesis Video Streams PutMedia riceve correttamente una richiesta, il servizio convalida le intestazioni della richiesta. Il servizio inizia quindi a leggere il payload e invia prima una risposta di 200. HTTP

Il servizio restituisce quindi uno stream contenente una serie di JSON oggetti (Acknowledgementoggetti) separati da nuove righe. I riconoscimenti vengono ricevuti sulla stessa connessione su cui vengono inviati i dati multimediali. Possono esserci molti riconoscimenti per una richiesta. PutMedia Ciascuno Acknowledgement è composto dalle seguenti coppie chiave-valore:

  • AckEventType- Tipo di evento rappresentato dal riconoscimento.

    • Buffering: Kinesis Video Streams ha iniziato a ricevere il frammento. Kinesis Video Streams invia la prima conferma di buffering quando viene ricevuto il primo byte di dati frammentari.

    • Ricevuto: Kinesis Video Streams ha ricevuto l'intero frammento. Se non hai configurato lo stream per rendere persistenti i dati, il produttore può interrompere il buffering del frammento dopo aver ricevuto questa conferma.

    • Persistente: Kinesis Video Streams ha reso persistente il frammento (ad esempio, su Amazon S3). Ottieni questo riconoscimento se hai configurato lo stream per rendere persistenti i dati. Dopo aver ricevuto questo riconoscimento, il produttore può interrompere il buffering del frammento.

    • Errore: Kinesis Video Streams ha riscontrato un errore durante l'elaborazione del frammento. Puoi rivedere il codice di errore e determinare la prossima linea d'azione.

    • Inattiva: la PutMedia sessione è in corso. Tuttavia, Kinesis Video Streams al momento non riceve dati. Kinesis Video Streams invia questa conferma periodicamente per un massimo di 30 secondi dopo l'ultima ricezione dei dati. Se non viene ricevuto alcun dato entro 30 secondi, Kinesis Video Streams chiude la richiesta.

      Nota

      Questo riconoscimento può aiutare un produttore a determinare se la PutMedia connessione è attiva, anche se non invia alcun dato.

  • FragmentTimecode- Codice temporale del frammento per il quale viene inviata la conferma.

    L'elemento può mancare se è inattivo. AckEventType

  • FragmentNumber- Numero del frammento generato da Kinesis Video Streams per il quale viene inviata la conferma.

  • ErrorIde ErrorCode - Se AckEventType èError, questo campo fornisce il codice di errore corrispondente. Di seguito è riportato l'elenco degli errori IDs con i codici di errore e i messaggi di errore corrispondenti:

    • 4000 - STREAM _ READ _ ERROR - Errore durante la lettura del flusso di dati.

    • 4001 - MAX _ _ FRAGMENT SIZE _ REACHED - La dimensione del frammento è superiore al limite massimo consentito, 50 MB.

    • 4002 - MAX _ _ FRAGMENT DURATION _ REACHED - La durata del frammento è superiore al limite massimo consentito.

    • 4003 - MAX _ _ CONNECTION DURATION _ REACHED - La durata della connessione è superiore alla soglia massima consentita.

    • 4004 - FRAGMENT _ _ TIMECODE _ LESSER THAN _ PREVIOUS - Il codice di tempo del frammento è inferiore al codice temporale precedente (durante una PutMedia chiamata, non è possibile inviare frammenti non ordinati).

    • 4005 - MORE _ _ _ THAN ALLOWED TRACKS _ FOUND - È stato trovato più di un brano in. MKV (obsoleto)

    • 4006 - INVALID _ MKV _ DATA - Impossibile analizzare il flusso di input come formato valido. MKV

    • 4007 - INVALID _ PRODUCER _ TIMESTAMP - Timestamp del produttore non valido.

    • 4008 - STREAM _ NOT _ ACTIVE - Lo stream non esiste più (eliminato).

    • 4009 - FRAGMENT _ _ METADATA LIMIT _ REACHED - È stato raggiunto il limite dei metadati dei frammenti. Consulta la sezione Limiti della guida per sviluppatori.

    • 4010 - TRACK _ NUMBER _ MISMATCH - Il numero del brano in un MKV frame non corrisponde ai brani nell'MKVintestazione.

    • 4011 - FRAMES _ MISSING _ FOR _ TRACK - Il frammento non conteneva alcun frame per almeno una delle tracce nell'intestazione. MKV

    • 4012 - INVALID _ FRAGMENT _ METADATA - Il nome dei metadati del frammento non può iniziare con la stringa. AWS_

    • 4500 - KMS _ _ KEY ACCESS _ DENIED - L'accesso alla chiave specificata KMS dello stream è negato.

    • 4501 - KMS _ KEY _ DISABLED - La KMS chiave specificata dello stream è disabilitata.

    • 4502 - KMS _ _ KEY VALIDATION _ ERROR - La convalida della KMS chiave specificata dello stream non è riuscita.

    • 4503 - KMS _ KEY _ UNAVAILABLE - La KMS chiave specificata dallo stream non è disponibile.

    • 4504 - KMS _ _ KEY INVALID _ USAGE - Utilizzo non valido della chiave specificata dallo stream. KMS

    • 4505 - KMS _ _ KEY INVALID _ STATE - La KMS chiave specificata dallo stream è in uno stato non valido.

    • 4506 - KMS _ _ KEY NOT _ FOUND - La KMS chiave specificata dello stream non è stata trovata.

    • 5000 - INTERNAL _ ERROR - Errore interno del servizio.

    • 5001 - ARCHIVAL _ ERROR - Kinesis Video Streams non è riuscito a mantenere i frammenti nell'archivio dati.

Nota

Il produttore, mentre invia il payload per una PutMedia richiesta di lunga durata, dovrebbe leggere la risposta per i riconoscimenti. Un produttore potrebbe ricevere blocchi di riconoscimenti contemporaneamente, a causa del buffering su un server proxy intermedio. Un produttore che desidera ricevere riconoscimenti tempestivi può inviare meno frammenti per ogni richiesta. PutMedia

Errori

Per informazioni sugli errori comuni a tutte le operazioni, consultare Errori comuni.

ClientLimitExceededException

Kinesis Video Streams ha limitato la richiesta perché è stato superato il limite di chiamate client consentite. Prova a effettuare la chiamata più tardi.

HTTPCodice di stato: 400

ConnectionLimitExceededException

Kinesis Video Streams ha limitato la richiesta perché è stato superato il limite di connessioni client consentite.

HTTPCodice di stato: 400

InvalidArgumentException

Il valore di questo parametro di input non è valido.

HTTPCodice di stato: 400

InvalidEndpointException

Il chiamante ha utilizzato un endpoint errato per scrivere dati in uno stream. Quando riceve tale eccezione, l'utente deve chiamare GetDataEndpoint con APIName set to PUT_MEDIA e utilizzare l'endpoint from response per richiamare la chiamata successiva. PutMedia

HTTPCodice di stato: 400

NotAuthorizedException

Il chiamante non è autorizzato a eseguire un'operazione sullo stream specificato o il token è scaduto.

HTTPCodice di stato: 401

ResourceNotFoundException

Codice di stato: 404, Lo stream con il nome specificato non esiste.

HTTPCodice di stato: 404

Esempi

Formato di riconoscimento

Il formato del riconoscimento è il seguente:

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

Vedi anche

Per ulteriori informazioni sull'utilizzo API in una delle lingue specifiche, consulta quanto segue AWS SDKs: