PutMedia

Verwenden Sie diese API, um Mediendaten an einen Kinesis-Videostream zu senden.

Anmerkung

Sie müssen zuerst die GetDataEndpoint API aufrufen, um einen Endpunkt zu erhalten. Senden Sie dann die PutMedia Anfragen mit dem Parameter --endpoint-url an diesen Endpunkt.

In der Anfrage verwenden Sie die HTTP-Header, um Parameterinformationen bereitzustellen, z. B. Streamname, Zeitstempel und ob der Zeitstempelwert absolut oder relativ zu dem Zeitpunkt ist, zu dem der Producer mit der Aufnahme begonnen hat. Sie verwenden den Anfragetext, um die Mediendaten zu senden. Kinesis Video Streams unterstützt nur das Matroska-Containerformat (MKV) für das Senden von Mediendaten über diese API.

Sie haben die folgenden Optionen für das Senden von Daten mit dieser API:

• Mediendaten in Echtzeit senden: Eine Sicherheitskamera kann beispielsweise Bilder in Echtzeit senden, während sie sie generiert. Dieser Ansatz minimiert die Latenz zwischen der Videoaufnahme und den über das Kabel gesendeten Daten. Dies wird als kontinuierlicher Produzent bezeichnet. In diesem Fall kann eine Verbraucheranwendung den Stream in Echtzeit oder bei Bedarf lesen.

• Mediendaten offline (stapelweise) senden: Eine Körperkamera kann beispielsweise stundenlang Videos aufnehmen und auf dem Gerät speichern. Später, wenn Sie die Kamera an den Docking-Anschluss anschließen, kann die Kamera eine PutMedia Sitzung starten, um Daten an einen Kinesis-Videostream zu senden. In diesem Szenario ist Latenz kein Problem.

Beachten Sie bei der Verwendung dieser API die folgenden Überlegungen:

• Sie müssen entweder streamName oder streamARN angeben, aber nicht beides.

• Um die Medien auf der Konsole oder über HLS abspielen zu können, sollte Track 1 jedes Fragments H.264-codiertes Video enthalten, die CodeCid in den Fragment-Metadaten sollte „V_MPEG/ISO/AVC“ lauten und die Fragment-Metadaten sollten private H.264-Codec-Daten im AVCC-Format enthalten. Optional sollte Track 2 jedes Fragments AAC-codiertes Audio enthalten, die CodeCid in den Fragment-Metadaten sollte „A_AAC“ lauten und die Fragment-Metadaten sollten private AAC-Codec-Daten enthalten.

• Möglicherweise finden Sie es einfacher, eine einzelne PutMedia Sitzung mit langer Laufzeit zu verwenden und eine große Anzahl von Mediendatenfragmenten in der Payload zu senden. Für jedes empfangene Fragment sendet Kinesis Video Streams eine oder mehrere Bestätigungen. Mögliche Netzwerkprobleme können dazu führen, dass Sie nicht alle diese Bestätigungen erhalten, sobald sie generiert werden.

• Sie können mehrere aufeinanderfolgende PutMedia Sitzungen mit jeweils weniger Fragmenten wählen, um sicherzustellen, dass Sie alle Bestätigungen vom Dienst in Echtzeit erhalten.

Anmerkung

Wenn Sie in mehreren gleichzeitigen PutMedia Sitzungen Daten an denselben Stream senden, werden die Medienfragmente im Stream verschachtelt. Sie sollten sicherstellen, dass dies in Ihrem Anwendungsszenario in Ordnung ist.

Bei der Verwendung der PutMedia API gelten die folgenden Beschränkungen:

• Ein Client kann PutMedia bis zu fünf Mal pro Sekunde pro Stream aufrufen.

• Ein Client kann bis zu fünf Fragmente pro Sekunde pro Stream senden.

• Kinesis Video Streams liest Mediendaten mit einer Geschwindigkeit von bis zu 12,5 MB/Sekunde oder 100 Mbit/s während einer Sitzung. PutMedia

Beachten Sie die folgenden Einschränkungen. In diesen Fällen sendet Kinesis Video Streams die Fehlerbestätigung in der Antwort.

• Fragmente mit Zeitcodes, die den maximal zulässigen Grenzwert überschreiten, und die mehr als 50 MB an Daten enthalten, sind nicht zulässig.

• Fragmente, die mehr als drei Spuren enthalten, sind nicht zulässig. Jeder Frame in jedem Fragment muss dieselbe Spurnummer haben wie eine der im Fragment-Header definierten Spuren. Darüber hinaus muss jedes Fragment mindestens einen Frame für jede im Fragment-Header definierte Spur enthalten.

• Jedes Fragment muss mindestens einen Frame für jede in den Fragment-Metadaten definierte Spur enthalten.

• Der früheste Frame-Zeitstempel in einem Fragment muss nach dem letzten Frame-Zeitstempel im vorherigen Fragment liegen.

• Ein MKV-Stream, der mehr als ein MKV-Segment enthält oder unzulässige MKV-Elemente (wietrack*) enthält, führt ebenfalls zur Fehlerbestätigung.

Kinesis Video Streams speichert jedes eingehende Fragment und die zugehörigen Metadaten in einem sogenannten „Chunk“. Die Fragment-Metadaten umfassen Folgendes:

• Die MKV-Header, die zu Beginn der Anfrage bereitgestellt wurden PutMedia

• Die folgenden Kinesis Video Streams-spezifischen Metadaten für das Fragment:

  • server_timestamp- Zeitstempel, zu dem Kinesis Video Streams mit dem Empfang des Fragments begonnen hat.

  • producer_timestamp- Zeitstempel, wann der Produzent mit der Aufnahme des Fragments begonnen hat. Kinesis Video Streams verwendet drei in der Anfrage empfangene Informationen, um diesen Wert zu berechnen.

    • Der Timecode-Wert des Fragments, der zusammen mit dem Fragment im Hauptteil der Anfrage empfangen wurde.

    • Zwei Anforderungsheader: producerStartTimestamp (als der Produzent mit der Aufnahme begonnen hat) und fragmentTimeCodeType (ob der Fragment-Timecode in der Payload absolut oder relativ ist).

    Kinesis Video Streams berechnet dann den producer_timestamp für das Fragment wie folgt:

    Wenn es relativ fragmentTimeCodeType ist, dann

    producer_timestamp= producerStartTimeStamp + Fragment-Timecode

    Wenn fragmentTimeCodeType es absolut ist, dann

    producer_timestamp= Fragment-Timecode (in Millisekunden umgewandelt)

  • Von Kinesis Video Streams zugewiesene eindeutige Fragmentnummer.

Anmerkung

Wenn Sie die GetMedia Anfrage stellen, gibt Kinesis Video Streams einen Stream dieser Chunks zurück. Der Client kann die Metadaten nach Bedarf verarbeiten.

Anmerkung

Dieser Vorgang ist nur für das AWS SDK for Java verfügbar. Er wird in AWS SDKs für andere Sprachen nicht unterstützt.

Anmerkung

Kinesis Video Streams analysiert und validiert die privaten Codec-Daten während der Aufnahme und Archivierung über die API nicht. PutMedia KVS extrahiert und validiert die erforderlichen Informationen aus den privaten Codec-Daten für das Verpacken von MPEG-TS- und MP4-Fragmenten, wenn der Stream über die HLS-APIs abgerufen wird.

Anmerkung

Wenn nach dem Aufrufen einer Kinesis Video Streams Streams-Medien-API ein Fehler ausgelöst wird, enthält dieser zusätzlich zum HTTP-Statuscode und dem Antworttext die folgenden Informationen:

• x-amz-ErrorTypeHTTP-Header — enthält zusätzlich zu dem, was der HTTP-Statuscode bietet, einen spezifischeren Fehlertyp.

• x-amz-RequestIdHTTP-Header — Wenn Sie ein Problem melden möchten AWS, kann das Support-Team das Problem anhand der Anforderungs-ID besser diagnostizieren.

Sowohl der HTTP-Statuscode als auch der ErrorType Header können verwendet werden, um programmatische Entscheidungen darüber zu treffen, ob und unter welchen Bedingungen Fehler wiederholt werden können. Außerdem können Informationen darüber bereitgestellt werden, welche Maßnahmen der Client-Programmierer möglicherweise ergreifen muss, um es erneut erfolgreich zu versuchen.

Weitere Informationen finden Sie im Abschnitt Fehler am Ende dieses Themas sowie unter Häufige Fehler.

Anforderungssyntax

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

URI-Anfrageparameter

Die Anforderung verwendet die folgenden URI-Parameter.

FragmentTimecodeType

Sie übergeben diesen Wert als x-amzn-fragment-timecode-type HTTP-Header.

Gibt an, ob die Timecodes in den Fragmenten (Payload, HTTP-Anforderungstext) absolut oder relativ zu sind. producerStartTimestamp Kinesis Video Streams verwendet diese Informationen, um die producer_timestamp für das in der Anfrage empfangene Fragment zu berechnen, wie in der API-Übersicht beschrieben.

Zulässige Werte: ABSOLUTE | RELATIVE

Erforderlich: Ja

ProducerStartTimestamp

Sie übergeben diesen Wert als x-amzn-producer-start-timestamp HTTP-Header.

Dies ist der Producer-Zeitstempel, zu dem der Producer mit der Aufnahme der Medien begonnen hat (nicht der Zeitstempel der spezifischen Fragmente in der Anfrage).

StreamARN

Sie übergeben diesen Wert als x-amzn-stream-arn HTTP-Header.

Amazon-Ressourcenname (ARN) des Kinesis-Videostreams, in den Sie den Medieninhalt schreiben möchten. Wenn Sie den nicht angebenstreamARN, müssen Sie den streamName angeben.

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge beträgt 1024 Zeichen.

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

StreamName

Sie übergeben diesen Wert als x-amzn-stream-name HTTP-Header.

Name des Kinesis-Videostreams, in den Sie den Medieninhalt schreiben möchten. Wenn Sie den nicht angebenstreamName, müssen Sie den streamARN angeben.

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge beträgt 256 Zeichen.

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

Anforderungstext

Die Anfrage akzeptiert die folgenden Binärdaten.

Payload

Der Medieninhalt, der in den Kinesis-Videostream geschrieben werden soll. In der aktuellen Implementierung unterstützt Kinesis Video Streams nur das Matroska (MKV) -Containerformat mit einem einzigen MKV-Segment. Ein Segment kann einen oder mehrere Cluster enthalten.

Anmerkung

Jeder MKV-Cluster ist einem Kinesis-Videostream-Fragment zugeordnet. Die von Ihnen gewählte Clusterdauer wird zur Fragmentdauer.

Antwortsyntax

HTTP/1.1 200

Payload

Antwortelemente

Wenn die Aktion erfolgreich ist, sendet der Service eine HTTP 200-Antwort zurück.

Die Antwort gibt folgendes als HTTP-Hauptteil zurück.

Payload

Nachdem Kinesis Video Streams erfolgreich eine PutMedia Anfrage empfangen hat, validiert der Dienst die Anforderungsheader. Der Dienst beginnt dann mit dem Lesen der Payload und sendet zunächst eine HTTP 200-Antwort.

Der Dienst gibt dann einen Stream zurück, der eine Reihe von JSON-Objekten (AcknowledgementObjekten) enthält, die durch Zeilenumbrüche getrennt sind. Die Bestätigungen werden auf derselben Verbindung empfangen, über die die Mediendaten gesendet werden. Für eine Anfrage kann es viele Bestätigungen geben. PutMedia Jedes Acknowledgement besteht aus den folgenden Schlüssel-Wert-Paaren:

• AckEventType- Ereignistyp, für den die Bestätigung steht.

  • Pufferung: Kinesis Video Streams hat begonnen, das Fragment zu empfangen. Kinesis Video Streams sendet die erste Buffering-Bestätigung, wenn das erste Byte von Fragmentdaten empfangen wird.

  • Empfangen: Kinesis Video Streams hat das gesamte Fragment empfangen. Wenn Sie den Stream nicht so konfiguriert haben, dass die Daten dauerhaft gespeichert werden, kann der Producer die Pufferung des Fragments beenden, sobald er diese Bestätigung erhält.

  • Persistent: Kinesis Video Streams hat das Fragment beibehalten (z. B. in Amazon S3). Sie erhalten diese Bestätigung, wenn Sie den Stream so konfiguriert haben, dass die Daten dauerhaft gespeichert werden. Nachdem Sie diese Bestätigung erhalten haben, kann der Producer die Pufferung des Fragments beenden.

  • Fehler: Bei Kinesis Video Streams ist bei der Verarbeitung des Fragments ein Fehler aufgetreten. Sie können den Fehlercode überprüfen und die nächste Vorgehensweise festlegen.

  • Inaktiv: Die PutMedia Sitzung ist im Gange. Kinesis Video Streams empfängt derzeit jedoch keine Daten. Kinesis Video Streams sendet diese Bestätigung in regelmäßigen Abständen für bis zu 30 Sekunden nach den letzten empfangenen Daten. Wenn innerhalb der 30 Sekunden keine Daten empfangen werden, schließt Kinesis Video Streams die Anfrage.

    Anmerkung

    Anhand dieser Bestätigung kann ein Produzent feststellen, ob die PutMedia Verbindung aktiv ist, auch wenn keine Daten gesendet werden.

• FragmentTimecode— Fragment-Timecode, für den die Bestätigung gesendet wird.

  Das Element kann fehlen, wenn es im Leerlauf istAckEventType.

• FragmentNumber- Von Kinesis Video Streams generierte Fragmentnummer, für die die Bestätigung gesendet wird.

• ErrorIdund ErrorCode — Falls jaError, enthält dieses Feld den AckEventType entsprechenden Fehlercode. Im Folgenden finden Sie eine Liste der Fehler-IDs und der entsprechenden Fehlercodes und Fehlermeldungen:

  • 4000 - STREAM_READ_ERROR - Fehler beim Lesen des Datenstroms.

  • 4001 - MAX_FRAGMENT_SIZE_REACHED — Die Fragmentgröße liegt über dem zulässigen Höchstwert von 50 MB.

  • 4002 - MAX_FRAGMENT_DURATION_REACHED — Die Fragmentdauer liegt über dem maximal zulässigen Grenzwert.

  • 4003 - MAX_CONNECTION_DURATION_REACHED — Die Verbindungsdauer ist größer als der maximal zulässige Schwellenwert.

  • 4004 - FRAGMENT_TIMECODE_LESSER_THAN_PREVIOUS — Der Fragment-Timecode ist kleiner als der Timecode des vorherigen Timecodes (innerhalb eines Anrufs können Sie Fragmente nicht in der falschen Reihenfolge senden). PutMedia

  • 4005 - MORE_THAN_ALLOWED_TRACKS_FOUND - In MKV wurde mehr als ein Titel gefunden. (veraltet)

  • 4006 - INVALID_MKV_DATA - Der Eingabestream konnte nicht als gültiges MKV-Format analysiert werden.

  • 4007 - INVALID_PRODUCER_TIMESTAMP — Ungültiger Producer-Zeitstempel.

  • 4008 - STREAM_NOT_ACTIVE - Stream existiert nicht mehr (gelöscht).

  • 4009 - FRAGMENT_METADATA_LIMIT_REACHED — Das Limit für Fragment-Metadaten wurde erreicht. Weitere Informationen finden Sie im Abschnitt Grenzwerte im Entwicklerhandbuch.

  • 4010 - TRACK_NUMBER_MISMATCH — Die Titelnummer in einem MKV-Frame stimmte nicht mit den Titeln im MKV-Header überein.

  • 4011 - FRAMES_MISSING_FOR_TRACK - Das Fragment enthielt keine Frames für mindestens einen der Tracks im MKV-Header.

  • 4012 - INVALID_FRAGMENT_METADATA - Der Name der Fragment-Metadaten darf nicht mit der Zeichenfolge beginnen. AWS_

  • 4500 - KMS_KEY_ACCESS_DENIED — Der Zugriff auf den angegebenen KMS-Schlüssel des Streams wurde verweigert.

  • 4501 - KMS_KEY_DISABLED — Der für den Stream angegebene KMS-Schlüssel ist deaktiviert.

  • 4502 - KMS_KEY_VALIDATION_ERROR — Der angegebene KMS-Schlüssel des Streams konnte nicht überprüft werden.

  • 4503 - KMS_KEY_UNAVAILABLE — Der angegebene KMS-Schlüssel für den Stream ist nicht verfügbar.

  • 4504 - KMS_KEY_INVALID_USAGE — Ungültige Verwendung des angegebenen KMS-Schlüssels für den Stream.

  • 4505 - KMS_KEY_INVALID_STATE — Der angegebene KMS-Schlüssel des Streams befindet sich in einem ungültigen Zustand.

  • 4506 - KMS_KEY_NOT_FOUND — Der angegebene KMS-Schlüssel des Streams wurde nicht gefunden.

  • 5000 - INTERNAL_ERROR - Interner Dienstfehler.

  • 5001 - ARCHIVAL_ERROR - Kinesis Video Streams konnte keine Fragmente im Datenspeicher speichern.

Anmerkung

Der Producer sollte beim Senden der Nutzdaten für eine lang andauernde PutMedia Anfrage die Antwort zur Bestätigung lesen. Ein Producer kann aufgrund der Pufferung auf einem zwischengeschalteten Proxyserver mehrere Bestätigungen gleichzeitig erhalten. Ein Produzent, der zeitnahe Bestätigungen erhalten möchte, kann in jeder Anfrage weniger Fragmente senden. PutMedia

Fehler

Weitere Informationen zu den allgemeinen Fehlern, die bei allen Aktionen zurückgegeben werden, finden Sie unter Häufige Fehler.

ClientLimitExceededException

Kinesis Video Streams hat die Anfrage gedrosselt, weil Sie das Limit der erlaubten Client-Aufrufe überschritten haben. Versuchen Sie später, den Anruf zu tätigen.

HTTP Status Code: 400

ConnectionLimitExceededException

Kinesis Video Streams hat die Anfrage gedrosselt, weil Sie das Limit der zulässigen Client-Verbindungen überschritten haben.

HTTP Status Code: 400

InvalidArgumentException

Der Wert für diesen Eingabeparameter ist ungültig.

HTTP Status Code: 400

InvalidEndpointException

Der Aufrufer hat einen falschen Endpunkt verwendet, um Daten in einen Stream zu schreiben. Bei Empfang einer solchen Ausnahme muss der Benutzer GetDataEndpoint mit APIName set to aufrufen PUT_MEDIA und den Endpunkt aus der Antwort verwenden, um den nächsten PutMedia Aufruf aufzurufen.

HTTP Status Code: 400

NotAuthorizedException

Der Aufrufer ist nicht autorisiert, eine Operation mit dem angegebenen Stream auszuführen, oder das Token ist abgelaufen.

HTTP-Statuscode: 401

ResourceNotFoundException

Statuscode: 404, Der Stream mit dem angegebenen Namen existiert nicht.

HTTP Status Code: 404

Beispiele

Format der Bestätigung

Das Format der Bestätigung lautet wie folgt:

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

Weitere Informationen finden Sie unter:

Weitere Informationen zur Verwendung dieser API in einem der sprachspezifischen AWS SDKs finden Sie im Folgenden:

• AWS -Befehlszeilenschnittstelle

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go v2

• AWS SDK for Java V2

• AWS SDK für JavaScript V3

• AWS SDK for PHP V3

• AWS SDK für Python

• AWS SDK for Ruby V3