Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Envío de registros mediante el punto final NDJSON (registros ND-JSON)
El punto final de registros de ND-JSON (`/ingest/bulk`) acepta registros en formato [NDJSON](https://github.com/ndjson/ndjson-spec) (JSON delimitado por nueva línea). Cada línea contiene exactamente un valor JSON, separado por caracteres de nueva línea.
Si utiliza la autenticación mediante token de portador, complete los pasos de configuración [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Formato de las solicitudes
Envía un valor JSON por línea, separado por `\n` (LF) o `\r\n` (CRLF). Las líneas vacías se ignoran silenciosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Ambas `application/json` `application/x-ndjson` se aceptan como tipo de contenido.
## Tipos de valores JSON aceptados
Según la especificación NDJSON (RFC 8259), se acepta cualquier valor JSON válido en cada línea.
**Objetos JSON (los más comunes):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrices JSON (agrupadas en eventos individuales):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Esta única línea produce 2 eventos. Cada elemento de la matriz se convierte en un evento de registro independiente.
**Valores primitivos:**
```
"a plain string log message"
42
true
null
```
Cada primitivo se convierte en su propio evento con la marca de tiempo actual del servidor.
**Tipos mixtos:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Las 4 líneas se aceptan como eventos válidos.
| Contenido de la línea | Comportamiento |
| --- | --- |
| Objeto JSON | Aceptado, se extrae la marca de tiempo si está presente |
| matriz JSON | Aplanado: cada elemento se convierte en un evento independiente |
| Matriz vacía [] | Aceptado, produce 0 eventos |
| Cadena JSON | Aceptado como mensaje de evento |
| Número JSON | Aceptado como mensaje de evento |
| Booleano JSON | Aceptado como mensaje de evento |
| JSON nulo | Aceptado como mensaje de evento |
| JSON no válido | Omitido (contado, el procesamiento continúa) |
| Línea vacía | Ignorada (no se cuenta como omitida) |
## Campo de fecha y hora
El `"timestamp"` campo está expresado en milisegundos de época (no segundos).
| Formato | Ejemplo | Interpretado como |
| --- | --- | --- |
| Numérico (milis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sin campo de marca de tiempo) | Hora actual del servidor |
| No numérico | "timestamp":"invalid" | Hora actual del servidor |
| Línea que no es de objetos | "hello", 42, true | Hora actual del servidor |
## Líneas no válidas
Las líneas que no son JSON válidas se omiten y se cuentan de forma silenciosa. El procesamiento continúa con la siguiente línea.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Resultado: 2 eventos ingeridos y 1 omitido. Devuelve `HTTP 200`.
Si todas las líneas no son válidas, devuelve `HTTP 400` con. `"All events were invalid"`
## Ejemplo de solicitud
```
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"}'
```
## Respuestas
**Éxito (se aceptan todos los eventos):**
```
HTTP 200 OK
{}
```
**Éxito parcial (algunos eventos rechazados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
El `rejectedLogRecords` campo es el número total de eventos rechazados. El `errorMessage` campo contiene un desglose codificado en JSON por motivo de rechazo:
+ `tooOldLogEventCount`— Eventos con marcas de tiempo anteriores al período de retención
+ `tooNewLogEventCount`— Eventos con marcas de tiempo demasiado lejanas en el futuro
+ `expiredLogEventCount`— Eventos que caducaron durante el procesamiento
## Prácticas recomendadas
### Agrupación de eventos por lotes
Para un mejor rendimiento y eficiencia:
+ Batch varios eventos en una sola solicitud cuando sea posible
+ Tamaño de lote recomendado: de 10 a 100 eventos por solicitud
+ Tamaño máximo de la solicitud: 1 MB
### Gestión de errores
Implemente una gestión de errores adecuada en su aplicación. Códigos de estado HTTP comunes:
+ `200 OK`— Los registros se ingirieron correctamente
+ `400 Bad Request`— Formato o parámetros de solicitud no válidos
+ `401 Unauthorized`— Token de portador no válido o caducado
+ `403 Forbidden`— Permisos insuficientes
+ `404 Not Found`— El grupo de registros o la transmisión no existen
+ `429 Too Many Requests`— Se ha superado el límite de velocidad
+ `500 Internal Server Error`— Error de servicio (reintento con un retraso exponencial)
## Limitaciones
+ Tamaño máximo del evento: 256 KB por evento
+ Tamaño máximo de solicitud: 1 MB
+ Número máximo de eventos por solicitud: 10 000
+ Los nombres de los grupos de registros deben seguir las convenciones CloudWatch de nomenclatura de los registros
+ La autenticación por token de portador debe estar habilitada en el grupo de registros si se utiliza la autenticación por token de portador.