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à.
# Comprendi le specifiche di richiesta e risposta di consegna 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.
Attualmente, solo la porta 443 è supportata per la distribuzione dei dati degli endpoint HTTP.
**Intestazioni HTTP - -Versione X-Amz-Firehose-Protocol**
Questa intestazione viene utilizzata per indicare la versione dei formati di richiesta/risposta. Attualmente, l'unica versione consentita è 1.0.
**Intestazioni HTTP - -Id X-Amz-Firehose-Request**
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 - -Arn: X-Amz-Firehose-Source**
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 - -Key X-Amz-Firehose-Access**
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. Tuttavia, se si utilizza Secrets Manager per configurare la chiave, il segreto deve seguire un formato oggetto JSON specifico:`{"api_key": "..."}`.
I contenuti possono essere arbitrari e possono potenzialmente rappresentare un token JWT o un ACCESS\$1KEY. 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, and/or codifica il valore configurato e utilizza i contenuti così come sono.
**Intestazioni HTTP - -Attributi X-Amz-Firehose-Common**
Questa intestazione contiene gli attributi comuni (metadati) relativi all'intera richiesta, a tutti i record and/or 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 \$1 (multiplier (2) ^ retry\$1count)) 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) \$1 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 and/or destinazione della chiave di accesso a cui vengono consegnati i record potrebbe 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 richiesta proveniente dall'origine 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"
}
]
}
}
]
}
```