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á.
# Enviando registros usando o endpoint NDJSON (ND-JSON Logs)
O endpoint ND-JSON Logs (`/ingest/bulk`) aceita registros no formato [NDJSON (Newline Delimited JSON)](https://github.com/ndjson/ndjson-spec). Cada linha contém exatamente um valor JSON, separado por caracteres de nova linha.
Se você estiver usando a autenticação do token do portador, conclua as etapas de configuração [Configurando a autenticação do token do portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Formato de solicitação
Envie um valor JSON por linha, separado por `\n` (LF) ou `\r\n` (CRLF). As linhas vazias são ignoradas silenciosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Ambos `application/json` `application/x-ndjson` são aceitos como o tipo de conteúdo.
## Tipos de valores JSON aceitos
De acordo com a especificação NDJSON (RFC 8259), qualquer valor JSON válido é aceito em cada linha.
**Objetos JSON (mais comuns):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrizes JSON (agrupadas em eventos individuais):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Essa única linha produz 2 eventos. Cada elemento da matriz se torna um evento de log separado.
**Valores primitivos:**
```
"a plain string log message"
42
true
null
```
Cada primitivo se torna seu próprio evento com a data e hora atual do servidor.
**Tipos mistos:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Todas as 4 linhas são aceitas como eventos válidos.
| Conteúdo da linha | Comportamento |
| --- | --- |
| Objeto JSON | Aceito, carimbo de data/hora extraído, se presente |
| matriz JSON | Achatado — cada elemento se torna um evento separado |
| Matriz vazia [] | Aceito, produz 0 eventos |
| Cadeia de caracteres JSON | Aceito como mensagem do evento |
| Número JSON | Aceito como mensagem do evento |
| Booleano JSON | Aceito como mensagem do evento |
| JSON nulo | Aceito como mensagem do evento |
| JSON inválido | Ignorado (contado, o processamento continua) |
| Linha vazia | Ignorado (não contado como ignorado) |
## Campo de carimbo de data/hora
O `"timestamp"` campo está em milissegundos de época (não segundos).
| Formato | Exemplo | Interpretada como |
| --- | --- | --- |
| Numérico (millis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sem campo de carimbo de data/hora) | Hora atual do servidor |
| Não numérico | "timestamp":"invalid" | Hora atual do servidor |
| Linha sem objeto | "hello", 42, true | Hora atual do servidor |
## Linhas inválidas
As linhas que não são JSON válidas são ignoradas e contadas silenciosamente. O processamento continua com a próxima linha.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Resultado: 2 eventos ingeridos, 1 ignorado. Retorna `HTTP 200`.
Se todas as linhas forem inválidas, retorna `HTTP 400` com`"All events were invalid"`.
## Exemplo de solicitação
```
curl -X POST "https://logs..amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/x-ndjson" \
-d '{"timestamp":1771007942000,"message":"User logged in","level":"INFO"}
{"timestamp":1771007943000,"message":"Query took 42ms","level":"DEBUG"}
{"timestamp":1771007944000,"error":"Connection refused","level":"ERROR"}'
```
## Respostas
**Sucesso (todos os eventos são aceitos):**
```
HTTP 200 OK
{}
```
**Sucesso parcial (alguns eventos foram rejeitados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
O `rejectedLogRecords` campo é o número total de eventos rejeitados. O `errorMessage` campo contém um detalhamento codificado em JSON por motivo de rejeição:
+ `tooOldLogEventCount`— Eventos com carimbos de data/hora anteriores ao período de retenção
+ `tooNewLogEventCount`— Eventos com timestamps muito distantes no futuro
+ `expiredLogEventCount`— Eventos que expiraram durante o processamento
## Práticas recomendadas
### eventos em lotes
Para melhor desempenho e eficiência:
+ Agrupe vários eventos em uma única solicitação, quando possível
+ Tamanho de lote recomendado: 10 a 100 eventos por solicitação
+ Tamanho máximo da solicitação: 1 MB
### Tratamento de erros
Implemente o tratamento adequado de erros em seu aplicativo. Códigos de status HTTP comuns:
+ `200 OK`— Registros ingeridos com sucesso
+ `400 Bad Request`— Formato ou parâmetros de solicitação inválidos
+ `401 Unauthorized`— Token de portador inválido ou expirado
+ `403 Forbidden`— Permissões insuficientes
+ `404 Not Found`— O grupo de log ou stream não existe
+ `429 Too Many Requests`— Limite de taxa excedido
+ `500 Internal Server Error`— Erro de serviço (tente novamente com recuo exponencial)
## Limitações
+ Tamanho máximo do evento: 256 KB por evento
+ Tamanho máximo da solicitação: 1 MB
+ Máximo de eventos por solicitação: 10.000
+ Os nomes dos grupos de registros devem seguir as convenções de nomenclatura de CloudWatch registros
+ A autenticação do token do portador deve ser ativada no grupo de registros se a autenticação do token do portador for usada.