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