Noções básicas das especificações de solicitação e resposta de entrega de endpoint de HTTP - Amazon Data Firehose
Formato de solicitaçãoFormato de respostaExemplos

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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

Para que o Amazon Data Firehose entregue dados com êxito aos endpoints de HTTP personalizados, esses endpoints devem aceitar solicitações e enviar respostas usando determinados formatos de solicitação e resposta do Amazon Data Firehose. Esta seção descreve as especificações de formato das solicitações HTTP que o serviço Amazon Data Firehose envia para endpoints de HTTP personalizados, bem como as especificações de formato das respostas HTTP que o serviço Amazon Data Firehose espera. Os endpoints de HTTP têm 3 minutos para responder a uma solicitação antes que o Amazon Data Firehose atinja o tempo limite da solicitação. O Amazon 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 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.

nota

Atualmente, somente a porta 443 oferece suporte à entrega de dados de endpoint de HTTP.

Cabeçalhos HTTP - Versão X-Amz-Firehose-Protocol

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 com êxito ou não. 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 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.

Cabeçalhos HTTP: Content-Length

Isso é usado da maneira padrão.

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

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

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

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.

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

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

Formato de resposta

Comportamento padrão em caso de erro

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.

Código de status

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.

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 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 recuadas usando um tempo de recuo inicial (1 segundo) com um fator de instabilidade de (15%) e cada nova tentativa subsequente é recuada usando a fórmula (initial-backoff-time * (multiplicador (2) ^ retry_count)) com variação adicional. 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.

Exemplos

Exemplo de uma solicitação CWLog originada.


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