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. # Verstehen Sie die Anforderungen- und Antwortspezifikationen für die HTTP-Endpunktzustellung Damit Amazon Data Firehose erfolgreich Daten an benutzerdefinierte HTTP-Endpunkte liefern kann, müssen diese Endpunkte Anfragen annehmen und Antworten in bestimmten Amazon Data Firehose-Anfrage- und Antwortformaten senden. In diesem Abschnitt werden die Formatspezifikationen der HTTP-Anfragen beschrieben, die der Amazon Data Firehose-Service an benutzerdefinierte HTTP-Endpunkte sendet, sowie die Formatspezifikationen der HTTP-Antworten, die der Amazon Data Firehose-Service erwartet. HTTP-Endpunkte haben 3 Minuten Zeit, um auf eine Anfrage zu antworten, bevor Amazon Data Firehose das Zeitlimit für diese Anfrage überschreitet. Amazon Data Firehose behandelt Antworten, die nicht dem richtigen Format entsprechen, als Zustellungsfehler. ## Anforderungsformat **Pfad- und URL-Parameter** Diese werden direkt von Ihnen als Teil eines einzigen URL-Felds konfiguriert. Amazon Data Firehose sendet sie wie konfiguriert ohne Änderung. Es werden nur HTTPS-Ziele unterstützt. URL-Einschränkungen werden bei der Konfiguration des Bereitstellungsdatenstroms angewendet. Derzeit wird nur Port 443 für die Bereitstellung von HTTP-Endpunktdaten unterstützt. **HTTP-Header — -Version X-Amz-Firehose-Protocol** Dieser Header wird verwendet, um die Version der Anforderungs-/Antwortformate anzugeben. Derzeit gibt es nur die Version 1.0. **HTTP-Header - -ID X-Amz-Firehose-Request** Der Wert dieses Headers ist eine undurchsichtige GUID, die für Debugging- und Deduplizierungszwecke verwendet werden kann. Endpunktimplementierungen sollten den Wert dieses Headers nach Möglichkeit sowohl für erfolgreiche als auch für erfolglose Anfragen protokollieren. Die Anforderungs-ID wird bei mehreren Versuchen derselben Anfrage unverändert beibehalten. **HTTP-Header – Inhaltstyp** Der Wert des Content-Type-Headers ist immer `application/json`. **HTTP-Header – Inhaltskodierung** Ein Firehose-Stream kann so konfiguriert werden, dass er GZIP verwendet, um den Hauptteil beim Senden von Anfragen zu komprimieren. Wenn diese Komprimierung aktiviert ist, wird der Wert des Content-Encoding-Headers gemäß der Standardpraxis auf gzip gesetzt. Wenn die Komprimierung nicht aktiviert ist, fehlt der Content-Encoding-Header vollständig. **HTTP-Header – Inhaltslänge** Dies wird standardmäßig verwendet. **HTTP-Header - -Arn: X-Amz-Firehose-Source** Der ARN des Firehose-Streams, dargestellt im ASCII-String-Format. Der ARN kodiert die Region, die AWS Konto-ID und den Streamnamen. Beispiel, `arn:aws:firehose:us-east-1:123456789:deliverystream/testStream`. **HTTP-Header — -Schlüssel X-Amz-Firehose-Access** Dieser Header enthält einen API-Schlüssel oder andere Anmeldeinformationen. Sie haben die Möglichkeit, den API-Schlüssel (auch Autorisierungstoken genannt) zu erstellen oder zu aktualisieren, wenn Sie Ihren Bereitstellungsdatenstrom erstellen oder aktualisieren. Amazon Data Firehose beschränkt die Größe des Zugriffsschlüssels auf 4096 Byte. Amazon Data Firehose versucht in keiner Weise, diesen Schlüssel zu interpretieren. Der konfigurierte Schlüssel wird wortwörtlich in den Wert dieses Headers kopiert. Wenn Sie jedoch Secrets Manager verwenden, um den Schlüssel zu konfigurieren, muss der geheime Schlüssel einem bestimmten JSON-Objektformat folgen:`{"api_key": "..."}`. Der Inhalt kann beliebig sein und möglicherweise ein JWT-Token oder einen ACCESS\$1KEY darstellen. Wenn für einen Endpunkt Anmeldeinformationen mit mehreren Feldern erforderlich sind (z. B. Benutzername und Passwort), sollten die Werte aller Felder zusammen in einem einzigen Zugriffsschlüssel in einem Format gespeichert werden, das der Endpunkt versteht (JSON oder CSV). Dieses Feld kann Base-64-kodiert sein, wenn der ursprüngliche Inhalt binär ist. Amazon Data Firehose ändert den and/or konfigurierten Wert nicht und verwendet den Inhalt unverändert. **HTTP-Header — -Attribute X-Amz-Firehose-Common** Dieser Header enthält die gemeinsamen Attribute (Metadaten), die sich auf die gesamte Anfrage beziehen, und zwar and/or auf alle Datensätze innerhalb der Anfrage. Diese werden direkt von Ihnen konfiguriert, wenn Sie einen Firehose-Stream erstellen. Der Wert dieses Attributs ist als JSON-Objekt mit dem folgenden Schema kodiert: ``` "$schema": http://json-schema.org/draft-07/schema# properties: commonAttributes: type: object minProperties: 0 maxProperties: 50 patternProperties: "^.{1,256}$": type: string minLength: 0 maxLength: 1024 ``` Hier ein Beispiel: ``` "commonAttributes": { "deployment -context": "pre-prod-gamma", "device-types": "" } ``` **Hauptteil – maximale Größe** Die maximale Körpergröße wird von Ihnen konfiguriert und kann vor der Komprimierung bis zu 64 MiB betragen. **Körper – Schema** Der Hauptteil enthält ein einzelnes JSON-Dokument mit dem folgenden JSON-Schema (in YAML geschrieben): ``` "$schema": http://json-schema.org/draft-07/schema# title: FirehoseCustomHttpsEndpointRequest description: > The request body that the Firehose service sends to custom HTTPS endpoints. type: object properties: requestId: description: > Same as the value in the X-Amz-Firehose-Request-Id header, duplicated here for convenience. type: string timestamp: description: > The timestamp (milliseconds since epoch) at which the Firehose server generated this request. type: integer records: description: > The actual records of the Firehose stream, carrying the customer data. type: array minItems: 1 maxItems: 10000 items: type: object properties: data: description: > The data of this record, in Base64. Note that empty records are permitted in Firehose. The maximum allowed size of the data, before Base64 encoding, is 1024000 bytes; the maximum length of this field is therefore 1365336 chars. type: string minLength: 0 maxLength: 1365336 required: - requestId - records ``` Hier ein Beispiel: ``` { "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f", "timestamp": 1578090901599 "records": [ { "data": "aGVsbG8=" }, { "data": "aGVsbG8gd29ybGQ=" } ] } ``` ## Reaktionsformat **Standardverhalten bei einem Fehler** Wenn eine Antwort die folgenden Anforderungen nicht erfüllt, behandelt der Firehose-Server sie so, als ob sie einen Statuscode 500 ohne Text hätte. **Statuscode** Der HTTP-Statuscode MUSS im 2XX-, 4XX- oder 5XX-Bereich liegen. Der Amazon Data Firehose-Server folgt KEINEN Weiterleitungen (3XX-Statuscodes). Nur der Antwortcode 200 gilt als erfolgreiche Übermittlung der Datensätze an HTTP/EP. Der Antwortcode 413 (Größe überschritten) wird als permanenter Fehler betrachtet und der Datensatzstapel wird nicht an den Fehler-Bucket gesendet, wenn er konfiguriert ist. Alle anderen Antwortcodes gelten als wiederherstellbare Fehler und unterliegen einem Back-off-Wiederholungsalgorithmus, der später erklärt wird. **Header – Inhaltstyp** Der einzig akzeptable Inhaltstyp ist application/json. **HTTP-Header – Inhaltskodierung** Content-Encoding DARF NICHT verwendet werden. Der Hauptteil MUSS unkomprimiert sein. **HTTP-Header – Inhaltslänge** Der Content-Length-Header MUSS vorhanden sein, wenn die Antwort einen Hauptteil hat. **Hauptteil – maximale Größe** Der Antworttext darf höchstens 1 MiB groß sein. ``` "$schema": http://json-schema.org/draft-07/schema# title: FirehoseCustomHttpsEndpointResponse description: > The response body that the Firehose service sends to custom HTTPS endpoints. type: object properties: requestId: description: > Must match the requestId in the request. type: string timestamp: description: > The timestamp (milliseconds since epoch) at which the server processed this request. type: integer errorMessage: description: > For failed requests, a message explaining the failure. If a request fails after exhausting all retries, the last Instance of the error message is copied to error output S3 bucket if configured. type: string minLength: 0 maxLength: 8192 required: - requestId - timestamp ``` Hier ein Beispiel: ``` Failure Case (HTTP Response Code 4xx or 5xx) { "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f", "timestamp": "1578090903599", "errorMessage": "Unable to deliver records due to unknown error." } Success case (HTTP Response Code 200) { "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f", "timestamp": 1578090903599 } ``` **Umgang mit Fehlerreaktionen** In allen Fehlerfällen versucht der Amazon Data Firehose-Server erneut, denselben Stapel von Datensätzen mithilfe eines exponentiellen Back-off-Algorithmus zuzustellen. Die Wiederholungen werden anhand einer anfänglichen Back-Off-Zeit (1 Sekunde) mit einem Jitterfaktor von (15%) zurückgesetzt, und jede weitere Wiederholung wird anhand der Formel (initial-backoff-time \$1 (multiplier (2) ^ retry\$1count)) mit zusätzlichem Jitter zurückgestellt. Die Backoff-Zeit ist auf ein maximales Intervall von 2 Minuten begrenzt. Beispielsweise beträgt die Back-Off-Zeit bei der 'n-ten Wiederholung = MAX (120, 2^n) \$1 random (0,85, 1,15). Die in der vorherigen Gleichung angegebenen Parameter können sich ändern. Die genaue anfängliche Backoff-Zeit, AWS die maximale Backoff-Zeit, den Multiplikator und die Jitter-Prozentsätze, die im exponentiellen Backoff-Algorithmus verwendet werden, finden Sie in der Firehose-Dokumentation. Bei jedem nachfolgenden Wiederholungsversuch kann sich das and/or Zugriffsschlüsselziel, an das Datensätze übermittelt werden, basierend auf der aktualisierten Konfiguration des Firehose ändern. Der Amazon Data Firehose-Service verwendet dieselbe Anforderungs-ID für alle Wiederholungen nach bestem Wissen und Gewissen. Das letzte Feature kann vom HTTP-Endpunktserver zur Deduplizierung verwendet werden. Wenn die Anfrage nach Ablauf der maximal zulässigen Zeit (basierend auf der Firehose-Stream-Konfiguration) immer noch nicht zugestellt wird, kann der Datensatzstapel optional auf der Grundlage der Stream-Konfiguration an einen Fehler-Bucket übermittelt werden. ## Beispiele Beispiel für eine Anfrage mit CWLog Herkunft. ``` { "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f", "timestamp": 1578090901599, "records": [ { "data": { "messageType": "DATA_MESSAGE", "owner": "123456789012", "logGroup": "log_group_name", "logStream": "log_stream_name", "subscriptionFilters": [ "subscription_filter_name" ], "logEvents": [ { "id": "0123456789012345678901234567890123456789012345", "timestamp": 1510109208016, "message": "log message 1" }, { "id": "0123456789012345678901234567890123456789012345", "timestamp": 1510109208017, "message": "log message 2" } ] } } ] } ```