翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
Amazon Textract 非同期オペレーションの呼び出し
Amazon Textract には、複数ページのドキュメントを PDF または TIFF 形式で処理するために使用できる非同期 API が用意されています。非同期オペレーションを使用して、JPEG、PNG、TIFF、または PDF 形式の単一ページのドキュメントを処理することもできます。
このトピックの情報は、テキスト検出オペレーションを使用して、Amazon Textract の非同期オペレーションの使用方法を示します。StartDocumentAnalysis および GetDocumentAnalysis のテキスト分析オペレーションでも同じアプローチを使用できます。また、StartExpenseAnalysis と GetExpenseAnalysis でも同じように機能します。
例については、マルチページドキュメント内のテキストの検出または分析を参照してください。
融資ドキュメントを分析する場合は、 StartLendingAnalysisオペレーションを使用してドキュメントページを分類し、分類されたページを Amazon Textract 分析オペレーションに送信できます。ページは、割り当てられたクラスに応じて分析オペレーションにルーティングされます。
GetLendingAnalysis オペレーションを使用して個々のページの結果を取得するか、 で分析の概要を取得できますGetLendingAnalysisSummary。
Amazon Textract は、Amazon S3 バケットに保存されているドキュメントを非同期的に処理します。処理を開始するには、StartDocumentTextDetection などの Startオペレーションを呼び出します。リクエストの完了ステータスは、Amazon Simple Notification Service (Amazon SNS) トピックに発行されます。Amazon SNS トピックから完了ステータスを取得するには、Amazon Simple Queue Service (Amazon SQS) キューまたは AWS Lambda 関数を使用できます。完了ステータスになったら、GetDocumentTextDetection などのGetオペレーションを呼び出して、リクエストの結果を取得します。
非同期呼び出しの結果は、オペレーションの OutputConfig引数を使用して Amazon S3 バケットを指定しない限り、デフォルトで暗号化され、Amazon Textract 所有のバケットに 7 日間保存されます。Amazon Textract が暗号化されたドキュメントを Amazon S3 バケットに送信できるようにする方法については、「」を参照してください出力設定のアクセス許可。
次の表は、Amazon Textract でサポートされているさまざまなタイプの非同期処理に対応する開始オペレーションと取得オペレーションを示しています。
| 処理タイプ | API の開始 | API を取得する |
|---|---|---|
| テキストの検出 | StartDocumentTextDetection | GetDocumentTextDetection |
| テキスト分析 | StartDocumentAnalysis | GetDocumentAnalysis |
| 経費分析 | StartExpenseAnalysis | GetExpenseAnalysis |
| 融資分析 | StartLendingAnalysis | GetLendingAnalysis、GetLendingAnalysisSummary |
AWS Lambda 関数を使用する例については、「Amazon Textract を使用した大規模なドキュメント処理
次の図は、Amazon S3 バケットに保存されているドキュメントイメージ内のドキュメントテキストを検出するプロセスを示しています。この図では、Amazon SQS キューが Amazon SNS トピックから完了ステータスを取得しています。
前の図に表示されるプロセスは、テキストと請求書/領収書を分析する場合と同じです。StartDocumentAnalysis を呼び出してテキストの分析を開始し、StartExpenseAnalysis を呼び出して請求書/領収書の分析を開始します。それぞれ GetDocumentAnalysis または GetExpenseAnalysis を呼び出して結果を取得します。
テキスト検出の開始
Amazon Textract テキスト検出リクエストを開始するには、StartDocumentTextDetection を呼び出します。以下は、StartDocumentTextDetection により渡される JSON リクエストの例を示しています。
{ "DocumentLocation": { "S3Object": { "Bucket": "bucket", "Name": "image.pdf" } }, "ClientRequestToken": "DocumentDetectionToken", "NotificationChannel": { "SNSTopicArn": "arn:aws:sns:us-east-1:nnnnnnnnnn:topic", "RoleArn": "arn:aws:iam::nnnnnnnnnn:role/roleTopic" }, "JobTag": "Receipt" }
入力パラメータDocumentLocationは、ドキュメントファイル名とそれを取得する Amazon S3 バケットを提供します。 には、Amazon Textract がテキスト検出リクエストの完了時に通知する Amazon SNS トピックの Amazon リソースネーム (ARN) NotificationChannelが含まれています。Amazon SNS トピックは、呼び出す Amazon Textract エンドポイントと同じ AWS リージョンに存在する必要があります。 には、Amazon Textract が Amazon SNS トピックに発行することを許可するロールの ARN NotificationChannelも含まれています。IAM サービスロールを作成して、Amazon Textract に Amazon SNS トピックへの発行アクセス許可を付与します。詳細については、「非同期オペレーション用の Amazon Textract の設定」を参照してください。
Amazon SNS トピックに発行される完了ステータスでジョブまたはジョブのグループを識別JobTagできるオプションの入力パラメータ を指定することもできます。たとえば、 JobTagを使用して、納税申告書や領収書など、処理されるドキュメントのタイプを特定できます。
ClientRequestToken というべき等トークンをオプションで設定すると、分析ジョブが誤って重複するのを防ぐことができます。に値を指定するとClientRequestToken、Startオペレーションは、 などのStartオペレーションへの複数の同一の呼び出しJobIdに対して同じ を返しますStartDocumentTextDetection。ClientRequestToken トークンの有効期間は 7 日です。7 日後に再利用することができます。トークンの有効期間中にトークンを再利用すると、以下のことが発生します。
-
同じ
Startオペレーション、同じ入力パラメータでトークンを再利用すると、同じJobIdが返されます。ジョブは再度実行されず、Amazon Textract は登録された Amazon SNS トピックに完了ステータスを送信しません。 -
同じ
Startオペレーションで、入力パラメータを少し変更してトークンを再利用すると、idempotentparametermismatchexception(HTTP ステータスコード: 400) 例外を受け取ります。 -
別の
Startオペレーションでトークンを再利用すると、オペレーションは正常に実行されます。
使用可能なもう 1 つのオプションのパラメータは です。これによりOutputConfig、出力の配置場所を調整できます。デフォルトでは、Amazon Textract は結果を内部に保存し、Get API オペレーションでのみアクセスできます。OutputConfig を有効にすると、出力の送信先となるバケットの名前と結果のファイルプレフィックスを設定し、結果をダウンロードできます。さらに、 KMSKeyIDパラメータをカスタマーマネージドキーに設定して、出力を暗号化できます。このパラメータセットがない場合、Amazon Textract は for Amazon S3 を使用してサーバー側を暗号化 AWS マネージドキー します。
注記
このパラメータを使用する前に、出力バケットの PutObject アクセス許可があることを確認してください。さらに、キーを使用する場合は、その AWS KMS キーの Decrypt、ReEncrypt、GenerateDataKey、および DescribeKey アクセス許可があることを確認してください。
StartDocumentTextDetection オペレーションに対する応答は、ジョブ識別子 (JobId) です。Amazon Textract が完了ステータスを Amazon SNS トピックに発行した後、 JobIdを使用してリクエストを追跡し、分析結果を取得します。以下に例を示します。
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
同時に開始するジョブが多すぎる場合、同時に実行されるジョブの数が Amazon Textract サービスの制限を下回るまで、 を呼び出してLimitExceededException例外 (HTTP ステータスコード: 400) StartDocumentTextDetectionを発生させます。
LimitExceededException 例外がアクティビティのバーストで発生する場合は、Amazon SQS キューを使用して受信リクエストを管理することを検討してください。同時リクエストの平均数が Amazon SQS キューで管理できず、まだLimitExceededException例外が発生している場合は、 サポートにお問い合わせください AWS 。
Amazon Textract 分析リクエストの完了ステータスの取得
Amazon Textract は、登録された Amazon SNS トピックに分析完了通知を送信します。通知には、ジョブ識別子およびオペレーション完了ステータスが JSON 文字列で含まれています。成功したテキスト検出リクエストのステータスは ですSUCCEEDED。たとえば、次の結果は、テキスト検出ジョブの処理が成功したことを示しています。
{ "JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f", "Status": "SUCCEEDED", "API": "StartDocumentTextDetection", "JobTag": "Receipt", "Timestamp": 1543599965969, "DocumentLocation": { "S3ObjectName": "document", "S3Bucket": "bucket" } }
詳細については、「Amazon Textract 結果通知」を参照してください。
Amazon Textract によって Amazon SNS トピックに発行されるステータス情報を取得するには、次のいずれかのオプションを使用します。
-
AWS Lambda – Amazon SNS トピックに書き込む AWS Lambda 関数をサブスクライブできます。関数は、リクエストが完了したことを Amazon Textract が Amazon SNS トピックに通知すると呼び出されます。サーバー側のコードでテキスト検出リクエストの結果を処理する場合は、Lambda 関数を使用します。たとえば、クライアントアプリケーションに情報を返す前に、サーバー側のコードを使用してイメージに注釈を付けたり、検出されたテキストのレポートを作成したりできます。
-
Amazon SQS – Amazon SQS キューを Amazon SNS トピックにサブスクライブできます。次に、Amazon SQS キューをポーリングして、テキスト検出リクエストが完了したときに Amazon Textract によって発行された完了ステータスを取得します。詳細については、「マルチページドキュメント内のテキストの検出または分析」を参照してください。クライアントアプリケーションからのみ Amazon Textract オペレーションを呼び出す場合は、Amazon SQS キューを使用します。
重要
Amazon Textract Getオペレーションを繰り返し呼び出して、リクエストの完了ステータスを取得することはお勧めしません。これは、リクエストが多すぎると Amazon Textract がGetオペレーションをスロットリングするためです。複数のドキュメントを同時に処理する場合、各ジョブのステータスを個別にポーリングするよりも、完了通知のために 1 つの SQS キューをモニタリングする方が簡単で効率的です。
Amazon Simple Notification Service (Amazon SNS) トピックまたは Amazon SQS キューから結果通知を受信するようにアカウントを設定している場合は、Amazon Textract のアクセス範囲を使用中のリソースのみに制限することで、アカウントの安全性を確保する必要があります。これは、IAM サービスロールに信頼ポリシーをアタッチすることで実行できます。これを行う方法については、「サービス間の混乱した代理の防止」を参照してください。
Amazon Textract テキスト検出結果の取得
テキスト検出リクエストの結果を取得するには、まず Amazon SNS トピックから取得した完了ステータスが であることを確認しますSUCCEEDED。次に GetDocumentTextDetection を呼び出し、StartDocumentTextDetection から返された JobId の値を渡します。リクエストの JSON は次の例のようになります。
{ "JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3", "MaxResults": 10, "SortBy": "TIMESTAMP" }
JobId は、テキスト検出オペレーションの識別子です。テキスト検出は大量のデータを生成する可能性があるため、 MaxResults を使用して、1 回のGetオペレーションで返す結果の最大数を指定します。のデフォルト値は 1,000 MaxResultsです。1,000 を超える値を指定すると、1,000 の結果のみが返されます。オペレーションがすべての結果を返さない場合、次のページのページ分割トークンが返されます。結果の次のページを取得するには、 NextTokenパラメータでトークンを指定します。
注記
結果は、ジョブの初期化から最大 7 日間しか取得できません。
GetDocumentTextDetection オペレーションレスポンス JSON は次のようになります。検出されたページの合計数は、 で返されますDocumentMetadata。検出されたテキストがBlocks配列で返されます。Block オブジェクトの詳細については、「」を参照してくださいテキスト検出およびドキュメント分析レスポンスオブジェクト。
{ "DocumentMetadata": { "Pages": 1 }, "JobStatus": "SUCCEEDED", "Blocks": [ { "BlockType": "PAGE", "Geometry": { "BoundingBox": { "Width": 1.0, "Height": 1.0, "Left": 0.0, "Top": 0.0 }, "Polygon": [ { "X": 0.0, "Y": 0.0 }, { "X": 1.0, "Y": 0.0 }, { "X": 1.0, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "64533157-c47e-401a-930e-7ca1bb3ac3fa", "Relationships": [ { "Type": "CHILD", "Ids": [ "4297834d-dcb1-413b-8908-3b96866ebbb5", "1d85ba24-2877-4d09-b8b2-393833d769e9", "193e9c47-fd87-475a-ba09-3fda210d8784", "bd8aeb62-961b-4b47-b78a-e4ed9eeecd0f" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 53.301639556884766, "Text": "ellooworio", "Geometry": { "BoundingBox": { "Width": 0.9999999403953552, "Height": 0.5365243554115295, "Left": 0.0, "Top": 0.46347561478614807 }, "Polygon": [ { "X": 0.0, "Y": 0.46347561478614807 }, { "X": 0.9999999403953552, "Y": 0.46347561478614807 }, { "X": 0.9999999403953552, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "4297834d-dcb1-413b-8908-3b96866ebbb5", "Relationships": [ { "Type": "CHILD", "Ids": [ "170c3eb9-5155-4bec-8c44-173bba537e70" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 89.15632629394531, "Text": "He llo,", "Geometry": { "BoundingBox": { "Width": 0.33642634749412537, "Height": 0.49159330129623413, "Left": 0.13885067403316498, "Top": 0.17169663310050964 }, "Polygon": [ { "X": 0.13885067403316498, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.6632899641990662 }, { "X": 0.13885067403316498, "Y": 0.6632899641990662 } ] }, "Id": "1d85ba24-2877-4d09-b8b2-393833d769e9", "Relationships": [ { "Type": "CHILD", "Ids": [ "516ae823-3bab-4f9a-9d74-ad7150d128ab", "6bcf4ea8-bbe8-4686-91be-b98dd63bc6a6" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 82.44834899902344, "Text": "worlo", "Geometry": { "BoundingBox": { "Width": 0.33182239532470703, "Height": 0.3766750991344452, "Left": 0.5091826915740967, "Top": 0.23131252825260162 }, "Polygon": [ { "X": 0.5091826915740967, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.607987642288208 }, { "X": 0.5091826915740967, "Y": 0.607987642288208 } ] }, "Id": "193e9c47-fd87-475a-ba09-3fda210d8784", "Relationships": [ { "Type": "CHILD", "Ids": [ "ed135c3b-35dd-4085-8f00-26aedab0125f" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 88.50325775146484, "Text": "world", "Geometry": { "BoundingBox": { "Width": 0.35004907846450806, "Height": 0.19635874032974243, "Left": 0.527581512928009, "Top": 0.30100569128990173 }, "Polygon": [ { "X": 0.527581512928009, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.49736443161964417 }, { "X": 0.527581512928009, "Y": 0.49736443161964417 } ] }, "Id": "bd8aeb62-961b-4b47-b78a-e4ed9eeecd0f", "Relationships": [ { "Type": "CHILD", "Ids": [ "9e28834d-798e-4a62-8862-a837dfd895a6" ] } ], "Page": 1 }, { "BlockType": "WORD", "Confidence": 53.301639556884766, "Text": "ellooworio", "Geometry": { "BoundingBox": { "Width": 1.0, "Height": 0.5365243554115295, "Left": 0.0, "Top": 0.46347561478614807 }, "Polygon": [ { "X": 0.0, "Y": 0.46347561478614807 }, { "X": 1.0, "Y": 0.46347561478614807 }, { "X": 1.0, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "170c3eb9-5155-4bec-8c44-173bba537e70", "Page": 1 }, { "BlockType": "WORD", "Confidence": 88.46246337890625, "Text": "He", "Geometry": { "BoundingBox": { "Width": 0.15350718796253204, "Height": 0.29955607652664185, "Left": 0.13885067403316498, "Top": 0.21856294572353363 }, "Polygon": [ { "X": 0.13885067403316498, "Y": 0.21856294572353363 }, { "X": 0.292357861995697, "Y": 0.21856294572353363 }, { "X": 0.292357861995697, "Y": 0.5181190371513367 }, { "X": 0.13885067403316498, "Y": 0.5181190371513367 } ] }, "Id": "516ae823-3bab-4f9a-9d74-ad7150d128ab", "Page": 1 }, { "BlockType": "WORD", "Confidence": 89.8501968383789, "Text": "llo,", "Geometry": { "BoundingBox": { "Width": 0.17724157869815826, "Height": 0.49159327149391174, "Left": 0.2980354428291321, "Top": 0.17169663310050964 }, "Polygon": [ { "X": 0.2980354428291321, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.6632899045944214 }, { "X": 0.2980354428291321, "Y": 0.6632899045944214 } ] }, "Id": "6bcf4ea8-bbe8-4686-91be-b98dd63bc6a6", "Page": 1 }, { "BlockType": "WORD", "Confidence": 82.44834899902344, "Text": "worlo", "Geometry": { "BoundingBox": { "Width": 0.33182239532470703, "Height": 0.3766750991344452, "Left": 0.5091826915740967, "Top": 0.23131252825260162 }, "Polygon": [ { "X": 0.5091826915740967, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.607987642288208 }, { "X": 0.5091826915740967, "Y": 0.607987642288208 } ] }, "Id": "ed135c3b-35dd-4085-8f00-26aedab0125f", "Page": 1 }, { "BlockType": "WORD", "Confidence": 88.50325775146484, "Text": "world", "Geometry": { "BoundingBox": { "Width": 0.35004907846450806, "Height": 0.19635874032974243, "Left": 0.527581512928009, "Top": 0.30100569128990173 }, "Polygon": [ { "X": 0.527581512928009, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.49736443161964417 }, { "X": 0.527581512928009, "Y": 0.49736443161964417 } ] }, "Id": "9e28834d-798e-4a62-8862-a837dfd895a6", "Page": 1 } ] }
アダプターの使用
Amazon Textract では、StartDocumentAnalysis オペレーションを呼び出すときにアダプターを使用できます。アダプターを使用するには、まず Amazon Textract コンソールを使用してアダプターを作成してトレーニングする必要があります。アダプターを適用するには、StartDocumentAnalysis API オペレーションを呼び出すときにその ID を指定します。StartDocumentAnalysis オペレーションを呼び出すときは、ページごとに最大 1 つのアダプターを使用できます。
"AdaptersConfig": { "Adapters": [ { "AdapterId": "2e9bf1c4aa31", "Version": "1", "Pages": [ "1" ] } ] }
