As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Envio de registros usando o endpoint JSON estruturado (Structured JSON Logs)
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

O endpoint (`/ingest/json`) do Structured JSON Logs aceita JSON padrão — um único objeto JSON ou uma matriz JSON de objetos. Esse endpoint foi projetado para dados de log estruturados em que cada evento é um objeto JSON.

Se você estiver usando a autenticação do token do portador, conclua as etapas de configuração [Configurando a autenticação do token do portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.

## Formato de solicitação
<a name="CWL_StructuredJSON_Format"></a>

Só `application/json` é aceito como o tipo de conteúdo.

**Objeto JSON único:**

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

**Matriz JSON de objetos:**

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

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

Esse endpoint é estrito — somente objetos JSON são aceitos como eventos.


| Input | Comportamento | 
| --- | --- | 
| Objeto JSON único | Aceito como um evento | 
| Matriz JSON de objetos | Cada objeto se torna um evento separado | 
| Matriz vazia [] | Aceito, produz 0 eventos | 
| Não objeto na matriz (string, número, etc.) | Ignorado | 
| Primitivo de nível superior ("hello",) 42 | Ignorado | 
| Objetos concatenados \$1...\$1\$1...\$1 | Somente o primeiro objeto analisado | 

**Exemplo — matriz com tipos mistos:**

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

Resultado: 2 eventos ingeridos (os objetos), 2 ignorados (a string e o número).

## Campo de carimbo de data/hora
<a name="CWL_StructuredJSON_Timestamp"></a>

O `"timestamp"` campo está em milissegundos de época, o mesmo que o endpoint NDJSON.


| Formato | Exemplo | Interpretada como | 
| --- | --- | --- | 
| Numérico (millis) | "timestamp":1771007942000 | 1771007942000 ms | 
| Missing (Ausente) | (sem campo de carimbo de data/hora) | Hora atual do servidor | 
| Não numérico | "timestamp":"invalid" | Hora atual do servidor | 

## Exemplo de solicitação
<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"}]'
```

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

**Sucesso (todos os eventos são aceitos):**

```
HTTP 200 OK
{}
```

**Sucesso parcial (alguns eventos foram rejeitados):**

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

O `rejectedLogRecords` campo é o número total de eventos rejeitados. O `errorMessage` campo contém um detalhamento codificado em JSON por motivo de rejeição:
+ `tooOldLogEventCount`— Eventos com carimbos de data/hora anteriores ao período de retenção
+ `tooNewLogEventCount`— Eventos com timestamps muito distantes no futuro
+ `expiredLogEventCount`— Eventos que expiraram durante o processamento

## Práticas recomendadas
<a name="CWL_StructuredJSON_Best_Practices"></a>

### eventos em lotes
<a name="CWL_StructuredJSON_Batching"></a>

Para melhor desempenho e eficiência:
+ Agrupe vários eventos em uma única solicitação, quando possível
+ Tamanho de lote recomendado: 10 a 100 eventos por solicitação
+ Tamanho máximo da solicitação: 1 MB

### Tratamento de erros
<a name="CWL_StructuredJSON_Error_Handling"></a>

Implemente o tratamento adequado de erros em seu aplicativo. Códigos de status HTTP comuns:
+ `200 OK`— Registros ingeridos com sucesso
+ `400 Bad Request`— Formato ou parâmetros de solicitação inválidos
+ `401 Unauthorized`— Token de portador inválido ou expirado
+ `403 Forbidden`— Permissões insuficientes
+ `404 Not Found`— O grupo de log ou stream não existe
+ `429 Too Many Requests`— Limite de taxa excedido
+ `500 Internal Server Error`— Erro de serviço (tente novamente com recuo exponencial)

## Limitações
<a name="CWL_StructuredJSON_Limitations"></a>
+ Tamanho máximo do evento: 256 KB por evento
+ Tamanho máximo da solicitação: 1 MB
+ Máximo de eventos por solicitação: 10.000
+ Os nomes dos grupos de registros devem seguir as convenções de nomenclatura de CloudWatch registros
+ A autenticação do token do portador deve ser ativada no grupo de registros se a autenticação do token do portador for usada.