翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 非同期ジョブによる PII エンティティの検索 (API)
<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 の場所を指定します。
+ `DataAccessRoleArn` – AWS Identity and Access Management ロールの Amazon リソースネーム (ARN) を指定します。このロールは、Amazon Comprehend 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 エンティティを検出した分析ジョブからの出力ファイル例です。入力の形式は、行ごとにドキュメント 1 つです。

```
{
  "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
 }
```

以下は、入力の形式がファイルごとにドキュメント 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 の場合は、各行末のバックスラッシュ (\\) 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)
    }
}
```