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

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

若要修訂文字中的 PII 實體，您可以啟動非同步批次任務。若要執行任務，請將文件上傳至 Amazon S3，然後提交 [StartPiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html) 請求。

**Topics**
+ [開始之前](#redact-pii-before)
+ [輸入參數](#redact-pii-api-inputs)
+ [輸出檔案格式](#redact-pii-api-outputs)
+ [使用 進行 PII 修訂 AWS Command Line Interface](#redact-pii-api-cli)

## 開始之前
<a name="redact-pii-before"></a>

開始之前，請確定您已：
+ **輸入和輸出儲存貯**體 - 識別您要用於輸入檔案和輸出檔案的 Amazon S3 儲存貯體。儲存貯體必須與您呼叫的 API 位於相同的區域。
+ **IAM 服務角色** - 您必須擁有具有存取輸入和輸出儲存貯體許可的 IAM 服務角色。如需詳細資訊，請參閱[非同步操作所需的角色型許可](security_iam_id-based-policy-examples.md#auth-role-permissions)。

## 輸入參數
<a name="redact-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_REDACTION`。透過此設定，Amazon Comprehend 會將輸入文件的副本寫入 Amazon S3 中的輸出位置。在此副本中，會修訂每個 PII 實體。
+ `RedactionConfig` – 為您的請求提供 [RedactionConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_RedactionConfig.html) 定義，其中包含修訂的組態參數。指定要修訂的 PII 類型，並指定每個 PII 實體是否以其類型名稱或您選擇的字元取代：
  + 指定要在`PiiEntityTypes`陣列中修訂的 PII 實體類型。若要修訂所有實體類型，請將陣列值設定為 `["ALL"]`。
  + 若要將每個 PII 實體取代為其類型，請將 `MaskMode` 參數設定為 `REPLACE_WITH_PII_ENTITY_TYPE`。例如，使用此設定時，PII 實體「Jane Doe」會取代為「【NAME】」。
  + 若要以您選擇的字元取代每個 PII 實體中的字元，請將 `MaskMode` 參數設定為 `MASK`，並將 `MaskCharacter` 參數設定為取代字元。僅提供單一字元。有效字元為 ！、\$1、\$1、%、&、\$1 和 @。例如，使用此設定時，PII 實體 "Jane Doe" 可以取代為 "\$1\$1\$1\$1 \$1\$1\$1"
+ `LanguageCode` – 將此參數設定為 `en`或 `es`。Amazon Comprehend 支援英文或西班牙文文字的 PII 偵測。

## 輸出檔案格式
<a name="redact-pii-api-outputs"></a>

下列範例顯示來自修訂 PII 之分析任務的輸入和輸出檔案。輸入的格式是每行一個文件。

```
{
Managing Your Accounts Primary Branch Canton John Doe Phone Number 443-573-4800 123 Main StreetBaltimore, MD 21224
Online Banking HowardBank.com  Telephone 1-877-527-2703 Bank 3301 Boston Street, Baltimore, MD 21224
```

編輯此輸入檔案的分析任務會產生下列輸出檔案。

```
{
Managing Your Accounts Primary Branch ****** ******** Phone Number ************ **********************************
Online Banking **************  Telephone ************** Bank ***************************************     
 }
```

## 使用 進行 PII 修訂 AWS Command Line Interface
<a name="redact-pii-api-cli"></a>

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

此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。

```
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_REDACTION"
    "RedactionConfig": {
        "MaskCharacter": "*",
        "MaskMode": "MASK",
        "PiiEntityTypes": ["ALL"]
    }
}
```

如果啟動事件偵測任務的請求成功，您會收到類似以下的回應：

```
{
  "JobId": "7c4fbe6e...e5b"
  "JobArn":  "arn:aws:comprehend:us-west-2:123456789012:pii-entities-detection-job/7c4fbe6e...e5b" 
  "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": "7c4fbe6e...e5b"
     "JobArn":  "arn:aws:comprehend:us-west-2:123456789012:pii-entities-detection-job/7c4fbe6e...e5b" 
     "JobName": "piiCLIredtest1",
     "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)
  }
}
```