本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 调用 Amazon Textract 异步操作
Amazon Textract 提供了一个异步 API，您可以用它来处理 PDF 或 TIFF 格式的多页文档。您还可以使用异步操作来处理 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. 在获得完成状态之后，请调用 `Get` 操作 (如 [GetDocumentTextDetection](API_GetDocumentTextDetection.md)) 以获取请求的结果。
默认情况下，异步调用的结果将被加密并存储在 Amazon Textract 拥有的存储桶中 7 天，除非您使用操作指定 Amazon S3 存储桶`OutputConfig`参数。
下表显示了 Amazon Textract 支持的不同类型异步处理的相应启动和 Get 操作：
**启动/获取亚马Amazon Textract 异步操作的API 操作**
| 处理类型 | 启动 API | 获取 API |
| --- | --- | --- |
| 文本检测 | StartDocumentTextDetection | GetDocumentTextDetection |
| 文本分析 | StartDocumentAnalysis | GetDocumentAnalysis |
| 费用分析 | StartePense 分析 | GetExpense 分析 |
对于使用的示例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/zh_cn/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 Textract 在文本检测请求完成时通知的 Amazon SNS 主题的 Amazon Resource Name (ARN) 的资源名称 (ARN)。Amazon SNS 主题必须与您调用的 Amazon Textract 终端节点位于同一 AWS 区域。`NotificationChannel`还包含允许 Amazon Textract 向 Amazon SNS 主题进行发布的角色的 ARN。您可通过创建 IAM 服务角色为 Amazon Textract 发布您的 Amazon SNS 主题授予权限。有关更多信息，请参阅 [为异步操作配置 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` 操作重复使用此令牌，操作将成功。
另一个可选参数是`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"}
```
如果你同时开始太多的工作，请致电`StartDocumentTextDetection`提高`LimitExceededException`异常（HTTP 状态代码：400），直到并发运行的任务数量低于 Amazon Textract 服务限制。
如果您发现活动量猛增时会引发 LLimitExceededException 异常，请考虑使用 Amazon SQS 队列管理传入请求。联系人AWS如果 Amazon SQS 队列无法管理平均数量的并发请求，您仍会收到，请联系 Support。`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 结果通知](async-notification-payload.md)。
要获取 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 在文本检测请求完成后发布的完成状态。有关更多信息，请参阅 [检测或分析多页文档中的文本](async-analyzing-with-sqs.md)。如果您希望仅从客户端应用程序调用 Amazon Textract 操作，请使用 Amazon SQS 队列。
**重要**
我们建议不要通过反复调用 Amazon Textract 来获取请求完成状态。`Get`operation. 这是因为 Amazon Textract 限制了`Get`操作（如果提出的请求过多）。如果您同时处理多个文档，那么监控一个 SQS 队列中的完成通知比为每个任务的状态分别轮询 Amazon Textract 更加简单有效。
## 获取 Amazon Textract 文本检测结果
要获取文本检测请求的结果，请先确保从 Amazon SNS 主题检索的完成状态为`SUCCEEDED`. 然后调用 `GetDocumentTextDetection`，它将传递从 `StartDocumentTextDetection` 返回的 `JobId` 值。请求 JSON 类似于以下示例：
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
"MaxResults": 10,
"SortBy": "TIMESTAMP"
}
```
`JobId`是文本检测操作的标识符。由于文本检测可以生成大量数据，请使用`MaxResults`以指定要在单个结果中返回的最大数量`Get`operation. 的默认值`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
}
]
}
```