非同期バッチ処理

大規模なドキュメントと大量のドキュメントのコレクションを分析するには、Amazon Comprehend の非同期オペレーションのいずれかを使用します。Amazon Comprehend の各オペレーションの非同期バージョンと、トピックモデリング用の追加のオペレーションセットがあります。

ドキュメントのコレクションを分析するには、通常、以下の手順を実行します。

1. Amazon S3 バケットにドキュメントを保存します。

2. 1 つ以上のジョブを開始して、ドキュメントを分析します。

3. 分析ジョブの進行状況をモニタリングします。

4. ジョブの完了時に S3 バケットから分析の結果を取得します。

以下のセクションでは、Amazon Comprehend API を使用して非同期オペレーションを実行する方法について説明します。

Prerequisites

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

説明	形式
各ファイルには 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 バケットへのアクセス権を付与する必要があります。詳細については、「非同期操作に必要なロールベースのアクセス許可」を参照してください。

分析Job 開始

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

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

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

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

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

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

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

• StartTopicsDetectionJob-ドキュメントコレクション内のトピックを検出するジョブを開始します。トピックモデリングの詳細については、「」を参照してください。トピックモデリング。

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

-Start*operation は、ジョブの進行状況をモニタリングするために使用できる ID を返します。

API を使用して進行状況を監視するには、個々のジョブの進行状況を監視するか、複数のジョブの進行状況を監視するかに応じて、2 つの操作のいずれかを使用します。

個々の解析ジョブの進行状況をモニタリングするには、Describe*オペレーション. によって返されたジョブ ID を指定します。Start*オペレーション. からのレスポンスは次のとおりです。Describe*オペレーションにはJobStatusフィールドにジョブのステータスが表示されます。

複数の解析ジョブの進行状況をモニタリングするには、List*オペレーション.List*オペレーションは、Amazon Comprehend に送信したジョブのリストを返します。レスポンスに次のものが含まれている。JobStatusジョブのステータスを示す各ジョブのフィールド。

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

個々のジョブのステータスを取得するには、Describe*実行している解析の操作。

• DescribeDominantLanguageDetectionJob

• DescribeEntitiesDetectionJob

• DescribeEventsDetectionJob

• DescribeKeyPhrasesDetectionJob

• DescribePiiEntitiesDetectionJob

• DescribeSentimentDetectionJob

• DescribeTopicsDetectionJob

複数のジョブのステータスを取得するには、List*実行している解析の操作。

• ListDominantLanguageDetectionJobs

• ListEntitiesDetectionJobs

• ListEventsDetectionJobs

• ListKeyPhrasesDetectionJobs

• ListPiiEntitiesDetectionJobs

• ListSentimentDetectionJobs

• ListTopicsDetectionJobs

結果を特定の条件に一致するジョブに制限するには、List*オペレーション 'Filterパラメータ。ジョブ名、ジョブのステータス、およびジョブが送信された日時をフィルタ処理できます。詳細については、「」を参照してください。FilterそれぞれのパラメータをList*でのオペレーションActionsリファレンス。

分析結果の取得

解析ジョブが終了したら、Describe*のオペレーションでは、結果の位置を取得します。ジョブのステータスがの場合COMPLETEDの場合、応答にはOutputDataConfig出力ファイルの Amazon S3 の場所を持つフィールドを含むフィールド。ファイル、output.tar.gzは、解析結果を含む圧縮アーカイブです。

ジョブのステータスがの場合FAILEDの場合、応答にはMessage分析ジョブが正常に完了しなかった理由を説明するフィールド。

個々のジョブのステータスを取得するには、適切なDescribe*オペレーション:

• DescribeDominantLanguageDetectionJob

• DescribeEntitiesDetectionJob

• DescribeEventsDetectionJob

• DescribeKeyPhrasesDetectionJob

• DescribeSentimentDetectionJob

• DescribeTopicsDetectionJob

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

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

主要言語検出結果の取得

以下は、主要な言語を検出した解析からの出力ファイルの例です。入力の形式は、1 行につき 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 行につき 1 つのドキュメントです。詳細については、「」を参照してください。DetectEntitiesオペレーション. 出力には 2 つのエラーメッセージが含まれています。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 つは長すぎるドキュメントと 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 行につき 1 つのドキュメントです。

{"Entities": [{"Mentions": [{"BeginOffset": 12, "EndOffset": 27, "GroupScore": 1.0, "Score": 0.916355, "Text": "over a year ago", "Type": "DATE"}]}, {"Mentions": [{"BeginOffset": 33, "EndOffset": 39, "GroupScore": 1.0, "Score": 0.996603, "Text": "Amazon", "Type": "ORGANIZATION"}]}, {"Mentions": [{"BeginOffset": 66, "EndOffset": 77, "GroupScore": 1.0, "Score": 0.999283, "Text": "Whole Foods", "Type": "ORGANIZATION"}]}], "Events": [{"Arguments": [{"EntityIndex": 2, "Role": "INVESTEE", "Score": 0.999283}, {"EntityIndex": 0, "Role": "DATE", "Score": 0.916355}, {"EntityIndex": 1, "Role": "INVESTOR", "Score": 0.996603}], "Triggers": [{"BeginOffset": 373, "EndOffset": 380, "GroupScore": 0.999984, "Score": 0.999955, "Text": "acquire", "Type": "CORPORATE_ACQUISITION"}], "Type": "CORPORATE_ACQUISITION"}, {"Arguments": [{"EntityIndex": 2, "Role": "PARTICIPANT", "Score": 0.999283}], "Triggers": [{"BeginOffset": 115, "EndOffset": 123, "GroupScore": 1.0, "Score": 0.999967, "Text": "combined", "Type": "CORPORATE_MERGER"}], "Type": "CORPORATE_MERGER"}], "File": "doc.txt", "Line": 0}

イベント出力ファイル構造とサポートされているイベントタイプの詳細については、「」を参照してください。イベントを検出する。

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

次に、文書内のキーフレーズを検出した分析の出力ファイルの例を示します。入力の形式は、1 行につき 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 行につき 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 行につき 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."}             

トピックモデリング結果の取得

トピックモデリング解析では、output.tar.gzファイルを開きます。詳細については、トピックモデリングを参照してください。