Amazon Comprehend のインサイトのための非同期分析 - Amazon Comprehend
前提条件分析の開始分析ジョブのモニタリング分析結果の取得

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

Amazon Comprehend のインサイトのための非同期分析

以下のセクションでは、Amazon Comprehend API を使用して非同期オペレーションを実行し、Amazon Comprehend のインサイトを分析します。

前提条件

ドキュメントは、UTF-8 形式のテキストファイルである必要があります。ドキュメントは 2 つの形式で送信できます。次の表に示すように、使用する形式は分析する文書のタイプによって異なります。

説明 形式
各ファイルには 1 つの入力ドキュメントを含めます。これはサイズの大きいドキュメントのコレクションに最適です。 ファイルごとに 1 文書

入力は 1 つまたは複数のファイルです。ファイル内の各行は 1 つのドキュメントとみなされます。これは、ソーシャルメディアへの投稿など、短いドキュメントに最適です。

各行は、改行 (LF、\ n)、キャリッジリターン (CR、\r)、またはその両方 (CRLF、\r\n) で終える必要があります。行の終了に、UTF-8 の行区切り文字 (u+2028) を使用することはできません。

 1 行に 1 文書

分析ジョブを開始するときは、入力データの S3 上の場所を指定します。URI は、呼び出す API エンドポイントと同じ AWS リージョンである必要があります。URI は 1 つのファイルを指すものでも、データファイルのコレクションのプレフィックスでもかまいません。詳細については、「InputDataConfig」データ型を参照してください。

Amazon Comprehend には、ドキュメントコレクションと出力ファイルを含む Amazon S3 バケットへのアクセス許可を付与する必要があります。詳細については、「バッチ操作に必要なロールベースのアクセス許可」を参照してください。

分析の開始

分析ジョブを送信するには、Amazon Comprehend コンソールまたは適切な Start* オペレーションを使用します。

  • StartDominantLanguageDetectionJob — コレクション内の各ドキュメントの主要な言語を検出するジョブを開始します。ドキュメントの主要言語の詳細については、「主要言語」を参照してください。

  • StartEntitiesDetectionJob — コレクション内の各ドキュメント内のエンティティを検出するジョブを開始します。エンティティの詳細については、「エンティティ」を参照してください。

  • StartKeyPhrasesDetectionJob — コレクション内の各ドキュメント内のキーフレーズを検出するジョブを開始します。キーフレーズの詳細については、「キーフレーズ」を参照してください。

  • StartPiiEntitiesDetectionJob — コレクション内の各ドキュメント内の個人を特定できる情報 (PII) を検出するジョブを開始します。PII の詳細については、「PII エンティティの検出」を参照してください。

  • StartSentimentDetectionJob — コレクション内の各ドキュメント内の感情を検出するジョブを開始します。詳細については、「感情」を参照してください。

分析ジョブのモニタリング

Start* オペレーションでは、ジョブの進行状況の監視に利用できる ID が返されす。

この API を使用して進行状況を監視するには、個別ジョブの進行状況を監視するのか、複数のジョブの進行状況を監視するのかに応じて、2 つあるオペレーションのいずれかを使用します。

個別分析ジョブの進行状況を監視するには、Describe* オペレーションを使用します。Start* オペレーションによって返されるジョブ ID を指定します。Describe* オペレーションからのレスポンスには、ジョブのステータスを示す JobStatus フィールドが含まれます。

複数の分析ジョブの進行状況を監視するには、List* オペレーションを使用します。 List* オペレーションでは、Amazon Comprehend に送信したジョブのリストが返されます。レスポンスには、ジョブごとにそのステータスを示す JobStatus フィールドが含まれます。

ステータスフィールドが COMPLETED または FAILED に設定されている場合、そのジョブの処理は完了しています。

個別ジョブのステータスを取得するには、実行する分析で Describe* オペレーションを使用します。

複数のジョブのステータスを取得するには、実行する分析で List* オペレーションを使用します。

結果を特定の条件に一致するジョブに制限するには、List* オペレーションの Filter パラメータを使用します。フィルタ条件には、ジョブ名やジョブステータス、またはジョブの送信日時を使用できます。詳細については、Amazon Comprehend API リファレンスの各 List* オペレーションの Filter パラメータを参照してください。

分析結果の取得

分析ジョブが終了すると、Describe* オペレーションを使用して結果の場所を取得します。ジョブのステータスが COMPLETED の場合、応答には出力ファイルの Amazon S3 の場所を示すフィールドを含む OutputDataConfig フィールドが含まれます。このファイル output.tar.gz は、分析の結果を含む圧縮アーカイブ形式です。

ジョブのステータスが FAILED の場合、 レスポンスには、ジョブが正常に完了しなかった理由を説明する Message フィールドが含まれます。

個別ジョブのステータスを取得するには、適切な Describe* オペレーションを使用します。

結果はドキュメントごとに 1 つの JSON 構造を持つ 1 つのファイルの形式で返されます。各レスポンスファイルには、ステータスフィールドが FAILED に設定されているジョブのエラーメッセージも含まれます。

以下の各セクションでは、2 つの入力形式の出力例を示しています。

主要言語の検出結果の取得

次に、主要言語を検出した分析からの出力ファイルの例を示します。入力の形式は、行ごとにドキュメント 1 つです。詳細については、DetectDominantLanguage オペレーションを参照してください。

{"File": "0_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9514502286911011}, {"LanguageCode": "de", "Score": 0.02374090999364853}, {"LanguageCode": "nl", "Score": 0.003208699868991971}, "Line": 0}
{"File": "1_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9822712540626526}, {"LanguageCode": "de", "Score": 0.002621392020955682}, {"LanguageCode": "es", "Score": 0.002386554144322872}], "Line": 1}

以下は、入力の形式がファイルごとにドキュメント 1 つの場合の分析の出力例です。

{"File": "small_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9728053212165833}, {"LanguageCode": "de", "Score": 0.007670710328966379}, {"LanguageCode": "es", "Score": 0.0028472368139773607}]}
{"File": "huge_doc", "Languages": [{"LanguageCode": "en", "Score": 0.984955906867981}, {"LanguageCode": "de", "Score": 0.0026436643674969673}, {"LanguageCode": "fr", "Score": 0.0014206881169229746}]}

エンティティ検出結果の取得

以下は、ドキュメント内のエンティティを検出した分析からの出力ファイル例です。入力の形式は、行ごとにドキュメント 1 つです。詳細については、DetectEntities オペレーションを参照してください。出力には 2 つのエラーメッセージが含まれています。1 つはドキュメントが長すぎる、もう 1 つはドキュメントが UTF-8 形式ではないというエラーです。

{"File": "50_docs", "Line": 0, "Entities": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.9763959646224976, "Text": "Cluj-NapocaCluj-Napoca", "Type": "LOCATION"}"]}
{"File": "50_docs", "Line": 1, "Entities": [{"BeginOffset": 11, "EndOffset": 15, "Score": 0.9615424871444702, "Text": "Maat", "Type": "PERSON"}}]}
{"File": "50_docs", "Line": 2, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds maximum size limit 102400 bytes."}
{"File": "50_docs", "Line": 3, "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent lines are ignored."}

以下は、入力の形式がファイルごとにドキュメント 1 つの場合の分析の出力例です。出力には 2 つのエラーメッセージが含まれています。1 つはドキュメントが長すぎる、もう 1 つはドキュメントが UTF-8 形式ではないというエラーです。

{"File": "non_utf8.txt", "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent line are ignored."}
{"File": "small_doc", "Entities": [{"BeginOffset": 0, "EndOffset": 4, "Score": 0.645766019821167, "Text": "Maat", "Type": "PERSON"}]}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds size limit 102400 bytes."}

キーフレーズ検出結果の取得

以下は、ドキュメント内のエンティティを検出した分析からの出力ファイル例です。入力の形式は、行ごとにドキュメント 1 つです。詳細については、DetectKeyPhrases オペレーションを参照してください。

{"File": "50_docs", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}], "Line": 0}

以下は、入力の形式がファイルごとにドキュメント 1 つの場合の分析の出力例です。

{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}

個人を特定できる情報 (PII) 検出結果の取得

以下は、ドキュメント内の 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"}

センチメント検出結果の取得

以下は、ドキュメントで表されているセンチメントを検出した分析からの出力ファイル例です。1 つのドキュメントが長すぎるというエラーメッセージが含まれています。入力の形式は、行ごとにドキュメント 1 つです。詳細については、DetectSentiment オペレーションを参照してください。

{"File": "50_docs", "Line": 0, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.002734508365392685, "Negative": 0.008935936726629734, "Neutral": 0.9841893315315247, "Positive": 0.004140198230743408}}
{"File": "50_docs", "Line": 1, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeded maximum size limit 5120 bytes."}
{"File": "50_docs", "Line": 2, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023119584657251835, "Negative": 0.0029857370536774397, "Neutral": 0.9866572022438049, "Positive": 0.008045154623687267}}

以下は、入力の形式がファイルごとにドキュメント 1 つの場合の分析の出力例です。

{"File": "small_doc", "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023450672160834074, "Negative": 0.0009663937962614, "Neutral": 0.9795311689376831, "Positive": 0.017157377675175667}}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeds the limit of 5120 bytes."}