Comprender las especificaciones de solicitudes y respuestas de entrega de puntos de conexión HTTP

Los configura directamente como parte de un único campo de URL. Amazon Data Firehose los envía tal y como están configurados, sin modificarlos. Solo se admiten los destinos HTTPS. Las restricciones de URL se aplican durante la configuración del flujo de entrega.

Este encabezado se usa para indicar la versión de los formatos de solicitudes o respuestas. Actualmente, la única versión es la 1.0.

El valor de este encabezado es un GUID opaco que se puede utilizar con fines de depuración y eliminación de duplicados. Si es posible, las implementaciones de puntos de conexión deben registrar el valor de este encabezado, tanto para las solicitudes que son correctas como para las que no lo son. El ID de solicitud se mantiene igual durante varios intentos de la misma solicitud.

El valor del encabezado Content-Type es siempre application/json.

Se puede configurar un flujo de Firehose para que utilice GZIP a fin de comprimir el cuerpo al enviar solicitudes. Cuando esta compresión está habilitada, el valor del encabezado Content-Encoding se establece en gzip, según la práctica habitual. Si la compresión no está habilitada, el encabezado Content-Encoding no aparece.

Se usa de forma estándar.

El ARN del flujo de Firehose se representa en formato de cadena ASCII. El ARN codifica la región, el ID de la cuenta de AWS y el nombre del flujo. Por ejemplo, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

Este encabezado contiene una clave de API u otras credenciales. Puede crear o actualizar la clave de API (también conocida como token de autorización) al crear o actualizar el flujo de entrega. Amazon Data Firehose restringe el tamaño de la clave de acceso a 4096 bytes. Amazon Data Firehose no intenta interpretar esta clave de ninguna manera. La clave configurada se copia palabra por palabra en el valor de este encabezado.

El contenido puede ser arbitrario y, potencialmente, representar un token JWT o una ACCESS_KEY. Si un punto de conexión requiere credenciales de varios campos (por ejemplo, nombre de usuario y contraseña), los valores de todos los campos deben almacenarse juntos en una única clave de acceso en un formato que el punto de conexión comprenda (JSON o CSV). Este campo puede codificarse en base64 si el contenido original es binario. Amazon Data Firehose no modifica ni codifica el valor configurado y utiliza el contenido tal cual.

Este encabezado contiene los atributos comunes (metadatos) que pertenecen a toda la solicitud o a todos los registros de la solicitud. Los configura directamente al crear un flujo de Firehose. El valor de este atributo está codificado como un objeto JSON con el siguiente esquema:

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

A continuación se muestra un ejemplo:

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

Configura el tamaño máximo del cuerpo, que puede ser de hasta 64 MiB antes de la compresión.

El cuerpo contiene un único documento JSON con el siguiente esquema JSON (escrito en 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
                    

A continuación se muestra un ejemplo:

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

Si una respuesta no cumple con los requisitos que se indican a continuación, el servidor de Firehose la tratará como si tuviera un código de estado 500 sin cuerpo.

El código de estado HTTP DEBE estar en el rango 2XX, 4XX o 5XX.

El servidor de Amazon Data Firehose NO sigue los redireccionamientos (códigos de estado 3XX). Solo el código de respuesta 200 se considera una entrega correcta de los registros a HTTP/EP. El código de respuesta 413 (tamaño excedido) se considera un error permanente y, si está configurado, el lote de registros no se envía al bucket de errores. Todos los demás códigos de respuesta se consideran errores recuperables y están sujetos a un algoritmo de reintentos de retroceso que se explica más adelante.

El único tipo de contenido aceptable es application/json.

NO SE DEBE utilizar Content-Encoding. El cuerpo DEBE estar descomprimido.

El encabezado Content-Length DEBE estar presente si la respuesta tiene un cuerpo.

El cuerpo de la respuesta debe tener un tamaño de 1 MiB o menos.

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

A continuación se muestra un ejemplo:

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
}
                    

En todos los casos de error, el servidor de Amazon Data Firehose vuelve a intentar entregar el mismo lote de registros mediante un algoritmo de retroceso exponencial. Los reintentos se retroceden con un tiempo de retroceso inicial (1 segundo) con un factor de fluctuación (15 %) y cada reintento posterior se retrocede con la fórmula (initial-backoff-time * (multiplier(2) ^ retry_count)) con la fluctuación agregada. El tiempo de retroceso está limitado a un intervalo máximo de 2 minutos. Por ejemplo, en el enésimo reintento, el tiempo de retroceso es = MAX(120, 2^n) * random(0.85, 1.15).

Los parámetros especificados en la ecuación anterior están sujetos a cambios. Consulte la documentación de AWS Firehose para conocer el tiempo de retroceso inicial exacto, el tiempo de retroceso máximo y los porcentajes de multiplicador y fluctuación utilizados en el algoritmo de retroceso exponencial.

En cada intento posterior, la clave de acceso o el destino en el que se entregan los registros pueden cambiar en función de la configuración actualizada del flujo de Firehose. El servicio Amazon Data Firehose utiliza el mismo ID de solicitud en todos los reintentos de la mejor manera posible. El servidor de puntos de conexión HTTP puede utilizar esta última característica con fines de eliminación de duplicados. Si la solicitud sigue sin entregarse después del tiempo máximo permitido (según la configuración del flujo de Firehose), el lote de registros se puede entregar opcionalmente en un bucket de errores según la configuración del flujo.