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 de Structured JSON (Structured JSON Logs)
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

El punto final de Structured JSON Logs (`/ingest/json`) acepta JSON estándar, ya sea un único objeto JSON o una matriz de objetos JSON. Este punto final está diseñado para datos de registro estructurados en los que cada evento es un objeto JSON.

Si utiliza la autenticación por 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
<a name="CWL_StructuredJSON_Format"></a>

Solo `application/json` se acepta como tipo de contenido.

**Objeto JSON único:**

```
{"timestamp":1771007942000,"message":"single event","level":"INFO"}
```

**Matriz de objetos JSON:**

```
[
  {"timestamp":1771007942000,"message":"event one","level":"INFO"},
  {"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]
```

## Tipos de valores JSON aceptados
<a name="CWL_StructuredJSON_Accepted_Types"></a>

Este punto final es estricto: solo los objetos JSON se aceptan como eventos.


| Input | Comportamiento | 
| --- | --- | 
| Objeto JSON único | Se acepta como un solo evento | 
| Matriz de objetos JSON | Cada objeto se convierte en un evento independiente | 
| Matriz vacía [] | Aceptado, produce 0 eventos | 
| No es un objeto en la matriz (cadena, número, etc.) | Omitido | 
| Primitiva de nivel superior ("hello",) 42 | Omitido | 
| Objetos concatenados \$1...\$1\$1...\$1 | Solo se analizó el primer objeto | 

**Ejemplo: matriz con tipos mixtos:**

```
[
  {"timestamp":1771007942000,"message":"valid object"},
  "just a string",
  42,
  {"timestamp":1771007943000,"message":"another valid object"}
]
```

Resultado: 2 eventos ingeridos (los objetos) y 2 omitidos (la cadena y el número).

## Campo de fecha y hora
<a name="CWL_StructuredJSON_Timestamp"></a>

El `"timestamp"` campo está expresado en milisegundos de época, igual que el punto final NDJSON.


| 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 | 

## Ejemplo de solicitud
<a name="CWL_StructuredJSON_Example"></a>

```
curl -X POST "https://logs.<region>.amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -H "Content-Type: application/json" \
  -d '[{"timestamp":1771007942000,"message":"User logged in","user_id":"u-123"},{"timestamp":1771007943000,"message":"Order placed","order_id":"o-456"}]'
```

## Respuestas
<a name="CWL_StructuredJSON_Responses"></a>

**É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
<a name="CWL_StructuredJSON_Best_Practices"></a>

### Agrupación de eventos por lotes
<a name="CWL_StructuredJSON_Batching"></a>

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
<a name="CWL_StructuredJSON_Error_Handling"></a>

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
<a name="CWL_StructuredJSON_Limitations"></a>
+ 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.