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 NDJSON (ND-JSON Logs)
[L'endpoint ND-JSON Logs () accetta i log in formato NDJSON (Newline Delimited JSON). `/ingest/bulk`](https://github.com/ndjson/ndjson-spec) Ogni riga contiene esattamente un valore JSON, separato da caratteri di nuova riga.
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
Invia un valore JSON per riga, separato da `\n` (LF) o `\r\n` (CRLF). Le righe vuote vengono ignorate silenziosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Entrambi i tipi `application/json` `application/x-ndjson` sono accettati come Content-Type.
## Tipi di valori JSON accettati
In base alle specifiche NDJSON (RFC 8259), qualsiasi valore JSON valido viene accettato su ogni riga.
**Oggetti JSON (i più comuni):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrici JSON (appiattite in singoli eventi):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Questa singola riga produce 2 eventi. Ogni elemento dell'array diventa un evento di registro separato.
**Valori primitivi:**
```
"a plain string log message"
42
true
null
```
Ogni primitiva diventa un evento a sé stante con il timestamp corrente del server.
**Tipi misti:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Tutte e 4 le righe sono accettate come eventi validi.
| Contenuto della riga | Comportamento |
| --- | --- |
| Oggetto JSON | Accettato, timestamp estratto se presente |
| Array JSON | Appiattito: ogni elemento diventa un evento separato |
| Matrice vuota [] | Accettato, produce 0 eventi |
| Stringa JSON | Accettato come messaggio di evento |
| Numero JSON | Accettato come messaggio di evento |
| Booleano JSON | Accettato come messaggio di evento |
| JSON nullo | Accettato come messaggio di evento |
| JSON non valido | Ignorato (conteggiato, l'elaborazione continua) |
| Riga vuota | Ignorata (non contata come ignorata) |
## Campo Timestamp
Il `"timestamp"` campo è espresso in millisecondi epocali (non secondi).
| 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 |
| Linea non oggetto | "hello", 42, true | Ora corrente del server |
## Righe non valide
Le righe che non sono JSON valide vengono ignorate e contate silenziosamente. L'elaborazione continua con la riga successiva.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Risultato: 2 eventi inseriti, 1 ignorato. Restituisce `HTTP 200`.
Se tutte le righe non sono valide, restituisce con. `HTTP 400` `"All events were invalid"`
## Richiesta di esempio
```
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"}'
```
## Risposte
**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
### Eventi di raggruppamento
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
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
+ 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.