非同期ジョブによる PII エンティティの検索 (API)

PDF

RSS

フォーカスモード

非同期ジョブによる PII エンティティの検索 (API) - Amazon Comprehend

開始する前に入力パラメータ非同期ジョブメソッド出力ファイル形式を使用した非同期分析 AWS Command Line Interface

非同期バッチジョブを実行して、文書の集団から PII を検索します。ジョブを実行するには、Amazon S3 に文書をアップロードし、StartPIIEntitiesDetectionJob リクエストを送信します。

トピック

開始する前に
入力パラメータ
非同期ジョブメソッド
出力ファイル形式
を使用した非同期分析 AWS Command Line Interface

開始する前に

始める前に、次の有無を確認します。

入出力バケット — 入力ファイルと出力ファイルに使用する Amazon S3 バケットを識別します。バケットは、呼び出す API と同じリージョンに存在している必要があります。
IAM サービスロール — 入出力バケットにアクセス許可を持つ IAM サービスロールが必要です。詳細については、「バッチ操作に必要なロールベースのアクセス許可」を参照してください。

入力パラメータ

リクエストには次のパラメータを含めます。

InputDataConfig — リクエストにジョブの入力プロパティを含む InputDataConfig 定義を示します。S3Uri パラメータには、入力文書の Amazon S3 の場所を指定します。
OutputDataConfig — リクエストにジョブの入力プロパティを含む OutputDataConfig 定義を示します。S3Uriパラメータには、Amazon Comprehend が分析結果を書き込む Amazon S3 の場所を指定します。
DataAccessRoleArn – AWS Identity and Access Management ロールの Amazon リソースネーム (ARN) を指定します。このロールは、Amazon Comprehend S3 内の入力データに対する読み取りアクセス権と出力場所への書き込みアクセス権を付与します。詳細については、「バッチ操作に必要なロールベースのアクセス許可」を参照してください。
Mode — このパラメータを ONLY_OFFSETS に設定します。この設定では、入力テキスト内の各 PII エンティティを特定する文字オフセットが出力されます。出力には信頼度スコアと PII エンティティタイプも含まれます。
LanguageCode – このパラメータを enまたはに設定しますes。Amazon Comprehend は、英語またはスペイン語のテキストでの PII 検出をサポートしています。

非同期ジョブメソッド

StartPiiEntitiesDetectionJob はジョブ ID を返すので、ジョブの進行状況を監視し、完了時にジョブのステータスを取得できます。

分析ジョブの進行状況を監視するには、DescribePIIEntitiesDetectionJob 演算にジョブ ID を指定します。DescribePiiEntitiesDetectionJob からの応答には、ジョブの現在のステータスを示す JobStatus フィールドが含まれます。正常なジョブの進展は次のようになります。

[送信] -> [進行中] -> [完了]。

分析ジョブが終了したなら (JobStatus が完了、失敗、または停止)、DescribePiiEntitiesDetectionJob を使用して結果の場所を取得します。ジョブのステータスが COMPLETED の場合、応答には出力ファイルの Amazon S3 の場所を示すフィールドを含む OutputDataConfig フィールドが含まれます。

Amazon Comprehend 非同期分析の手順の詳細については、「非同期バッチ処理」を参照してください。

出力ファイル形式

出力ファイルでは、入力ファイルの名前と末尾に .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

次の例では、 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 演算を使用して、既存のジョブのステータスを取得できます。イベント検出ジョブの開始リクエストが成功すると、以下のような応答が表示されます。


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)
    }
}