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

# Amazon Connect Voice ID 이벤트 스키마
<a name="voiceid-event-schema"></a>

**참고**  
지원 종료 알림: 2026년 5월 20일에 Amazon Connect Voice ID에 대한 지원이 AWS 종료됩니다. 2026년 5월 20일 이후에는 Amazon Connect 콘솔에서 Voice ID에 액세스하거나, Amazon Connect 관리자 웹 사이트 또는 연락처 제어판에서 Voice ID 기능에 액세스하거나, Voice ID 리소스에 액세스할 수 없습니다. 자세한 내용은 [Amazon Connect Voice ID 지원 종료](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html) 섹션을 참조하세요.

Voice ID는 등록, 인증 또는 감시 목록의 사기범 탐지 등 모든 트랜잭션에 대해 이벤트를 생성합니다. 이벤트는 EventBridge 기본 이벤트 버스로 전송됩니다.

EventBridge를 사용하여 Voice ID 이벤트를 모니터링함으로써 감시 목록에 있는 사기범 탐지 및 Voice ID 인증 결과를 위한 분석 파이프라인을 만들 수 있습니다. 이 주제에 나와 있는 스키마를 사용하여 관련성 있는 Voice ID 이벤트를 수신 및 필터링하도록 EventBridge 규칙을 구성한 다음 Amazon Kinesis Data Firehose를 통해 이벤트를 처리하여 원하는 데이터 웨어하우스에 저장할 수 있습니다.

 예를 들어 Voice ID 분석을 거의 실시간으로 추적하고 싶은 경우 모든 `Evaluate-Session` 이벤트를 가져오고 `authenticationResult` 및 `fraudDetectionResult`를 가져올 수 있습니다.

이벤트는 [최선의 작업](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)을 기반으로 발생됩니다.

## 이벤트의 공통 필드
<a name="voiceid-event-common-fields"></a>
+ `version` - 이벤트 데이터의 버전 
+ `id` - EventBridge에서 생성한 이벤트의 고유 식별자
+ `detail-type` - 이벤트 세부 정보에 대한 식별자
+ `source` - 이벤트의 소스 항상 `aws.voiceid`입니다.
+ `account` - AWS 계정 ID.
+ `timestamp` - 이벤트가 게시된 날짜 및 시간(UTC)
+ `region` - API 호출이 수행된 AWS 리전입니다.
+ `resources` - API 호출에서 사용한 리소스
+ `detail` - 이벤트에 대한 세부 정보
  + `detail.sourceId` - Voice ID로 생성된 고유 ID로, 중복 제거에 사용할 수 있습니다.
  + `detail.action` - 호출되는 API와 유사합니다.
  + `detail.status` - 작업의 상태(성공 또는 실패)를 나타냅니다.
  + `detail.errorInfo` - Voice ID에서 지정된 작업 오류가 발생하면 입력됩니다.

다음은 발생된 이벤트의 스키마입니다.

## 세션 시작 작업
<a name="start-session"></a>

스트림 시작 시(설정 후), 스트림 종료 시, 실패 시 이벤트를 내보냅니다.

```
{...commonfields
    "detail-type": "VoiceId Start Session Action",
    "detail": {
        "sourceId": String,
        "action": "START_SESSION",
        "status": String,
        "domainId": String,
        "session": {
            "sessionId": String,
            "sessionName": String,
            "authenticationConfiguration": {
                "acceptanceThreshold":Integer
            },
            "fraudDetectionConfiguration": {
                "riskThreshold":Integer,
                "watchlistId": String
            },
            "streamingConfiguration": {
                "authenticationMinimumSpeechInSeconds": Integer
            },
            "enrollmentAudioProgress": {
                "audioAggregationStatus": String,
                "audioAggregationStartedAt": "Timestamp",
                "audioAggregationEndedAt": "Timestamp"
            },
            "authenticationAudioProgress": {
                "audioAggregationStartedAt": "Timestamp",
                "audioAggregationEndedAt": "Timestamp"
            },
            "fraudDetectionAudioProgress": {
                "audioAggregationStartedAt": "Timestamp",
                "audioAggregationEndedAt": "Timestamp"
            },
            "generatedSpeakerId": String
        },
        "errorInfo": {
            "errorMessage": String,
            "errorType": String,
            "errorCode": Integer
       }
    }
}
```

## 세션 업데이트 작업
<a name="update-session"></a>

 내부 세션 업데이트가 성공하거나 실패할 때 이벤트를 내보냅니다.

```
{...commonfields
"detail-type": "VoiceId Update Session Action",
"detail": {
    "sourceId": String,
    "action": "UPDATE_SESSION",
    "status": String,
    "domainId": String,
    "session": {
        "sessionId": String,
        "sessionName": String,
        "authenticationConfiguration": {
            "acceptanceThreshold": Integer
        },
        "fraudDetectionConfiguration": {
            "riskThreshold": Integer,
            "watchlistId": String
        },
        "streamingConfiguration": {
            "authenticationMinimumSpeechInSeconds": Integer
        },
        "generatedSpeakerId": String
    },
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```

## 세션 평가 작업
<a name="evaluate-session"></a>

세션 평가가 성공하거나 실패할 때 이벤트를 내보냅니다. 사유는 KNOWN\$1FRAUDSTER 또는 VOICE\$1SPOOFING일 수 있습니다.

```
{...commonfields
"detail-type": "VoiceId Evaluate Session Action",
"detail": {
    "sourceId": String,
    "action": "EVALUATE_SESSION",
    "status": String,
    "domainId": String,
    "session": {
        "sessionId": String,
        "sessionName": String,
        "generatedSpeakerId": String,
        "streamingStatus": String,
        "authenticationResult": {
            "authenticationResultId": String,
            "decision": String,
            "score": Integer,
            "audioAggregationStartedAt": "Timestamp",
            "audioAggregationEndedAt": "Timestamp",
            "configuration": {
                "acceptanceThreshold": Integer
            }
        },
        "fraudDetectionResult": {
            "fraudDetectionResultId": String,
            "decision": String,
            "reasons": [String],
            "audioAggregationStartedAt": "Timestamp",
            "audioAggregationEndedAt": "Timestamp",
            "configuration": {
                   "riskThreshold": Integer
            },
            "riskDetails": {
                 "knownFraudsterRisk": {
                         "generatedFraudsterId": String,
                         "riskScore": Integer,
                         "watchlistId": String
                  },
                  "voiceSpoofingRisk": {
                        "riskScore": Integer
                  } 
            }
         }
     },
     "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```

## 화자 작업
<a name="speaker"></a>

화자 옵트아웃, 화자 삭제 또는 화자 등록이 성공 또는 실패할 때 이벤트를 내보냅니다.

```
{...commonfields
"detail-type": "VoiceId Speaker Action",
"detail": {
    "sourceId": String,
    "domainID": String,
    "action": String,
    "status": String,
    "generatedSpeakerId": String,
    "data": {
        "enrollmentSource": String,
        "enrollmentSourceId": String,
        "enrollmentStatus": String
        },
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
     }
}
}
```

## 사기범 작업
<a name="fraudster"></a>

사기범이 성공적으로 등록 또는 삭제되면 이벤트를 내보냅니다.

사기범이 감시 목록에 연결되거나 연결 해제될 때는 이벤트가 전송되지 않습니다.

```
{...commonfields
"detail-type": "VoiceId Fraudster Action",
"detail": {
    "sourceId": String,
    "domainID": String,
    "action": String,
    "status": String,
    "generatedFraudsterId": String,
    "watchlistIds": [String],
    "data": {
        "registrationSource": String,
        "registrationSourceId": String,
        "registrationStatus": String
    },
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```

## EnrollBySession
<a name="enrollbysession"></a>

등록 요청이 제출되면 이 이벤트를 내보냅니다. 실제 등록이 성공하거나 실패할 때 `Speaker` 이벤트를 내보냅니다.

```
{...commonfields
"detail-type": "VoiceId Session Speaker Enrollment Action",
"detail": {
    "sourceId": String,
    "domainId": String,
    "action": "SESSION_ENROLLMENT_REQUEST",
    "status": String,
    "sessionId": String,
    "sessionName": String,
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```

## StartSpeakerEnrollmentJob
<a name="startspeakerenrollmentjob"></a>

배치 등록 요청이 제출되거나, 성공하거나, 실패할 때 이 이벤트를 내보냅니다. 개별 화자 각각의 등록 성공 또는 실패를 나타내기 위해 `Speaker` 이벤트를 내보냅니다.

```
{...commonfields
"detail-type": "VoiceID Batch Speaker Enrollment Action",
"detail": {
    "sourceId": String,
    "domainId": String,
    "action": "BATCH_ENROLLMENT_REQUEST",
    "status": String,
    "batchJobId": String,
    "data": {
        "dataAccessRoleArn": String,
        "enrollmentConfig": {
            "existingEnrollmentAction": String,
            "fraudDetectionConfig": {
            "fraudDetectionAction": String,
            "riskThreshold": Integer,
            "watchlistIds": [String],
            }
        },
        "inputDataConfig": {
            "s3Uri": String
         },
        "outputDataConfig": {
            "s3Uri": String,
            "kmsKeyId": String
        }
    },
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```

## StartFraudsterRegistrationJob
<a name="startfraudsterregistrationjob"></a>

배치 등록 요청이 제출되거나, 성공하거나, 실패할 때 이 이벤트를 내보냅니다. 개별 사기범 각각의 등록 성공 또는 실패를 나타내기 위해 `Fraudster` 이벤트를 내보냅니다.

```
{...commonfields
"detail-type": "VoiceId Batch Fraudster Registration Action",
"detail": {
    "sourceId": String,
    "domainId": String,
    "action": "BATCH_REGISTRATION_REQUEST",
    "status": String,
    "batchJobId": String,
    "data": {
        "dataAccessRoleArn": String,
        "registrationConfig": {
            "duplicateRegistrationAction": String,
            "fraudsterSimilarityThreshold": Integer,
            "watchlistIds": [String],
        }
        "inputDataConfig": {
            "s3Uri": String
        },
        "outputDataConfig": {
            "s3Uri": String,
            "kmsKeyId": String
        }
    },                                                      
    "errorInfo": {
        "errorMessage": String,
        "errorType": String,
        "errorCode": Integer
    }
}
}
```