本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用結構化 JSON 端點傳送日誌 （結構化 JSON 日誌）
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

結構化 JSON Logs 端點 (`/ingest/json`) 接受標準 JSON – 單一 JSON 物件或物件的 JSON 陣列。此端點專為結構式日誌資料而設計，其中每個事件都是 JSON 物件。

如果您使用承載字符身分驗證，請先完成 中的設定步驟，[設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)再繼續。

## 要求格式
<a name="CWL_StructuredJSON_Format"></a>

僅`application/json`接受 做為 Content-Type。

**單一 JSON 物件：**

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

**物件的 JSON 陣列：**

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

## 接受的 JSON 值類型
<a name="CWL_StructuredJSON_Accepted_Types"></a>

此端點很嚴格 – 僅接受 JSON 物件做為事件。


| Input | Behavior (行為) | 
| --- | --- | 
| 單一 JSON 物件 | 接受為一個事件 | 
| 物件的 JSON 陣列 | 每個物件都會成為個別的事件 | 
| 空陣列 [] | 已接受，會產生 0 個事件 | 
| 陣列中的非物件 （字串、數字等） | 略過 | 
| 最上層基本 ("hello"、42) | 略過 | 
| 串連物件 \$1...\$1\$1...\$1 | 僅剖析第一個物件 | 

**範例 – 混合類型的陣列：**

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

結果：擷取 2 個事件 （物件）、略過 2 個事件 （字串和數字）。

## 時間戳記欄位
<a name="CWL_StructuredJSON_Timestamp"></a>

`"timestamp"` 欄位以 epoch 毫秒為單位，與 NDJSON 端點相同。


| 格式 | 範例 | 解譯為 | 
| --- | --- | --- | 
| 數值 （毫秒） | "timestamp":1771007942000 | 1771007942000 毫秒 | 
| 缺少 | （無時間戳記欄位） | 伺服器目前時間 | 
| 非數值 | "timestamp":"invalid" | 伺服器目前時間 | 

## 範例請求
<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"}]'
```

## 回應
<a name="CWL_StructuredJSON_Responses"></a>

**成功 （接受所有事件）：**

```
HTTP 200 OK
{}
```

**部分成功 （部分事件遭到拒絕）：**

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

`rejectedLogRecords` 欄位是已拒絕事件的總數。`errorMessage` 欄位包含依拒絕原因分類的 JSON 編碼明細：
+ `tooOldLogEventCount` – 時間戳記早於保留期間的事件
+ `tooNewLogEventCount` – 未來時間戳記太久的事件
+ `expiredLogEventCount` – 處理期間過期的事件

## 最佳實務
<a name="CWL_StructuredJSON_Best_Practices"></a>

### 批次處理事件
<a name="CWL_StructuredJSON_Batching"></a>

為了獲得更好的效能和效率：
+ 盡可能在單一請求中批次處理多個事件
+ 建議的批次大小：每個請求 10–100 個事件
+ 請求大小上限：1 MB

### 錯誤處理
<a name="CWL_StructuredJSON_Error_Handling"></a>

在應用程式中實作適當的錯誤處理。常見的 HTTP 狀態碼：
+ `200 OK` – 日誌已成功擷取
+ `400 Bad Request` – 無效的請求格式或參數
+ `401 Unauthorized` – 承載字符無效或過期
+ `403 Forbidden` – 許可不足
+ `404 Not Found` – 日誌群組或串流不存在
+ `429 Too Many Requests` – 超過速率限制
+ `500 Internal Server Error` – 服務錯誤 （以指數退避重試）

## 限制
<a name="CWL_StructuredJSON_Limitations"></a>
+ 事件大小上限：每個事件 256 KB
+ 請求大小上限：1 MB
+ 每個請求的事件上限：10，000
+ 日誌群組名稱必須遵循 CloudWatch Logs 命名慣例
+ 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。