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. HTTPEndgeräte haben 3 Minuten Zeit, um auf eine Anfrage zu antworten, bevor Amazon Data Firehose eine Zeitüberschreitung für diese Anfrage durchführt. Amazon Data Firehose behandelt Antworten, die nicht dem richtigen Format entsprechen, als Zustellungsfehler.

Anforderungsformat

Pfad und Parameter URL

Diese werden direkt von Ihnen als Teil eines einzigen URL Feldes konfiguriert. Amazon Data Firehose sendet sie wie konfiguriert ohne Änderung. Es werden nur HTTPS-Ziele unterstützt. URLBei der Konfiguration des Delivery-Streams gelten Einschränkungen.

Anmerkung

Derzeit wird nur Port 443 für die Bereitstellung von HTTP Endpunktdaten unterstützt.

HTTPHeader - X-Amz-Firehose-Protokoll-Version

Dieser Header wird verwendet, um die Version der Anforderungs-/Antwortformate anzugeben. Derzeit gibt es nur die Version 1.0.

HTTPHeader - X-Amz-Firehose-Anforderungs-ID

Der Wert dieses Headers ist undurchsichtig GUID und kann für Debugging- und Deduplizierungszwecke verwendet werden. 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.

HTTPHeader — Inhaltstyp

Der Wert des Content-Type-Headers ist immer application/json.

HTTPHeader — Kodierung von Inhalten

Ein Firehose-Stream kann so konfiguriert werden, dass er beim Senden von Anfragen GZIP zum Komprimieren des Hauptteils verwendet wird. 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.

HTTPHeader — Länge des Inhalts

Dies wird standardmäßig verwendet.

HTTPKopfzeilen - X-Amz-Firehose-SOURCE-ARN:

Der ARN des Firehose-Streams, der im ASCII Zeichenkettenformat dargestellt wird. Das ARN kodiert die Region, die AWS Konto-ID und den Streamnamen. Beispiel, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

HTTPHeader - X-Amz-Firehose-Access-Key

Dieser Header enthält einen Schlüssel oder andere Anmeldeinformationen. API Sie haben die Möglichkeit, den API -key (auch Autorisierungstoken genannt) zu erstellen oder zu aktualisieren, wenn Sie Ihren Delivery-Stream 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.

Der Inhalt kann beliebig sein und möglicherweise ein JWT Token oder ein ACCESS _ KEY 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 (JSONoder). CSV Dieses Feld kann Base-64-kodiert sein, wenn der ursprüngliche Inhalt binär ist. Amazon Data Firehose ändert und/oder codiert den konfigurierten Wert nicht und verwendet den Inhalt unverändert.

HTTPHeader - X-Amz-Firehose-Common-Attribute

Dieser Header enthält die gemeinsamen Attribute (Metadaten), die sich auf die gesamte Anfrage und/oder auf alle Datensätze innerhalb der Anfrage beziehen. 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    

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 (eingeschriebenYAML):

"$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
                    

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 liegt im MUST Bereich 2XX, 4XX oder 5XX.

Der Amazon Data Firehose-Server NOT folgt Weiterleitungen (3XX-Statuscodes). Nur der Antwortcode 200 gilt als erfolgreiche Übermittlung der Datensätze an /EP. HTTP 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.

HTTPKopfzeilen — Inhaltskodierung

MUSTNOTContent-Encoding soll verwendet werden. Der Körper MUST muss unkomprimiert sein.

HTTPKopfzeilen — Länge des Inhalts

Der Content-Length-Header MUST 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
                    

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 * (multiplier (2) ^ retry_count)) mit zusätzlichem Jitter zurückgestellt. Die Backoff-Zeit ist auf ein maximales Intervall von 2 Minuten begrenzt. Bei der 'n-ten Wiederholung ist die Back-Off-Zeit beispielsweise = MAX (120, 2^n) * 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 können sich der Zugriffsschlüssel und/oder das Ziel, an das die Datensätze übermittelt werden, aufgrund der aktualisierten Konfiguration des Firehose-Streams ändern. Der Amazon Data Firehose-Service verwendet dieselbe Anforderungs-ID für alle Wiederholungen nach bestem Wissen und Gewissen. Diese letzte Funktion kann vom Endpunktserver zur Deduplizierung verwendet werden. HTTP 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"
        }
      ]
    }
   }
  ]
}