Apêndice - Especificações de solicitação e resposta de entrega de endpoint HTTP - Amazon Kinesis Data Firehose
Formato de solicitaçãoFormato de respostaExemplos

Apêndice - Especificações de solicitação e resposta de entrega de endpoint HTTP

Para que o Kinesis Data Firehose entregue dados com sucesso aos endpoints HTTP personalizados, esses endpoints devem aceitar solicitações e enviar respostas usando determinados formatos de solicitação e resposta do Kinesis Data Firehose. Esta seção descreve as especificações de formato das solicitações HTTP que o serviço Kinesis Data Firehose envia para endpoints HTTP personalizados, bem como as especificações de formato das respostas HTTP que o serviço Kinesis Data Firehose espera. Os endpoints HTTP têm 3 minutos para responder a uma solicitação antes que o Kinesis Data Firehose atinja o tempo limite da solicitação. O Kinesis Data Firehose trata as respostas que não seguem o formato adequado como falhas de entrega.

Formato de solicitação

Parâmetros de caminho e URL

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

nota

Atualmente, somente a porta 443 é compatível com a entrega de dados de endpoint HTTP.

Cabeçalhos HTTP: X-Amz-Firehose-Protocol-Version

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

Cabeçalhos HTTP: X-Amz-Firehose-Request-Id

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 bem-sucedidas quanto malsucedidas. O ID da solicitação é mantido entre as várias tentativas da mesma solicitação.

Cabeçalhos HTTP: Content-Type

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

Cabeçalhos HTTP: Content-Encoding

Um fluxo de entrega do Kinesis Data 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.

Cabeçalhos HTTP: Content-Length

Isso é usado da maneira padrão.

Cabeçalhos HTTP: X-Amz-Firehose-Source-Arn:

O ARN do fluxo de entrega do Kinesis Data 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.

Cabeçalhos HTTP: X-Amz-Firehose-Access-Key

Esse cabeçalho carrega uma chave de API ou outras credenciais. Você pode criar ou atualizar a chave de API (também conhecida como token de autorização) ao criar ou atualizar o fluxo de entrega. O Kinesis Data Firehose restringe o tamanho da chave de acesso a 4.096 bytes. O Kinesis 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 Kinesis Data Firehose não modifica e/ou codifica o valor configurado e usa o conteúdo sem alterações.

Cabeçalhos HTTP - X-Amz-Firehose-Common-Attributes

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 de entrega. 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": ""
  }
Corpo: tamanho máximo

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

Corpo: esquema

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 Delivery 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="
    }
  ]
}

Formato de resposta

Comportamento padrão em caso de erro

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

Código de status

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

O servidor Kinesis Data Firehose NÃO segue redirecionamentos (códigos de status 3XX). Somente o código de resposta 200 é considerado uma entrega bem-sucedida 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.

Cabeçalhos HTTP: tipo de conteúdo

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

Cabeçalhos HTTP: Content-Encoding

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

Cabeçalhos HTTP: Content-Length

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

Corpo: tamanho máximo

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
}
Lidar com respostas de erro

Em todos os casos de erro, o servidor Kinesis 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 s, (1 * (2^n)) * aleatório (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 de entrega. O serviço Kinesis 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 HTTP. Se a solicitação ainda não for entregue após o tempo máximo permitido (com base na configuração do fluxo de entrega), o lote de registros poderá, opcionalmente, ser entregue a um repositório de erros de acordo com a configuração do fluxo.

Exemplos

Exemplo de uma solicitação originada do 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"
        }
      ]
    }
   }
  ]
}