Noções básicas das especificações de solicitação e resposta de entrega de endpoint de HTTP

Eles são configurados diretamente por você como parte de um único campo de URL. O Amazon Data Firehose os envia como foram configurados, sem modificação. Somente há suporte para destinos de https. As restrições de URL são aplicadas durante a configuração do fluxo de entrega.

Esse cabeçalho é usado para indicar a versão dos formatos de solicitação/resposta. Atualmente, a única versão é a 1.0.

O valor desse cabeçalho é um GUID opaco que pode ser usado para depuração e eliminação de duplicações. As implementações de endpoint devem registrar em log o valor desse cabeçalho, se possível, tanto para solicitações com êxito ou não. O ID da solicitação é mantido entre as várias tentativas da mesma solicitação.

O valor do cabeçalho Content-Type é sempre application/json.

Um fluxo do Firehose pode ser configurado para usar o GZIP para compactar o corpo das solicitações ao enviá-las. Quando essa compactação está habilitada, o valor do cabeçalho Content-Encoding é definido como gzip, de acordo com a prática padrão. Se a compactação não estiver habilitada, o cabeçalho Content-Encoding estará totalmente ausente.

Isso é usado da maneira padrão.

O ARN do fluxo do Firehose representado no formato string ASCII. O ARN codifica a região, o ID da conta da AWS e o nome do fluxo. Por exemplo, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

Esse cabeçalho carrega uma chave de API ou outras credenciais. É possível criar ou atualizar a chave de API (também conhecida como token de autorização) ao criar ou atualizar seu fluxo de entrega. O Amazon Data Firehose restringe o tamanho da chave de acesso a 4.096 bytes. O Amazon Data Firehose não tenta, de maneira nenhuma, interpretar essa chave. A chave configurada é copiada literalmente para o valor desse cabeçalho.

O conteúdo pode ser arbitrário e pode representar um token JWT ou uma ACCESS_KEY. Se um endpoint exigir credenciais com vários campos (por exemplo, nome de usuário e senha), os valores de todos os campos devem ser armazenados juntos em uma única chave de acesso em um formato que o endpoint entenda (JSON ou CSV). Esse campo pode ser codificado na base 64 se o conteúdo original for binário. O Amazon Data Firehose não modifica e/ou codifica o valor configurado e usa o conteúdo sem alterações.

Esse cabeçalho transporta os atributos comuns (metadados) relativos à solicitação inteira e/ou a todos os registros dentro da solicitação. Eles são configurados diretamente por você ao criar um fluxo do Firehose. O valor desse atributo é codificado como um objeto JSON com o seguinte 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    

Veja um exemplo abaixo:

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

O tamanho máximo do corpo é configurado por você e pode ter até 64 MiB, antes de compactado.

O corpo leva um único documento JSON com o seguinte esquema JSON (escrito em 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
                    

Veja um exemplo abaixo:

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

Se uma resposta não estiver em conformidade com os requisitos abaixo, o servidor do Firehose a tratará como se tivesse um código de status 500 sem corpo.

O código de status do HTTP DEVE estar no intervalo 2XX, 4XX ou 5XX.

O servidor do Amazon Data Firehose NÃO segue redirecionamentos (códigos de status 3XX). Somente o código de resposta 200 é considerado uma entrega com êxito de registros para HTTP/EP. O código de resposta 413 (tamanho excedido) é considerado uma falha permanente, e o lote de registros não é enviado para o bucket de erros, se configurado. Todos os outros códigos de resposta são considerados erros passíveis de novas tentativas e estão sujeitos ao algoritmo de novas tentativas de recuo que será explicado posteriormente.

O único tipo de conteúdo aceitável é aplicação/json.

A codificação de conteúdo NÃO DEVE ser usada. O corpo DEVE estar descompactado.

O cabeçalho Content-Length DEVE estar presente se a resposta tiver um corpo.

O corpo da resposta deve ter no máximo 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
                    

Veja um exemplo abaixo:

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
}
                    

Em todos os casos de erro, o servidor d Amazon Data Firehose faz uma nova tentativa de entrega do mesmo lote de registros usando um algoritmo de recuo exponencial. As novas tentativas são canceladas usando um tempo de recuo inicial (1 segundo) com um fator de instabilidade de (15%), e cada nova tentativa subsequente é cancelada usando a fórmula (tempo de recuo inicial * (multiplicador (2) ^ número_tentativas)) com instabilidade adicionada. O tempo de recuo é limitado por um intervalo máximo de 2 minutos. Por exemplo, na 'n'-ésima tentativa, o tempo de recuo é = MAX(120, 2^n) * random(0,85, 1,15).

Os parâmetros especificados na equação anterior estão sujeitos a alterações. Consulte a documentação do AWS Firehose para ver o tempo exato de recuo inicial, o tempo máximo de recuo, o multiplicador e as porcentagens de instabilidade usadas no algoritmo de recuo exponencial.

Em cada nova tentativa subsequente, a chave de acesso e/ou o destino para o qual os registros são entregues podem mudar de acordo com a configuração atualizada do fluxo do Firehose. O serviço Amazon Data Firehose usa, dentro do máximo possível, o mesmo ID de solicitação em todas as novas tentativas. Esse último atributo pode ser usado para eliminar duplicação pelo servidor de endpoint de HTTP. Se a solicitação ainda não for entregue após o tempo máximo permitido (com base na configuração do fluxo do Firehose), o lote de registros poderá, opcionalmente, ser entregue a um bucket de erros de acordo com a configuração do fluxo.