PutMedia - Amazon Kinesis Video Streams
AnforderungssyntaxURIParameter anfordernAnforderungstextAntwortsyntaxAntwortelementeFehlerBeispieleWeitere Informationen finden Sie unter:

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

PutMedia

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

Anmerkung

Sie müssen zuerst den aufrufen GetDataEndpointAPI, 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 (MKV) -Containerformat für das Senden von Mediendaten mit diesem Format. API

Sie haben die folgenden Optionen, um Daten damit zu senden: 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 Option die folgenden Überlegungen:

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

  • Um die Medien auf der Konsole oder via abspielen zu könnenHLS, sollte Track 1 jedes Fragments H.264-kodiertes Video enthalten, die CodecID in den Fragment-Metadaten sollte „V_MPEG/ISO/AVC“ lauten und die Fragment-Metadaten sollten AVCC formatierte private H.264-Codec-Daten 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 von gelten die folgenden Beschränkungen PutMediaAPI:

  • 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 (liketrack*) 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 zu Beginn der Anfrage angegebenen MKV Header 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)

    • Eindeutige Fragmentnummer, die von Kinesis Video Streams zugewiesen wurde.

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 AWS SDK für Java verfügbar. Sie wird in AWS SDKs anderen Sprachen nicht unterstützt.

Anmerkung

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

Anmerkung

Wenn nach dem Aufrufen eines Kinesis Video Streams-Mediums ein Fehler ausgegeben wirdAPI, enthält dieser neben dem HTTP Statuscode und dem Antworttext die folgenden Informationen:

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

  • x-amz-RequestIdHTTPHeader — 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 sie Informationen darüber liefern, 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

URIParameter anfordern

Die Anfrage 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 Header. x-amzn-stream-arn HTTP

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 Segment. MKV 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 Dienst 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 200-Antwort. HTTP

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 der zulässigen Höchstgrenze von 50 MB.

    • 4002 - MAX _ _ FRAGMENT DURATION _ REACHED - Die Fragmentdauer liegt über der maximal zulässigen Grenze.

    • 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 vorherige Timecode (innerhalb eines PutMedia Anrufs können Sie Fragmente nicht in der falschen Reihenfolge senden).

    • 4005 - MORE _ _ _ THAN ALLOWED TRACKS _ FOUND - Es wurde mehr als ein Titel gefunden in. MKV (veraltet)

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

    • 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 Fragmentmetadaten 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 Spuren 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 angegebene KMS Schlüssel des Streams 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 des Streams.

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

HTTPStatuscode: 400

ConnectionLimitExceededException

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

HTTPStatuscode: 400

InvalidArgumentException

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

HTTPStatuscode: 400

InvalidEndpointException

Der Anrufer 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.

HTTPStatuscode: 400

NotAuthorizedException

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

HTTPStatuscode: 401

ResourceNotFoundException

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

HTTPStatuscode: 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 API in einer der sprachspezifischen Sprachen finden Sie im Folgenden AWS SDKs: