Comprendre les spécifications relatives aux demandes de livraison et aux réponses des HTTP terminaux - Amazon Data Firehose
Format des demandesFormat de la réponseExemples

La diffusion de flux Amazon Data Firehose vers les tables Apache Iceberg dans Amazon S3 est en version préliminaire et peut faire l'objet de modifications.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Comprendre les spécifications relatives aux demandes de livraison et aux réponses des HTTP terminaux

Pour qu'Amazon Data Firehose puisse transmettre des données à des points de HTTP terminaison personnalisés, ces points de terminaison doivent accepter les demandes et envoyer des réponses en utilisant certains formats de demande et de réponse Amazon Data Firehose. Cette section décrit les spécifications de format des HTTP demandes que le service Amazon Data Firehose envoie aux HTTP points de terminaison personnalisés, ainsi que les spécifications de format des HTTP réponses attendues par le service Amazon Data Firehose. HTTPles points de terminaison disposent de 3 minutes pour répondre à une demande avant qu'Amazon Data Firehose n'expire cette demande. Amazon Data Firehose considère les réponses qui ne respectent pas le format approprié comme des échecs de livraison.

Format des demandes

Chemin et URL paramètres

Ils sont configurés directement par vous dans le cadre d'un URL champ unique. Amazon Data Firehose les envoie tels que configurés sans modification. Seules les destinations HTTPS sont prises en charge. URLdes restrictions sont appliquées lors de la configuration du flux de diffusion.

Note

Actuellement, seul le port 443 est pris en charge pour la livraison des données des HTTP terminaux.

HTTPEn-têtes - X-Amz-Firehose-Protocol-Version

Cet en-tête est utilisé pour indiquer la version des formats de demande et de réponse. Actuellement, la seule version est la version 1.0.

HTTPEn-têtes - X-Amz-Firehose-Request-Id

La valeur de cet en-tête est une valeur opaque GUID qui peut être utilisée à des fins de débogage et de déduplication. Les implémentations des points de terminaison doivent enregistrer la valeur de cet en-tête si possible, à la fois pour les requêtes réussies et pour celles qui ont échoué. L'ID de la demande reste le même entre plusieurs tentatives de la même demande.

HTTPEn-têtes - Type de contenu

La valeur de l'en-tête Content-Type est toujours application/json.

HTTPEn-têtes - Encodage du contenu

Un flux Firehose peut être configuré pour être utilisé pour GZIP compresser le corps lors de l'envoi de requêtes. Lorsque cette compression est activée, la valeur de l'en-tête Content-Encoding est définie sur gzip, conformément à la pratique standard. Si la compression n'est pas activée, l'en-tête Content-Encoding est totalement absent.

HTTPEn-têtes - Longueur du contenu

Ces en-têtes sont utilisés de manière standard.

HTTPEn-têtes - X-Amz-Firehose-Source-Arn :

Le ARN flux Firehose représenté sous ASCII forme de chaîne. Il ARN code la région, l'identifiant AWS du compte et le nom du flux. Par exemple, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

HTTPEn-têtes - X-Amz-Firehose-Access-Key

Cet en-tête contient une API clé ou d'autres informations d'identification. Il est possible de créer ou de mettre à jour le API -key (alias jeton d'autorisation) lors de la création ou de la mise à jour de votre flux de diffusion. Amazon Data Firehose limite la taille de la clé d'accès à 4 096 octets. Amazon Data Firehose n'essaie en aucun cas d'interpréter cette clé. La clé configurée est copiée exactement dans la valeur de cet en-tête.

Le contenu peut être arbitraire et peut potentiellement représenter un JWT jeton ou un ACCESS _KEY. Si un point de terminaison nécessite des informations d'identification à champs multiples (par exemple, nom d'utilisateur et mot de passe), les valeurs de tous les champs doivent être stockées ensemble dans une seule clé d'accès dans un format que le point de terminaison comprend (ou)JSON. CSV Ce champ peut être codé en base 64 si le contenu d'origine est binaire. Amazon Data Firehose ne modifie et/ou ne code pas la valeur configurée et utilise le contenu tel quel.

HTTPEn-têtes - X-Amz-Firehose-Common-Attributes

Cet en-tête contient les attributs communs (métadonnées) relatifs à l'ensemble de la demande ou à tous les enregistrements de la demande. Vous les configurez directement lors de la création d'un stream Firehose. La valeur de cet attribut est codée sous forme d'JSONobjet selon le schéma suivant : 


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

Voici un exemple :


"commonAttributes": {
    "deployment -context": "pre-prod-gamma",
    "device-types": ""
  }
Corps : taille maximale

Vous définissez vous-même la taille maximale du corps, qui peut aller jusqu'à 64 Mio, avant compression.

Corps : schéma

Le corps contient un seul JSON document avec le JSON schéma suivant (écrit enYAML) :


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

Voici un exemple :


{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599
  "records": [
    {
      "data": "aGVsbG8="
    },
    {
      "data": "aGVsbG8gd29ybGQ="
    }
  ]
}

Format de la réponse

Comportement par défaut en cas d'erreur

Si une réponse ne répond pas aux exigences ci-dessous, le serveur Firehose la traite comme si elle avait un code d'état 500 sans corps.

Code d'état

Le code HTTP d'état MUST doit être compris entre 2XX, 4XX ou 5XX.

Le serveur Amazon Data Firehose NOT suit les redirections (codes d'état 3XX). Seul le code de réponse 200 est considéré comme une livraison réussie des enregistrements à HTTP /EP. Le code de réponse 413 (taille dépassée) est considéré comme une défaillance permanente et le lot d'enregistrements n'est pas envoyé au compartiment d'erreurs s'il est configuré. Tous les autres codes de réponse sont considérés comme des erreurs réitérables et sont soumis à l'algorithme de tentative de retardement expliqué plus loin.

En-têtes HTTP : type de contenu

Le seul type de contenu acceptable est application/json.

HTTPEn-têtes - Encodage du contenu

Le codage du contenu MUST NOT doit être utilisé. Le corps MUST ne doit pas être comprimé.

HTTPEn-têtes - Longueur du contenu

L'en-tête Content-Length MUST doit être présent si la réponse a un corps.

Corps : taille maximale

La taille du corps de la réponse doit être inférieure ou égale à 1 Mio.


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

Voici un exemple :


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
}
Gestion des réponses d'erreur

Dans tous les cas d'erreur, le serveur Amazon Data Firehose tente à nouveau de livrer le même lot d'enregistrements à l'aide d'un algorithme de réduction exponentielle. Les nouvelles tentatives sont annulées en utilisant un temps d'attente initial (1 seconde) avec un facteur de gigue de (15 %) et chaque nouvelle tentative suivante est annulée en utilisant la formule (initial-backoff-time * (multiplicateur (2) ^ retry_count)) avec une instabilité accrue. Le temps de retard est limité à un intervalle maximal de deux minutes. Par exemple, lors de la neuvième tentative, le temps de retour est = MAX (120, 2^n) * random (0,85, 1,15).

Les paramètres spécifiés dans l'équation précédente sont susceptibles d'être modifiés. Reportez-vous à la documentation AWS Firehose pour connaître le temps d'arrêt initial exact, le temps d'arrêt maximal, le multiplicateur et les pourcentages de gigue utilisés dans l'algorithme de ralentissement exponentiel.

À chaque nouvelle tentative suivante, la clé d'accès et/ou la destination vers laquelle les enregistrements sont livrés peuvent changer en fonction de la configuration mise à jour du flux Firehose. Le service Amazon Data Firehose utilise le même identifiant de demande pour chaque nouvelle tentative, dans le meilleur des cas. Cette dernière fonctionnalité peut être utilisée à des fins de déduplication par le serveur de point de HTTP terminaison. Si la demande n'est toujours pas livrée après le délai maximum autorisé (selon la configuration du flux Firehose), le lot d'enregistrements peut éventuellement être envoyé vers un compartiment d'erreur basé sur la configuration du flux.

Exemples

Exemple de demande CWLog provenant d'une source.


{
  "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"
        }
      ]
    }
   }
  ]
}