Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Invio di log utilizzando l'endpoint JSON strutturato (Structured JSON Logs)
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

L'endpoint Structured JSON Logs (`/ingest/json`) accetta lo standard JSON: un singolo oggetto JSON o un array di oggetti JSON. Questo endpoint è progettato per dati di registro strutturati in cui ogni evento è un oggetto JSON.

Se utilizzi l'autenticazione con token al portatore, completa i passaggi di configurazione indicati prima di procedere. [Configurazione dell'autenticazione con token al portatore](CWL_HTTP_Endpoints_BearerTokenAuth.md)

## Formato della richiesta
<a name="CWL_StructuredJSON_Format"></a>

Solo `application/json` viene accettato come Content-Type.

**Oggetto JSON singolo:**

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

**Matrice di oggetti JSON:**

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

## Tipi di valori JSON accettati
<a name="CWL_StructuredJSON_Accepted_Types"></a>

Questo endpoint è rigoroso: solo gli oggetti JSON vengono accettati come eventi.


| Input | Comportamento | 
| --- | --- | 
| Oggetto JSON singolo | Accettato come evento unico | 
| Matrice di oggetti JSON | Ogni oggetto diventa un evento separato | 
| Matrice vuota [] | Accettato, produce 0 eventi | 
| Non è un oggetto nell'array (stringa, numero, ecc.) | Saltato | 
| Primitiva di primo livello (,) "hello" 42 | Saltato | 
| Oggetti concatenati \$1...\$1\$1...\$1 | Solo il primo oggetto è stato analizzato | 

**Esempio: array con tipi misti:**

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

Risultato: 2 eventi inseriti (gli oggetti), 2 ignorati (la stringa e il numero).

## Campo Timestamp
<a name="CWL_StructuredJSON_Timestamp"></a>

Il `"timestamp"` campo è espresso in millisecondi di epoca, come l'endpoint NDJSON.


| Formato | Esempio | Interpretato come | 
| --- | --- | --- | 
| Numerico (millis) | "timestamp":1771007942000 | 1771007942000 ms | 
| Mancante | (nessun campo timestamp) | Ora corrente del server | 
| Non numerico | "timestamp":"invalid" | Ora corrente del server | 

## Richiesta di esempio
<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"}]'
```

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

**Operazione riuscita (tutti gli eventi sono accettati):**

```
HTTP 200 OK
{}
```

**Successo parziale (alcuni eventi rifiutati):**

```
{
  "partialSuccess": {
    "rejectedLogRecords": 5,
    "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
  }
}
```

Il `rejectedLogRecords` campo indica il numero totale di eventi rifiutati. Il `errorMessage` campo contiene una suddivisione con codifica JSON in base al motivo del rifiuto:
+ `tooOldLogEventCount`— Eventi con timestamp precedenti al periodo di conservazione
+ `tooNewLogEventCount`— Eventi con timestamp troppo lontani nel futuro
+ `expiredLogEventCount`— Eventi scaduti durante l'elaborazione

## Best practice
<a name="CWL_StructuredJSON_Best_Practices"></a>

### Eventi di raggruppamento
<a name="CWL_StructuredJSON_Batching"></a>

Per prestazioni ed efficienza migliori:
+ Batch di più eventi in un'unica richiesta, quando possibile
+ Dimensione del batch consigliata: 10—100 eventi per richiesta
+ Dimensione massima della richiesta: 1 MB

### Gestione degli errori
<a name="CWL_StructuredJSON_Error_Handling"></a>

Implementa una corretta gestione degli errori nell'applicazione. Codici di stato HTTP comuni:
+ `200 OK`— Registri inseriti con successo
+ `400 Bad Request`— Formato o parametri di richiesta non validi
+ `401 Unauthorized`— Token al portatore non valido o scaduto
+ `403 Forbidden`— Autorizzazioni insufficienti
+ `404 Not Found`— Il gruppo o lo stream di log non esiste
+ `429 Too Many Requests`— Limite di velocità superato
+ `500 Internal Server Error`— Errore di servizio (nuovo tentativo con backoff esponenziale)

## Limitazioni
<a name="CWL_StructuredJSON_Limitations"></a>
+ Dimensione massima dell'evento: 256 KB per evento
+ Dimensione massima della richiesta: 1 MB
+ Numero massimo di eventi per richiesta: 10.000
+ I nomi dei gruppi di log devono seguire le convenzioni di denominazione CloudWatch dei log
+ L'autenticazione con token portatore deve essere abilitata nel gruppo di log se viene utilizzata l'autenticazione con token portatore.