本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
调用 Amazon Textract 异步操作
Amazon Textract 提供了一个异步 API，您可以使用它来处理 PDF 或 TIFF 格式的多页文档。您还可以使用异步操作来处理 JPEG、PNG、TIFF 或 PDF 格式的单页文档。
本主题中的信息使用文本检测操作来展示如何使用 Amazon Textract 异步操作。您可以对StartDocumentAnalysis和的文本分析操作使用相同的方法GetDocumentAnalysis。它也适用于StartExpenseAnalysis和GetExpenseAnalysis。
有关示例，请参阅检测或分析多页文档中的文本。
如果您正在分析借阅文档，则可以使用该StartLendingAnalysis操作对文档页面进行分类，并将分类页面发送给 Amazon Textract 分析操作。根据所分配的类别，将页面路由到分析操作。
您可以使用GetLendingAnalysis操作检索单个页面的结果，也可以使用检索分析摘要。GetLendingAnalysisSummary
Amazon Textract 异步处理存储在亚马逊 S3 存储桶中的文档。您可以通过调用Start操作开始处理，例如StartDocumentTextDetection。将请求完成状态发布到Amazon Simple Notification Service (Amazon SNS) 主题。要从亚马逊 SNS 主题中获取完成状态，您可以使用亚马逊简单队列服务 (Amazon SQS) Simple Queue 队列或函数。 AWS Lambda 在获得完成状态之后，请调用 Get 操作 (如 GetDocumentTextDetection) 以获取请求的结果。
默认情况下，异步调用的结果会被加密并存储在 Amazon Textract 拥有的存储桶中 7 天，除非您使用操作的参数指定 Amazon S3 存储桶。OutputConfig有关如何让 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 主题获取完成状态。
上图所示的分析文本的过程与分析文本的过程相同。 invoices/receipts您可以通过调用开始分析文本，StartDocumentAnalysis然后 invoices/receipts 通过调用开始分析。StartExpenseAnalysis您可以GetExpenseAnalysis分别通过调用GetDocumentAnalysis或来获得结果。
开始文本检测
您可以通过调用来启动 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 存储桶。 NotificationChannel包含亚马逊 SNS 主题的亚马逊资源名称 (ARN)，当文本检测请求完成时，亚马逊 Textract 会通知该主题。亚马逊 SNS 主题必须与您正在调用的 Amazon Textract 终端节点位于同一 AWS 区域。 NotificationChannel还包含允许亚马逊 Textract 向亚马逊 SNS 主题发布内容的角色的 ARN。通过创建 IAM 服务角色，您可以授予 Amazon Textract 发布您的亚马逊 SNS 主题的权限。有关更多信息，请参阅 为异步操作配置 Amazon Textract。
您还可以指定一个可选的输入参数JobTag，使您能够识别发布到 Amazon SNS 主题的已完成状态的任务或任务组。例如，您可以使用JobTag来标识正在处理的单据类型，例如纳税申报表或收据。
为防止分析任务意外重复，您可以选择性地提供幂等令牌 ClientRequestToken。如果您为提供了一个值ClientRequestToken，则JobId对于多次相同的Start操作调用，该Start操作将返回相同的值，例如StartDocumentTextDetection。ClientRequestToken 令牌的使用期限为 7 天。7 天后，您可以重复使用它。如果您在令牌使用期限内重复使用令牌，则会出现以下情况：
-
如果您对相同的
Start操作和相同的输入参数重复使用此令牌，则会返回相同的JobId。该任务不会再次执行，Amazon Textract 也不会向注册的亚马逊 SNS 主题发送完成状态。 -
如果您对相同的
Start操作重复使用此令牌，并且只进行了细微的输入参数更改，则会引发idempotentparametermismatchexception（HTTP 状态代码：400）异常。 -
如果您对其他
Start操作重复使用此令牌，操作将成功。
另一个可选参数是OutputConfig，它允许您调整输出的放置位置。默认情况下，Amazon Textract 将在内部存储结果，并且只能通过 Get API 操作进行访问。OutputConfig启用后，您可以设置输出将发送到的存储桶的名称和结果的文件前缀，您可以在其中下载结果。此外，您可以将KMSKeyID参数设置为客户管理的密钥以加密输出。如果不设置此参数，Amazon Textract 将使用适用于 Amazon S3 的 AWS 托管式密钥 服务器端加密
注意
在使用此参数之前，请确保您拥有输出存储桶的 PutObject 权限。此外，如果您决定使用该密钥 ReEncrypt GenerateDataKey，请确保您拥有该密 AWS KMS 钥的解密、、和 DescribeKey 权限。
对 StartDocumentTextDetection 操作的响应是作业标识符 (JobId)。在 Amazon Textract 发布亚马逊 SNS 主题的完成状态之后，使用JobId来跟踪请求并获取分析结果。以下是示例：
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
如果您同时启动的任务太多，则会调用StartDocumentTextDetection引发LimitExceededException异常（HTTP 状态代码：400），直到同时运行的任务数量低于 Amazon Textract 服务限制。
如果您发现由于活动激增而引发 LimitExceededException 异常，请考虑使用 Amazon SQS 队列来管理传入的请求。如果您发现 Amazon SQS 队列无法管理您的平均并发请求数，并且仍然收到LimitExceededException例外情况，请联系 AWS
Support。
获取亚马逊 Textract 分析请求的完成状态
Amazon Textract 向注册的亚马逊 SNS 主题发送分析完成通知。通知将在 JSON 字符串中包含操作的任务标识符和完成状态。成功的文本检测请求具有SUCCEEDED状态。例如，以下结果显示文本检测作业的成功处理。
{ "JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f", "Status": "SUCCEEDED", "API": "StartDocumentTextDetection", "JobTag": "Receipt", "Timestamp": 1543599965969, "DocumentLocation": { "S3ObjectName": "document", "S3Bucket": "bucket" } }
有关更多信息，请参阅 亚马逊 Textract 结果通知。
要获取 Amazon Textract 向亚马逊 SNS 主题发布的状态信息，请使用以下选项之一：
-
AWS Lambda – 您可订阅写入到 Amazon SNS 主题的 AWS Lambda 函数。当 Amazon Textract 通知亚马逊 SNS 主题请求已完成时，就会调用该函数。如果您希望服务器端代码处理文本检测请求的结果，请使用 Lambda 函数。例如，在将信息返回到客户端应用程序之前，您可能需要使用服务器端代码对图像进行注释或针对检测到的文本创建报告。
-
亚马逊 SQS — 您可以通过亚马逊 SQS 队列订阅亚马逊 SNS 主题。然后，您可以轮询亚马逊 SQS 队列，以检索 Amazon Textract 在文本检测请求完成时发布的完成状态。有关更多信息，请参阅 检测或分析多页文档中的文本。如果您只想从客户端应用程序调用 Amazon Textract 操作，请使用亚马逊 SQS 队列。
重要
我们不建议通过重复调用 Amazon Textr Get act 操作来获取请求完成状态。这是因为如果提出的请求过多，Amazon Textract 会限制该Get操作。如果您同时处理多个文档，则监控一个 SQS 队列以获取完成通知比单独轮询 Amazon Textract 以了解每项任务的状态更简单、更高效。
如果您已将账户配置为接收来自亚马逊简单通知服务 (Amazon SNS) Simple Notification SVICE 主题的结果通知或通过亚马逊 SQS 队列接收结果通知，则应将 Amazon Textract 的访问范围限制为仅限于您正在使用的资源，从而确保您的账户安全。这可以通过将信任策略附加到您的 IAM 服务角色来完成。有关如何执行此操作的信息，请参阅Cross-service 混乱的副手预防。
获取亚马逊 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 控制台创建和训练适配器。要应用您的适配器，请在调用 StartDocumentAnalysisAPI 操作时提供其 ID。调用该StartDocumentAnalysis操作时，您每页最多可以使用一个适配器。
"AdaptersConfig": { "Adapters": [ { "AdapterId": "2e9bf1c4aa31", "Version": "1", "Pages": [ "1" ] } ] }
