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

# 使用 NDJSON 端點傳送日誌 (ND-JSON 日誌）
<a name="CWL_HTTP_Endpoints_NDJSON"></a>

ND-JSON Logs 端點 (`/ingest/bulk`) 接受 [NDJSON （換行分隔 JSON) 格式的](https://github.com/ndjson/ndjson-spec)日誌。每一行只包含一個 JSON 值，以換行字元分隔。

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

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

每行傳送一個 JSON 值，以 `\n`(LF) 或 `\r\n`(CRLF) 分隔。空白行會被無提示地忽略。

```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```

`application/json` 和 都`application/x-ndjson`被接受為 Content-Type。

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

根據 NDJSON 規格 (RFC 8259)，每行接受任何有效的 JSON 值。

**JSON 物件 （最常見）：**

```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```

**JSON 陣列 （扁平化為個別事件）：**

```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```

此單行會產生 2 個事件。每個陣列元素都會成為個別的日誌事件。

**基本值：**

```
"a plain string log message"
42
true
null
```

每個基本會成為具有伺服器目前時間戳記的專屬事件。

**混合類型：**

```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```

所有 4 行都被接受為有效事件。


| 行內容 | Behavior (行為) | 
| --- | --- | 
| JSON 物件 | 已接受，如果有的話擷取時間戳記 | 
| JSON 陣列 | 平面化 – 每個元素都會成為個別的事件 | 
| 空陣列 [] | 已接受，會產生 0 個事件 | 
| JSON 字串 | 接受為事件訊息 | 
| JSON 號碼 | 接受為事件訊息 | 
| JSON 布林值 | 接受為事件訊息 | 
| JSON null | 接受為事件訊息 | 
| 無效的 JSON | 已略過 （已計算，處理會繼續） | 
| 空行 | 已忽略 （未計為略過） | 

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

`"timestamp"` 欄位以 epoch 毫秒 （非秒） 為單位。


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

## 無效的行
<a name="CWL_NDJSON_Invalid_Lines"></a>

非有效 JSON 的行會無提示地略過並計數。處理會繼續進行下一行。

```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```

結果：擷取 2 個事件，略過 1 個事件。傳回 `HTTP 200`。

如果所有行都無效， 會傳回 `HTTP 400`與 `"All events were invalid"`。

## 範例請求
<a name="CWL_NDJSON_Example"></a>

```
curl -X POST "https://logs.<region>.amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -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"}'
```

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

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

```
HTTP 200 OK
{}
```

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

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

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

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

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

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

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