本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用结构化 JSON 端点发送日志（结构化 JSON 日志）
结构 JSON 端点

结构化 JSON 日志端点 (`/ingest/json`) 接受标准 JSON，可以是单个 JSON 对象，也可以是对象的 JSON 数组。此端点专为结构化日志数据而设计，其中每个事件都是一个 JSON 对象。

如果您使用的是不记名令牌身份验证，请先完成中的设置步骤，[设置不记名令牌身份验证](CWL_HTTP_Endpoints_BearerTokenAuth.md)然后再继续。

## 请求格式


仅`application/json`被接受为内容类型。

**单个 JSON 对象：**

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

**JSON 对象数组：**

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

## 接受的 JSON 值类型


此端点非常严格 — 只接受 JSON 对象作为事件。


| Input | 行为 | 
| --- | --- | 
| 单个 JSON 对象 | 作为一个活动被接受 | 
| JSON 对象数组 | 每个对象都变成一个单独的事件 | 
| 空数组 [] | 已接受，生成 0 个事件 | 
| 数组中的非对象（字符串、数字等） | Skipped | 
| 顶级原语 ("hello",42) | Skipped | 
| 连接的对象 \$1...\$1\$1...\$1 | 仅解析第一个对象 | 

**示例 — 混合类型的数组：**

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

结果：提取了 2 个事件（对象），跳过 2 个事件（字符串和数字）。

## 时间戳字段


该`"timestamp"`字段以纪元毫秒为单位，与 NDJSON 端点相同。


| 格式 | 示例 | 解释为 | 
| --- | --- | --- | 
| 数字（毫秒） | "timestamp":1771007942000 | 1771007942000 ms | 
| 缺失 | （没有时间戳字段） | 服务器当前时间 | 
| 非数字 | "timestamp":"invalid" | 服务器当前时间 | 

## 示例请求


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

## 响应


**成功（接受所有活动）：**

```
HTTP 200 OK
{}
```

**部分成功（某些事件被拒绝）：**

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

该`rejectedLogRecords`字段是被拒绝的事件的总数。该`errorMessage`字段包含按拒绝原因划分的 JSON 编码细分：
+ `tooOldLogEventCount`— 时间戳早于保留期的事件
+ `tooNewLogEventCount`— 将来时间戳过远的事件
+ `expiredLogEventCount`— 在处理过程中过期的事件

## 最佳实践


### 对事件进行批处理


为了获得更好的性能和效率：
+ 尽可能在单个请求中批量处理多个事件
+ 建议的批处理大小：每个请求 10—100 个事件
+ 最大请求大小：1 MB

### 错误处理


在应用程序中实现正确的错误处理。常见的 HTTP 状态码：
+ `200 OK`— 已成功提取日志
+ `400 Bad Request`— 无效的请求格式或参数
+ `401 Unauthorized`— 不记名令牌无效或已过期
+ `403 Forbidden`— 权限不足
+ `404 Not Found`— 日志组或直播不存在
+ `429 Too Many Requests`— 超出速率限制
+ `500 Internal Server Error`— 服务错误（使用指数退避重试）

## 限制

+ 最大事件大小：每个事件 256 KB
+ 最大请求大小：1 MB
+ 每个请求的最大事件数：10,000
+ 日志组名称必须遵循 CloudWatch 日志命名约定
+ 如果使用不记名令牌身份验证，则必须在日志组上启用持有者令牌身份验证。