使用結構化 JSON 端點傳送日誌 （結構化 JSON 日誌） - Amazon CloudWatch Logs
要求格式接受的 JSON 值類型時間戳記欄位範例請求回應最佳實務限制

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

使用結構化 JSON 端點傳送日誌 （結構化 JSON 日誌）

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

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

要求格式

僅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 值類型

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

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

範例 – 混合類型的陣列：

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

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

時間戳記欄位

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

格式 範例 解譯為
數值 （毫秒） "timestamp":1771007942000 1771007942000 毫秒
缺少 （無時間戳記欄位） 伺服器目前時間
非數值 "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 Logs 命名慣例

  • 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。