本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
調用 Amazon Textract 異步操作
Amazon Textract 提供了一個異步 API，您可以使用它來處理 PDF 或 TIFF 格式的多頁文檔。您還可以使用異步操作來處理 JPEG、PNG、TIFF 或 PDF 格式的單頁文檔。
本主題中的信息使用文本檢測操作來展示如何使用 Amazon Textract 異步操作。同樣的方法適用於StartDocumentAnalysis和GetDocumentAnalysis。它也適用於StartExpenseAnalysis和GetExpenseAnalysis。
如需範例，請參閱 檢測或分析多頁文檔中的文本。
Amazon Textract 以非同步方式處理存放在 Amazon S3 儲存貯體中的檔案。您可以通過調用Start操作，例如StartDocumentTextDetection。請求的完成狀態將發佈至 Amazon SNS Simple Notification Service (Amazon SNS) 主題。若要自 Amazon SNS 主題取得完成狀態，您可以使用 Amazon Simple Queue Service (Amazon SQS) 排列或AWS Lambda函數。在獲得完成狀態後，可呼叫如 GetDocumentTextDetection 的 Get 操作來取得請求結果。
默認情況下，異步調用的結果 Amazon S3 被加密並存儲在 Amazon Textract 擁有的存儲桶中 7 天，除非您使用操作的OutputConfig引數。
下表顯示了 Amazon Textract 支持的不同異步處理類型的相應「開始」和「獲取」操作：
啟動/取得亞馬遜文件異步操作的API 操作 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 處理類型 | 啟動 API | 取得 API | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 文字偵測 | StartDocumentTextDetection | GetDocumentTextDetection | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 文字分析 | StartDocumentAnalysis | GetDocumentAnalysis | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 費用分析 | 起始筆分析 | 地理軟件分析 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
對於使用AWS Lambda函數，請參使用 Amazon Textract 進行大規模文檔處理
下圖顯示在 Amazon S3 儲存貯體中的檔案映像中偵測檔案的程序。在圖表內，Amazon SQS 佇列將自 Amazon SNS 主題取得完成狀態。
前面圖所顯示的流程與分析文本和發票/收據的流程相同。您可以通過調用StartDocumentAnalysis並開始分析發票/收據，方法是調用StartExpenseAnalysis您可以通過調用GetDocumentAnalysis或者GetExpenseAnalysis分別。
啟動文字偵測
透過呼叫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 儲存貯體。NotificationChannel包含 Amazon SNS 主題的 Amazon Resource Name (ARN)，Amazon Amazon Textract N) 將在文本檢測請求完成時通知。Amazon SNS 主題必須與您呼叫的 Amazon Textract 端點位於同一個 AWS 區域。NotificationChannel也包含允許 Amazon Textract 發佈到 Amazon SNS 主題的角色 ARN。透過 IAM 服務角色，您將許可提供給 Amazon SNS 主題。如需詳細資訊，請參閱 為異步操作配置 Amazon Textract。
您也可以指定可選輸入參數JobTag，可讓您找出顯示完成狀態且已發佈至 Amazon SNS 主題的任務或任務組。例如，您可以使用JobTag標識正在處理的單據類型，例如納税表或收據。
為避免分析任務發生意外的重複，您可以選擇性地提供等冪符記 ClientRequestToken。如果您提供ClientRequestToken，Start操作會傳回相同的JobId對於多個相同的調用Start操作，例如StartDocumentTextDetection。ClientRequestToken 符記有 7 天的存留期。在 7 天後，您可以再次使用它。如果您在符記的存留期內重新使用符記，會發生下列情況：
-
如果您使用的
Start操作與相同的輸入參數來重新使用符記，將傳回相同的JobId。不會再次執行任務，而 Amazon Textract 也不會傳送完成狀態到已註冊的 Amazon SNS 主題。 -
如果您以相同的
Start操作搭配些微變更的參數來重新使用符記，您會得到一個idempotentparametermismatchexception(HTTP 狀態碼：400) 例外狀況。 -
如果您以不同的
Start操作來重新使用符記，操作將可成功。
另一個可選參數是OutputConfig，它允許您調整輸出的放置位置。默認情況下，Amazon Textract 將在內部存儲結果，並且只能通過獲取 API 操作訪問。搭配OutputConfig，您可以設置將輸出發送到的存儲桶的名稱以及結果的文件前綴，您可以在其中下載結果。此外，您也可以設定KMSKeyID參數添加到客户託管密鑰來加密您的輸出。如果沒有此參數設置，Amazon Textract 將使用AWS 受管金鑰適用於 Amazon S3
注意
在使用此參數之前，請確保您具有輸出存儲桶的 PutObject 權限。此外，請確保您具有解密、ReEncrypt、GenerateDataKey 和 DescribeKey 權限AWS KMS鍵，如果您決定使用它。
對於 StartDocumentTextDetection 操作的回應為任務識別碼 (JobId)。使用JobId追蹤請求並在 Amazon Textract 發佈完成狀態到 Amazon SNS 主題後取得分析結果。以下是範例：
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
如果同時啟動太多作業，請調用StartDocumentTextDetectionRETURNLimitExceededException例外狀況 (HTTP 狀態碼：400)，直到數量同時執行任務的數量低於 Amazon Textract 服務限制。
如果您發現限制拒絕例外狀況發生且產生活動激增，請考慮使用 Amazon SQS 排列來管理傳入的請求。聯絡AWS如果您 Support 現同時進行的請求的平均數量無法由 Amazon SQS 排列控管，而您仍收到LimitExceededException例外狀況。
取得 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 Amazon Textract 發佈至 Amazon SNS 主題的狀態資訊，請使用以下其中一個選項：
-
AWS Lambda— 您可以訂AWS Lambda函數，以寫入 Amazon SNS 主題。當 Amazon Textract 通知 Amazon SNS 主題請求已完成時，將呼叫此功能。如果您需要伺服器端程式碼來處理文字偵測請求的結果，請使用 Lambda 函數。例如，您可能想要使用服務器端代碼來標註映像，或在傳回信息到客户端應用程式前針對檢測到的文本創建報告。
-
Amazon SQS— 您可以訂 Amazon SQS 佇列至 Amazon SNS 主題。接著請輪詢 Amazon SQS 排列以取得由 Amazon Textract 在文本檢測請求完成時發佈的完成狀態。如需詳細資訊，請參閱 檢測或分析多頁文檔中的文本。如果您只想從客户端應用程式呼叫 Amazon Textract 操作，請使用 Amazon SQS 佇列。
重要
我們不建議您透過重複呼叫 Amazon Textract 來取得請求完成狀態Getoperation. 這是因為 Amazon Textract 會限制Get操作，如果執行太多請求。如果您同時處理多個檔案，監控一個 SQS 排列的完成通知將會比輪詢 Amazon Textract 以獲得個別任務的狀態更容易且有效率。
獲取 Amazon Textract 檢測結果
若要取得文本檢測請求結果，首先請確認自 Amazon SNS 主題檢索的完成狀態為SUCCEEDED。然後呼叫 GetDocumentTextDetection，將傳遞自 StartDocumentTextDetection 傳回的 JobId 值。請求 JSON 格式類似於以下範例：
{ "JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3", "MaxResults": 10, "SortBy": "TIMESTAMP" }
JobId是文本檢測操作的標識符。由於文字偵測可以生成大量數據，請使用MaxResults來指定傳回結果的最大數量，以在單個Getoperation. 的預設預設預設值MaxResults是 1,000 個。如果您指定的值大於 1,000，將只會傳回 1,000 個結果。如果操作未返回所有結果，將傳回下一頁的分頁令牌。若要取得下一頁的結果，請在NextToken參數。
注意
Amazon Textract 會保留異步操作的結果 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 } ] }
