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