翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Textract 非同期オペレーションを呼び出す
Amazon Textract は、PDF または TIFF 形式で複数ページのドキュメントを処理するために使用できる非同期 API を提供します。非同期操作を使用して、JPEG、PNG、TIFF、または PDF 形式の単一ページのドキュメントを処理することもできます。
このトピックの情報は、テキスト検出操作を使用して Amazon Textract の非同期オペレーションの使用方法を示しています。同じアプローチが、のテキスト解析操作でも機能します。[StartDocumentAnalysis](API_StartDocumentAnalysis.md)そして[GetDocumentAnalysis](API_GetDocumentAnalysis.md)。また、で動作します。[StartExpenseAnalysis](API_StartExpenseAnalysis.md)そして[GetExpenseAnalysis](API_GetExpenseAnalysis.md)。
例については、[複数ページドキュメント内のテキストの検出または分析](async-analyzing-with-sqs.md) を参照してください。
Amazon Textract は、Amazon S3 バケットに保存されたドキュメントを非同期的に処理します。処理を開始するには、`Start`などの操作[StartDocumentTextDetection](API_StartDocumentTextDetection.md)。リクエストの完了ステータスが、Amazon Simple Notification Service (Amazon SNS) トピックに発行されます。Amazon SNS トピックから完了ステータスを取得するには、Amazon Simple Queue Service (Amazon SQS) キューまたはAWS Lambdafunction. 完了ステータスを取得したら、[GetDocumentTextDetection](API_GetDocumentTextDetection.md) などの `Get` オペレーションを呼び出してリクエストの結果を取得します。
非同期呼び出しの結果は、オペレーションを使用して Amazon S3 バケットを指定しない限り、デフォルトで暗号化され、Amazon Textract が所有するバケットに 7 日間保存されます。`OutputConfig`引数。
次の表に、Amazon Textract でサポートされているさまざまなタイプの非同期処理に対応する開始オペレーションと Get オペレーションを示します。
**Amazon Textract 非同期オペレーションの API オペレーションの開始/取得**
| 処理タイプ | API を起動する | API の取得 |
| --- | --- | --- |
| テキストの検出 | StartDocumentTextDetection | GetDocumentTextDetection |
| テキスト分析 | StartDocumentAnalysis | GetDocumentAnalysis |
| 経費分析 | 経費分析の開始 | 経費分析を取得 |
という例を挙げてAWS Lambda関数、「」を参照してください。[Amazon Textract による大規模なドキュメント処理](https://github.com/aws-samples/amazon-textract-serverless-large-scale-document-processing)。
以下の図は、Amazon S3 バケットに保存されているドキュメントイメージ内のドキュメントテキストを検出するプロセスを示しています。この図では、Amazon SQS キューによって Amazon SNS トピックから完了ステータスが表示されます。
![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/textract/latest/dg/images/asynchronous.png)
前の図に表示されるプロセスは、テキストおよび請求書/領収書の分析と同じです。テキスト分析を開始するには、を呼び出します。[StartDocumentAnalysis](API_StartDocumentAnalysis.md)そして、電話をかけて請求書/領収書の分析を開始する[StartExpenseAnalysis](API_StartExpenseAnalysis.md)あなたは呼び出すことによって結果を得ます[GetDocumentAnalysis](API_GetDocumentAnalysis.md)または[GetExpenseAnalysis](API_GetExpenseAnalysis.md)それぞれ。
## テキストの検出の開始
Amazon Textract テキストリクエストを開始するには、を呼び出します。[StartDocumentTextDetection](API_StartDocumentTextDetection.md)。以下は、`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 バケットを提供します。`NotificationChannel`には、Amazon SNS トピックの Amazon リソースネーム (ARN) と、テキスト検出リクエストの完了時に Amazon Textract が通知します。Amazon SNS トピックは、呼び出し先の Amazon Textract エンドポイントと同じ AWS リージョン内に存在する必要があります。`NotificationChannel`には、Amazon Textract を Amazon SNS トピックに発行できるようにするためのロールの ARN も含まれています。Amazon SNS トピックへの Amazon Textract 発行アクセス許可を付与するには、IAM サービスロールを作成します。詳細については、「[非同期オペレーション用の Amazon Textract の設定](api-async-roles.md)」を参照してください。
オプションの入力パラメータを指定することもできます。`JobTag`を選択すると、Amazon SNS トピックに発行された完了ステータスのジョブまたはジョブのグループを特定できます。たとえば、を使用すると、`JobTag`税金フォームや領収書など、処理中の文書のタイプを識別します。
`ClientRequestToken` というべき等トークンをオプションで設定すると、分析ジョブが誤って重複するのを防ぐことができます。の値を指定した場合`ClientRequestToken`とすると、`Start`オペレーションが同じを返す`JobId`への複数の同一のコールに対して`Start`などの操作`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 は、AWS マネージドキーAmazon S3 におけるもの
**注記**
このパラメータを使用する前に、出力バケットの PutObject 権限があることを確認してください。さらに、の [復号化]、[ReEncrypt]、[generateDataKey]、および [describeKey] 権限があることを確認します。AWS KMS使用することに決めた場合はキーを指定します。
`StartDocumentTextDetection` オペレーションに対する応答は、ジョブ識別子 (`JobId`) です。を使用する`JobId`Amazon Textract が完了ステータスを Amazon SNS トピックに発行したら、リクエストを追跡し、分析結果を取得します。次に例を示します。
```
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
```
同時に開始するジョブが多すぎると、`StartDocumentTextDetection`を育てる`LimitExceededException`同時に実行されるジョブの数が Amazon Textract のサービスの制限を下回るまで、の例外 (HTTP ステータスコード:400)。
アクティビティのバーストにより LimitExceedededException 例外が発生した場合は、Amazon SQS キューを使用して受信リクエストを管理することを検討してください。連絡先AWS同時リクエストの平均数を Amazon SQS キューで管理できないと、引き続き受信されている場合のSupport`LimitExceededException`例外。
## Amazon Textract 分析リクエストの完了ステータスの取得
Amazon Textract は、登録されている Amazon SNS トピックに分析完了の通知を送信します。通知には、ジョブ識別子およびオペレーション完了ステータスが JSON 文字列で含まれています。成功したテキスト検出リクエストには、`SUCCEEDED`status。たとえば、次の結果は、テキスト検出ジョブが正常に処理されたことを示しています。
```
{
"JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f",
"Status": "SUCCEEDED",
"API": "StartDocumentTextDetection",
"JobTag": "Receipt",
"Timestamp": 1543599965969,
"DocumentLocation": {
"S3ObjectName": "document",
"S3Bucket": "bucket"
}
}
```
詳細については、「[Amazon Textract 結果通知](async-notification-payload.md)」を参照してください。
Amazon Textract によって Amazon SNS トピックに発行されたステータス情報を取得するには、次のいずれかのオプションを使用します。
+ **AWS Lambda**— をサブスクライブできますAWS LambdaAmazon SNS トピックに書き込む関数。この関数は、Amazon Textract が Amazon SNS トピックにリクエスト完了を通知したときに呼び出されます。Lambda 関数を使用すると、サーバー側のコードでテキスト検出リクエストの結果を処理できます。たとえば、クライアントアプリケーションに情報を返す前に、イメージに注釈を付けたり、検出されたテキストに関するレポートを作成したりする場合があります。
+ **Amazon SQS**— Amazon SNS トピックに Amazon SQS キューをサブスクライブできます。Amazon SQS キューをポーリングすることで、リクエストの完了時に Amazon Textract が発行する完了ステータスを取得できます。詳細については、「[複数ページドキュメント内のテキストの検出または分析](async-analyzing-with-sqs.md)」を参照してください。Amazon Textract オペレーションをクライアントアプリケーションからのみ呼び出す場合は、Amazon SQS キューを使用します。
**重要**
Amazon Textract を繰り返し呼び出すことでリクエスト完了ステータスを取得することは推奨されません。`Get`オペレーション. これは、Amazon Textract が`Get`実行されるリクエストが多すぎると、操作が実行されます。複数のドキュメントを同時に処理する場合は、Amazon Textract をポーリングして各ジョブのステータスを個別に取得するよりも、1 つの SQS キューの完了通知を監視するほうがシンプルかつ効率的です。
## Amazon Textract テキスト検出結果の取得
テキスト検出リクエストの結果を取得するには、Amazon SNS トピックから取得された完了ステータスがであることを最初に確認します。`SUCCEEDED`。次に `GetDocumentTextDetection` を呼び出し、`StartDocumentTextDetection` から返された `JobId` の値を渡します。リクエストの JSON は次の例のようになります。
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
"MaxResults": 10,
"SortBy": "TIMESTAMP"
}
```
`JobId`テキスト検出操作の識別子です。テキスト検出によって大量のデータが生成されるため、`MaxResults`は、1 件で返す結果の最大数を指定します。`Get`オペレーション. のデフォルト値`MaxResults`は1,000です。1,000 より大きい値を指定した場合、1,000 件の結果だけが返されます。オペレーションによってすべての結果が返されない場合、次のページのページ分割トークンが返されます。次の結果ページを取得するには、`NextToken`パラメータ。
**注記**
Amazon Textract は非同期オペレーションの結果を 7 日間保持します。この時間を過ぎると結果を取得することはできません。
-`GetDocumentTextDetection`オペレーションの応答の JSON は次のようになります。検出されたページの総数が`DocumentMetadata`。検出されたテキストは`Blocks`配列。の詳細については、`Block`オブジェクト、「」を参照してください。[テキスト検出および文書分析応答オブジェクト](how-it-works-document-layout.md)。
```
{
"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
}
]
}
```