Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Senden von Protokollen mithilfe des strukturierten JSON-Endpunkts (Strukturierte JSON-Protokolle)
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

Der Endpunkt Structured JSON Logs (`/ingest/json`) akzeptiert Standard-JSON — entweder ein einzelnes JSON-Objekt oder ein JSON-Array von Objekten. Dieser Endpunkt ist für strukturierte Protokolldaten konzipiert, bei denen jedes Ereignis ein JSON-Objekt ist.

Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md) bevor Sie fortfahren.

## Anforderungsformat
<a name="CWL_StructuredJSON_Format"></a>

`application/json`Wird nur als Content-Type akzeptiert.

**Einzelnes JSON-Objekt:**

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

**JSON-Array von Objekten:**

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

## Akzeptierte JSON-Werttypen
<a name="CWL_StructuredJSON_Accepted_Types"></a>

Dieser Endpunkt ist streng — nur JSON-Objekte werden als Ereignisse akzeptiert.


| Input | Behavior | 
| --- | --- | 
| Einzelnes JSON-Objekt | Als ein Ereignis akzeptiert | 
| JSON-Array von Objekten | Jedes Objekt wird zu einem separaten Ereignis | 
| Leeres Array [] | Akzeptiert, erzeugt 0 Ereignisse | 
| Kein Objekt im Array (Zeichenfolge, Zahl usw.) | Übersprungen | 
| Primitiv der obersten Ebene ("hello",) 42 | Übersprungen | 
| Verkettete Objekte \$1...\$1\$1...\$1 | Nur das erste Objekt wurde analysiert | 

**Beispiel — Array mit gemischten Typen:**

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

Ergebnis: 2 Ereignisse wurden aufgenommen (die Objekte), 2 übersprungen (die Zeichenfolge und die Zahl).

## Feld „Zeitstempel“
<a name="CWL_StructuredJSON_Timestamp"></a>

Das `"timestamp"` Feld wird in Epochen-Millisekunden angegeben, genau wie der NDJSON-Endpunkt.


| Format | Beispiel | Interpretiert als | 
| --- | --- | --- | 
| Numerisch (Millis) | "timestamp":1771007942000 | 1771007942000 ms | 
| Fehlen | (kein Zeitstempelfeld) | Aktuelle Uhrzeit des Servers | 
| Nicht numerisch | "timestamp":"invalid" | Aktuelle Uhrzeit des Servers | 

## Beispielanforderung
<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"}]'
```

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

**Erfolgreich (alle Ereignisse wurden akzeptiert):**

```
HTTP 200 OK
{}
```

**Teilweise erfolgreich (einige Ereignisse wurden abgelehnt):**

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

Das `rejectedLogRecords` Feld gibt die Gesamtzahl der abgelehnten Ereignisse an. Das `errorMessage` Feld enthält eine JSON-kodierte Aufschlüsselung nach Ablehnungsgründen:
+ `tooOldLogEventCount`— Ereignisse, deren Zeitstempel älter als der Aufbewahrungszeitraum sind
+ `tooNewLogEventCount`— Ereignisse mit Zeitstempeln, die zu weit in der future liegen
+ `expiredLogEventCount`— Ereignisse, die während der Verarbeitung abgelaufen sind

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

### Ereignisse werden gebündelt
<a name="CWL_StructuredJSON_Batching"></a>

Für mehr Leistung und Effizienz:
+ Wenn möglich, mehrere Ereignisse in einer einzigen Anfrage bündeln
+ Empfohlene Batchgröße: 10—100 Ereignisse pro Anfrage
+ Maximale Anforderungsgröße: 1 MB

### Fehlerbehandlung
<a name="CWL_StructuredJSON_Error_Handling"></a>

Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung. Allgemeine HTTP-Statuscodes:
+ `200 OK`— Protokolle wurden erfolgreich aufgenommen
+ `400 Bad Request`— Ungültiges Anforderungsformat oder ungültige Parameter
+ `401 Unauthorized`— Ungültiges oder abgelaufenes Trägertoken
+ `403 Forbidden`— Unzureichende Berechtigungen
+ `404 Not Found`— Protokollgruppe oder Stream existiert nicht
+ `429 Too Many Requests`— Ratenlimit überschritten
+ `500 Internal Server Error`— Servicefehler (erneuter Versuch mit exponentiellem Backoff)

## Einschränkungen
<a name="CWL_StructuredJSON_Limitations"></a>
+ Maximale Ereignisgröße: 256 KB pro Ereignis
+ Maximale Anforderungsgröße: 1 MB
+ Maximale Anzahl von Ereignissen pro Anfrage: 10.000
+ Die Namen der Protokollgruppen müssen den Benennungskonventionen für CloudWatch Protokolle entsprechen
+ Wenn die Bearer-Token-Authentifizierung verwendet wird, muss die Bearer-Token-Authentifizierung für die Protokollgruppe aktiviert sein.