기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 구조화된 JSON 엔드포인트를 사용하여 로그 전송(구조화된 JSON 로그)
<a name="CWL_HTTP_Endpoints_StructuredJSON"></a>

구조화된 JSON 로그 엔드포인트(`/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 | 동작 | 
| --- | --- | 
| 단일 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"` 필드는 NDJSON 엔드포인트와 동일한 에포크 밀리초 단위입니다.


| 형식 | 예제 | 다음으로 해석됨 | 
| --- | --- | --- | 
| 숫자(millis) | "timestamp":1771007942000 | 1771007942000ms | 
| 누락됨 | (타임스탬프 필드 없음) | 서버 현재 시간 | 
| 숫자가 아닌 | "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\$1100개
+ 최대 요청 크기: 1MB

### 오류 처리
<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>
+ 최대 이벤트 크기: 이벤트당 256KB
+ 최대 요청 크기: 1MB
+ 요청당 최대 이벤트 수: 10,000
+ 로그 그룹 이름은 CloudWatch Logs 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.