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

# 使用非同步任務 (API) 尋找 PII 實體
<a name="async-pii-api"></a>

執行非同步批次任務，在文件集合中尋找 PII。若要執行任務，請將文件上傳至 Amazon S3，然後提交 [StartPiiEntitiesDetectionJob](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 位置。 Amazon Comprehend 
+ `DataAccessRoleArn` – 提供 AWS Identity and Access Management 角色的 Amazon Resource Name (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，以便您可以監控任務的進度，並在任務完成時擷取任務狀態。

若要監控分析任務的進度，請將任務 ID 提供給 [DescribePiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribePiiEntitiesDetectionJob.html) 操作。的回應`DescribePiiEntitiesDetectionJob`包含目前狀態為任務`JobStatus`的欄位。成功的任務會轉換到下列狀態：

已提交 -> IN\_PROGRESS -> 已完成。

分析任務完成後 (`JobStatus` 已完成、失敗或已停止），請使用 `DescribePiiEntitiesDetectionJob`取得結果的位置。如果任務狀態為 `COMPLETED`，回應會包含 `OutputDataConfig` 欄位，其中包含具有輸出檔案 Amazon S3 位置的欄位。

如需 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>

下列範例使用 `StartPiiEntitiesDetectionJob`操作搭配 AWS CLI。

此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 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)
    }
}
```