Appendice: Specifiche delle richieste e delle risposte di distribuzione degli endpoint HTTP - Amazon Data Firehose
Formato della richiestaFormato della rispostaEsempi

Amazon Data Firehose era precedentemente noto come Amazon Kinesis Data Firehose

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Appendice: Specifiche delle richieste e delle risposte di distribuzione degli endpoint HTTP

Affinché Amazon Data Firehose fornisca correttamente i dati agli endpoint HTTP personalizzati, questi endpoint devono accettare richieste e inviare risposte utilizzando determinati formati di richiesta e risposta di Amazon Data Firehose. Questa sezione descrive le specifiche di formato delle richieste HTTP che il servizio Amazon Data Firehose invia agli endpoint HTTP personalizzati, nonché le specifiche di formato delle risposte HTTP che il servizio Amazon Data Firehose si aspetta. Gli endpoint HTTP dispongono di 3 minuti per rispondere a una richiesta prima che Amazon Data Firehose effettui il timeout della richiesta. Amazon Data Firehose considera le risposte che non rispettano il formato corretto come errori di consegna.

Formato della richiesta

Parametri relativi al percorso e all'URL

Questi parametri sono configurati direttamente dall'utente come parte di un singolo campo URL. Amazon Data Firehose li invia così come configurati senza modifiche. Sono supportate solo le destinazioni https. Le restrizioni relative agli URL vengono applicate durante la configurazione del flusso di distribuzione.

Nota

Attualmente, solo la porta 443 è supportata per la distribuzione dei dati degli endpoint HTTP.

Intestazioni HTTP: X-Amz-Firehose-Protocol-Version

Questa intestazione viene utilizzata per indicare la versione dei formati di richiesta/risposta. Attualmente, l'unica versione consentita è 1.0.

Intestazioni HTTP: X-Amz-Firehose-Request-Id

Il valore di questa intestazione è un GUID opaco che può essere utilizzato per scopi di debug e deduplicazione. Le implementazioni degli endpoint devono registrare il valore di questa intestazione, se possibile, sia per le richieste riuscite che per quelle non riuscite. L'ID della richiesta viene mantenuto invariato tra più tentativi della stessa richiesta.

Intestazioni HTTP: Content-Type

Il valore dell'intestazione Content-Type è sempre application/json.

Intestazioni HTTP: Content-Encoding

Uno stream Firehose può essere configurato per utilizzare GZIP per comprimere il body durante l'invio delle richieste. Quando questa compressione è abilitata, il valore dell'intestazione Content-Encoding è impostato su gzip, come da prassi standard. Se la compressione non è abilitata, l'intestazione Content-Encoding è del tutto assente.

Intestazioni HTTP: Content-Length

Viene utilizzato nel modo standard.

Intestazioni HTTP: X-Amz-Firehose-Source-Arn:

L'ARN del flusso Firehose rappresentato in formato stringa ASCII. L'ARN codifica la regione, l'ID AWS dell'account e il nome dello stream. Ad esempio, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

Intestazioni HTTP: X-Amz-Firehose-Access-Key

Questa intestazione contiene una chiave API o altre credenziali. Hai la possibilità di creare o aggiornare la chiave API (nota anche come token di autorizzazione) durante la creazione o l'aggiornamento del flusso di distribuzione. Amazon Data Firehose limita la dimensione della chiave di accesso a 4096 byte. Amazon Data Firehose non tenta di interpretare questa chiave in alcun modo. La chiave configurata viene copiata letteralmente nel valore di questa intestazione.

I contenuti possono essere arbitrari e possono potenzialmente rappresentare un token JWT o un ACCESS_KEY. Se un endpoint richiede credenziali multi-campo (ad esempio nome utente e password), i valori di tutti i campi devono essere memorizzati insieme in un'unica chiave di accesso in un formato comprensibile all'endpoint (JSON o CSV). Questo campo può essere codificato in base 64 se i contenuti originali sono binari. Amazon Data Firehose non modifica e/o codifica il valore configurato e utilizza i contenuti così come sono.

Intestazioni HTTP: X-Amz-Firehose-Common-Attributes

Questa intestazione contiene gli attributi comuni (metadati) che riguardano l'intera richiesta e/o tutti i record all'interno della richiesta. Questi vengono configurati direttamente dall'utente durante la creazione di uno stream Firehose. Il valore di questo attributo è codificato come oggetto JSON con il seguente schema: 


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

Ecco un esempio:


"commonAttributes": {
    "deployment -context": "pre-prod-gamma",
    "device-types": ""
  }
Corpo: dimensione massima

La dimensione massima del corpo è configurata dall'utente e può arrivare fino a un massimo di 64 MiB, prima della compressione.

Corpo: schema

Il corpo contiene un singolo documento JSON con il seguente schema JSON (scritto in YAML):


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

Ecco un esempio:


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

Formato della risposta

Comportamento predefinito in caso di errore

Se una risposta non è conforme ai requisiti seguenti, il server Firehose la considera come se avesse un codice di stato 500 senza corpo.

Codice di stato

Il codice di stato HTTP DEVE essere compreso nell'intervallo 2XX, 4XX o 5XX.

Il server Amazon Data Firehose NON segue i reindirizzamenti (codici di stato 3XX). Solo il codice di risposta 200 viene considerato come una distribuzione riuscita dei record a HTTP/EP. Il codice di risposta 413 (dimensione superata) è considerato un errore permanente e il batch di record non viene inviato al bucket di errori se configurato. Tutti gli altri codici di risposta sono considerati errori recuperabili e sono soggetti all'algoritmo di back-off relativo ai nuovi tentativi illustrato più avanti.

Intestazioni: tipo di contenuto

L'unico tipo di contenuto accettabile è application/json.

Intestazioni HTTP: Content-Encoding

La codifica del contenuto NON DEVE essere utilizzata. Il corpo DEVE essere decompresso.

Intestazioni HTTP: Content-Length

L'intestazione Content-Length DEVE essere presente se la risposta ha un corpo.

Corpo: dimensione massima

Il corpo della risposta deve avere dimensioni pari o inferiori a 1 MiB.


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

Ecco un esempio:


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
}
Gestione delle risposte di errore

In tutti i casi di errore, il server Amazon Data Firehose ritenta la consegna dello stesso batch di record utilizzando un algoritmo di back-off esponenziale. Il backup dei tentativi viene eseguito utilizzando un tempo di back-off iniziale (1 secondo) con un fattore di jitter del (15%) e ogni tentativo successivo viene bloccato utilizzando la formula (initial-backoff-time * (multiplier (2) ^ retry_count)) con jitter aggiunto. Il tempo di back-off è limitato a un intervallo massimo di 2 minuti. Ad esempio, al 'n'-esimo tentativo, il tempo di annullamento è = MAX (120, 2^n) * casuale (0,85, 1,15).

I parametri specificati nell'equazione precedente sono soggetti a modifiche. Fate riferimento alla documentazione di AWS Firehose per il tempo esatto di backoff iniziale, il tempo massimo di backoff, i moltiplicatori e le percentuali di jitter utilizzate nell'algoritmo di backoff esponenziale.

In ogni tentativo successivo, la chiave di accesso e/o la destinazione a cui vengono consegnati i record potrebbero cambiare in base alla configurazione aggiornata del flusso Firehose. Il servizio Amazon Data Firehose utilizza lo stesso ID di richiesta per tutti i tentativi nel miglior modo possibile. Quest'ultima funzionalità può essere utilizzata per scopi di deduplicazione dal server endpoint HTTP. Se la richiesta non viene ancora consegnata dopo il tempo massimo consentito (in base alla configurazione del flusso Firehose), il batch di record può essere facoltativamente inviato a un bucket di errori basato sulla configurazione del flusso.

Esempi

Esempio di una richiesta proveniente da CWLog:


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