本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
呼叫 Amazon Textract 非同步操作
Amazon Textract 提供非同步 API，可用來處理 PDF 或 TIFF 格式的多頁文件。您也可以使用非同步操作來處理 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 函數。取得完成狀態後，您可以呼叫Get操作，例如 GetDocumentTextDetection，以取得請求的結果。
根據預設，非同步呼叫的結果會加密並存放在 Amazon Textract 擁有的儲存貯體中 7 天，除非您使用 操作的OutputConfig引數指定 Amazon S3 儲存貯體。如需如何讓 Amazon Textract 將加密文件傳送到 Amazon S3 儲存貯體的資訊，請參閱 輸出組態的許可。
下表顯示 Amazon Textract 支援的不同類型的非同步處理對應的開始和取得操作：
| 處理類型 | 啟動 API | 取得 API |
|---|---|---|
| 文字偵測 | StartDocumentTextDetection | GetDocumentTextDetection |
| 文字分析 | StartDocumentAnalysis | GetDocumentAnalysis |
| 費用分析 | StartExpenseAnalysis | GetExpenseAnalysis |
| 貸款分析 | StartLendingAnalysis | GetLendingAnalysis、GetLendingAnalysisSummary |
如需使用 AWS Lambda 函數的範例，請參閱使用 Amazon Textract 進行大規模文件處理
下圖顯示偵測存放在 Amazon S3 儲存貯體之文件映像中的文件文字的程序。在圖表內，佇列將自 Amazon SNS 主題取得完成狀態。
先前圖表顯示的程序與分析文字和發票/收據的程序相同。您可以透過呼叫 StartDocumentAnalysis 來開始分析文字，並透過呼叫 StartExpenseAnalysis 來開始分析發票/收據。您可以分別呼叫 GetDocumentAnalysis 或 GetExpenseAnalysis 來取得結果。
啟動文字偵測
您可以透過呼叫 StartDocumentTextDetection 來啟動 Amazon Textract 文字偵測請求。以下是由 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 Textract 在文字偵測請求完成時通知的 Amazon SNS 主題的 Amazon Resource Name (ARN)。Amazon SNS 主題必須與您呼叫的 Amazon Textract 端點位於相同的 AWS 區域。 NotificationChannel也包含允許 Amazon Textract 發佈至 Amazon SNS 主題之角色的 ARN。您可以透過建立 IAM 服務角色，將 Amazon Textract 發佈許可授予 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 會將結果存放在內部，而且只能由 Get API 操作存取。OutputConfig 啟用 後，您可以設定輸出將傳送至的儲存貯體名稱，以及結果的檔案字首，您可以在其中下載結果。此外，您可以將 KMSKeyID 參數設定為客戶受管金鑰，以加密您的輸出。如果沒有此參數集，Amazon Textract 將使用 AWS 受管金鑰 適用於 Amazon S3 的 加密伺服器端
注意
使用此參數之前，請確定您擁有輸出儲存貯體的 PutObject 許可。此外，如果您決定使用 AWS KMS 金鑰，請確定您具有金鑰的 Decrypt、ReEncrypt、GenerateDataKey 和 DescribeKey 許可。
對於 StartDocumentTextDetection 操作的回應為任務識別碼 (JobId)。在 Amazon Textract 將完成狀態發佈至 Amazon SNS 主題之後，使用 JobId追蹤請求並取得分析結果。以下是範例：
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
如果您同時啟動太多任務，請呼叫 StartDocumentTextDetection提出LimitExceededException例外狀況 (HTTP 狀態碼：400)，直到同時執行的任務數量低於 Amazon Textract 服務限制。
如果您發現 LimitExceededException 例外狀況隨著活動暴增而引發，請考慮使用 Amazon SQS 佇列來管理傳入的請求。如果您發現 Amazon SQS 佇列無法管理並行請求的平均數量，但仍收到LimitExceededException例外狀況，請聯絡 AWS Support。
取得 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：您可以註冊 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 Get操作以取得請求完成狀態。這是因為如果提出太多請求，Amazon Textract 會調節Get操作。如果您同時處理多個文件，監控完成通知的一個 SQS 佇列會比輪詢 Amazon Textract 個別每個任務的狀態更簡單且更有效率。
如果您已將 帳戶設定為從 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來指定在單一Get操作中傳回的最大結果數量。的預設值MaxResults為 1，000。如果您指定的值大於 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 操作時，每個頁面最多可使用一個轉接器。
"AdaptersConfig": { "Adapters": [ { "AdapterId": "2e9bf1c4aa31", "Version": "1", "Pages": [ "1" ] } ] }
