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

# 비동기 작업으로 PII 개체 찾기(API)
<a name="async-pii-api"></a>

비동기 일괄 작업을 실행하여 문서 모음에서 PII를 찾습니다. 이 작업을 실행하려면 Amazon S3에 문서를 업로드하고 [PII 개체 감지 작업 시작](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html) 요청을 제출하세요.

**Topics**
+ [시작하기 전에](#detect-pii-before)
+ [입력 파라미터](#async-pii-api-inputs)
+ [비동기 작업 메서드](#async-pii-api-lifecycle)
+ [출력 파일 형식](#async-pii-api-outputs)
+ [를 사용한 비동기 분석 AWS Command Line Interface](#async-pii-api-cli)

## 시작하기 전에
<a name="detect-pii-before"></a>

시작하기 전에 다음 사항을 확인해야 합니다.
+ **입력 및 출력 버킷** - 입력 파일 및 출력 파일에 사용하려는 Amazon S3 버킷을 식별합니다. 버킷은 사용자가 호출하는 API와 동일한 리전에 있어야 합니다.
+ **IAM 서비스 역할** - 입력 및 출력 버킷에 액세스하려면 권한이 있는 IAM 서비스 역할이 필요합니다. 자세한 내용은 [비동기 작업에 필요한 역할 기반 권한](security_iam_id-based-policy-examples.md#auth-role-permissions)을 참조하십시오.

## 입력 파라미터
<a name="async-pii-api-inputs"></a>

 요청 시 다음의 필수적인 파라미터를 포함시킵니다.
+ `InputDataConfig` — 요청에 [InputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html) 정의를 제공합니다. 여기에는 작업에 대한 입력 속성이 포함되어야 합니다. `S3Uri` 파라미터에서 입력 문서의 Amazon S3 위치를 지정합니다.
+ `OutputDataConfig` — 요청에 [OutputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html) 정의를 제공합니다. 여기에는 작업에 대한 입력 속성이 포함되어야 합니다. `S3Uri` 파라미터에서 Amazon Comprehend가 분석 결과를 기록하는 Amazon S3 위치를 지정하십시오.
+ `DataAccessRoleArn` - AWS Identity and Access Management 역할의 Amazon 리소스 이름(ARN)을 제공합니다. 이 역할은 Amazon Comprehend에 입력 데이터에 대한 읽기 액세스 권한과 Amazon S3 내 출력 위치에 대한 쓰기 액세스 권한을 부여해야 합니다. 자세한 내용은 [비동기 작업에 필요한 역할 기반 권한](security_iam_id-based-policy-examples.md#auth-role-permissions)을 참조하십시오.
+ `Mode` - 이 파라미터를 `ONLY_OFFSETS`로 설정합니다. 이 설정을 사용하면 출력 결과는 입력 텍스트에서 각 PII 개체를 찾는 문자 오프셋을 제공합니다. 출력 결과에는 신뢰도 점수와 PII 개체 유형도 포함됩니다.
+ `LanguageCode` -이 파라미터를 `en` 또는 로 설정합니다`es`. Amazon Comprehend는 영어 또는 스페인어 텍스트로 PII 감지를 지원합니다.

## 비동기 작업 메서드
<a name="async-pii-api-lifecycle"></a>

`StartPiiEntitiesDetectionJob`이 작업 ID를 반환함으로써 작업 진행 상황을 모니터링하고 완료 시 작업 상태를 찾아 확인할 수 있습니다.

분석 작업의 진행 상황을 모니터링하려면 [DescribePiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribePiiEntitiesDetectionJob.html) 작업에 작업 ID를 제공하십시오. `DescribePiiEntitiesDetectionJob`의 응답에는 작업의 현재 상태를 나타내는 `JobStatus` 필드가 포함되어 있습니다. 성공적인 작업은 다음 상태로 전환됩니다.

제출됨 -> 진행 중-> 완료됨 

분석 작업이 완료된 후(`JobStatus`가 완료됨, 실패함 또는 중지됨) 결과 위치를 가져오는 데 `DescribePiiEntitiesDetectionJob`을 사용합니다. 작업 상태가 `COMPLETED`인 경우 응답에는 출력 파일의 Amazon S3 위치가 있는 필드가 포함된 `OutputDataConfig` 필드가 포함됩니다.

Amazon Comprehend 비동기 분석을 위해 따라야 할 단계에 대한 추가 세부 정보는 [비동기 일괄 처리](concepts-processing-modes.md#how-async)을 참조하세요.

## 출력 파일 형식
<a name="async-pii-api-outputs"></a>

 출력 파일 이름은 입력 파일과 동일하며 끝에 .out이 추가됩니다. 이 파일에는 분석 결과가 들어 있습니다.

다음은 문서에서 PII 개체를 감지한 분석 작업의 출력 파일 예제입니다. 입력 형식은 한 줄에 한 문서입니다.

```
{
  "Entities": [
    {
      "Type": "NAME",
      "BeginOffset": 40,
      "EndOffset": 69,
      "Score": 0.999995
    },
    {
      "Type": "ADDRESS",
      "BeginOffset": 247,
      "EndOffset": 253,
      "Score": 0.998828
    },
    {
      "Type": "BANK_ACCOUNT_NUMBER",
      "BeginOffset": 406,
      "EndOffset": 411,
      "Score": 0.693283
    }
  ],
  "File": "doc.txt",
  "Line": 0
},
{
  "Entities": [
    {
      "Type": "SSN",
      "BeginOffset": 1114,
      "EndOffset": 1124,
      "Score": 0.999999
    },
    {
      "Type": "EMAIL",
      "BeginOffset": 3742,
      "EndOffset": 3775,
      "Score": 0.999993
    },
    {
      "Type": "PIN",
      "BeginOffset": 4098,
      "EndOffset": 4102,
      "Score": 0.999995
    }
  ],
  "File": "doc.txt",
  "Line": 1
 }
```

다음은 입력 형식이 파일당 문서 하나인 분석으로부터의 출력 결과의 예입니다.

```
{
  "Entities": [
    {
      "Type": "NAME",
      "BeginOffset": 40,
      "EndOffset": 69,
      "Score": 0.999995
    },
    {
      "Type": "ADDRESS",
      "BeginOffset": 247,
      "EndOffset": 253,
      "Score": 0.998828
    },
    {
      "Type": "BANK_ROUTING",
      "BeginOffset": 279,
      "EndOffset": 289,
      "Score": 0.999999
    }
  ],
  "File": "doc.txt"
}
```

## 를 사용한 비동기 분석 AWS Command Line Interface
<a name="async-pii-api-cli"></a>

다음 예제에서는 AWS CLI로 `StartPiiEntitiesDetectionJob` 작업을 사용합니다.

다음은 Unix, Linux, macOS용 형식으로 지정된 예제입니다. Windows의 경우 각 줄의 끝에 있는 백슬래시(\$1) Unix 연속 문자를 캐럿(^)으로 바꿉니다.

```
aws comprehend start-pii-entities-detection-job \
    --region region \
    --job-name job name \
    --cli-input-json file://path to JSON input file
```

`cli-input-json` 파라미터에는 다음 예시에 표시된 대로 요청 데이터가 포함된 JSON 파일의 경로를 제공해야 합니다.

```
{
  "InputDataConfig": {
      "S3Uri": "s3://input bucket/input path",
      "InputFormat": "ONE_DOC_PER_LINE"
  },
  "OutputDataConfig": {
      "S3Uri": "s3://output bucket/output path"
  },
  "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role"
  "LanguageCode": "en",
  "Mode": "ONLY_OFFSETS"     
}
```

이벤트 감지 작업을 시작하는 요청이 받아들여지면 다음과 유사한 응답을 받게 됩니다.

```
{
  "JobId": "5d2fbe6e...e2c"
  "JobArn":  "arn:aws:comprehend:us-west-2:123456789012:pii-entities-detection-job/5d2fbe6e...e2c" 
  "JobStatus": "SUBMITTED",   
}
```

[DescribeEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEventsDetectionJob.html) 작업을 사용하여 기존 작업의 상태를 얻을 수 있습니다. 이벤트 감지 작업을 시작하는 요청이 받아들여지면 다음과 유사한 응답을 받게 됩니다.

```
aws comprehend describe-pii-entities-detection-job \
    --region region \
    --job-id job ID
```

작업이 성공적으로 완료되면 다음과 비슷한 응답을 받게 됩니다.

```
{
    "PiiEntitiesDetectionJobProperties": {
  "JobId": "5d2fbe6e...e2c"
  "JobArn":  "arn:aws:comprehend:us-west-2:123456789012:pii-entities-detection-job/5d2fbe6e...e2c" 
  "JobName": "piiCLItest3",
  "JobStatus": "COMPLETED",
  "SubmitTime": "2022-05-05T14:54:06.169000-07:00",
  "EndTime": "2022-05-05T15:00:17.007000-07:00",
  "InputDataConfig": {
       (identical to the input data that you provided with the request)
    }
}
```