本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon Comprehend 见解的异步分析
以下各节使用Amazon Comprehend API 运行异步任务以分析 Amazon Comprehend 的见解。
**Topics**
+ [先决条件](#detect-topics-role-auth)
+ [开始分析任务](#how-start-job)
+ [监控分析任务](#how-monitor-progress)
+ [获取分析结果](#how-get-results)
## 先决条件
文档必须是 UTF-8-formatted 文本文件。您可以提交两种格式文件。您使用的格式取决于您要分析的文档类型，如下表中所述。
| 说明 | Format |
| --- | --- |
| 每个文件包含一个输入文档。这最适合大型文档的集合。 | 每个文件一个文档 |
| 输入是一个或多个文件。文件中的每一行都被视为一个文档。这最适合简短的文档，例如社交媒体帖子。
每行必须以换行符 (LF, \\n)、回车符 (CR, \\r) 或两者兼有 (CRLF, \\r\\n) 结尾。你不能使用 UTF-8 行分隔符 (u\+2028) 来结束一行。 | 每行一个文档 |
启动分析任务时，您需要指定输入数据的 S3 位置。URI 必须与您正在调用的 API 终端节点位于同一 AWS 区域。URI 可以指向单个文件，也可以是数据文件集合的前缀。有关更多信息，请参阅 [InputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html) 数据类型。
您必须授权 Amazon Comprehend 访问包含文档集和输出文件的 Amazon S3 存储桶。有关更多信息，请参阅 [Role-based 异步操作所需的权限](security_iam_id-based-policy-examples.md#auth-role-permissions)。
## 开始分析任务
要提交分析任务，请使用 Amazon Comprehend 控制台或相应的 `Start*` 操作：
+ [StartDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDominantLanguageDetectionJob.html)— 开始工作以检测馆藏中每个文档中的主要语言。有关文档中主要语言的更多信息，请参阅 [主要语言](how-languages.md)。
+ [StartEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEntitiesDetectionJob.html)— 启动一项工作以检测集合中每个文档中的实体。有关实体的更多信息，请参阅 [实体](how-entities.md)。
+ [StartKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartKeyPhrasesDetectionJob.html)— 开始工作以检测馆藏中每个文档中的关键短语。有关键短语的更多信息，请参阅 [关键短语](how-key-phrases.md)。
+ [StartPiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html)— 开始检测馆藏中每个文档中的个人身份信息 (PII)。有关 PII 的更多信息，请参阅 [检测 PII 实体](how-key-phrases.md)。
+ [StartSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartSentimentDetectionJob.html)— 开始一项工作以检测集合中每个文档中的情绪。有关情绪更多信息，请参阅 [情绪](how-sentiment.md)。
## 监控分析任务
`Start*` 操作会返回一个 ID，您可以用它来监控任务的进度。
要使用 API 监控进度，您可以使用两种操作之一，具体取决于您是要监控单个任务还是多个任务的进度。
要监控单个分析任务的进度，请使用 `Describe*` 操作。您提供 `Start*` 操作返回的任务 ID。`Describe*` 操作的响应包含任务状态的 `JobStatus` 字段。
要监控多个分析任务的进度，请使用 `List*` 操作。 `List*` 操作会返回您提交给 Amazon Comprehend 的任务列表。响应中包含每个任务的 `JobStatus` 字段，用于告诉您该任务的状态。
如果状态字段设置为 `COMPLETED` 或 `FAILED`， 则任务处理已完成。
要获取单个任务的状态，请使用 `Describe*` 操作进行您正在执行的分析。
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribePiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribePiiEntitiesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
要获取多个任务的状态，请使用 `List*` 操作进行您正在执行的分析。
+ [ListDominantLanguageDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListDominantLanguageDetectionJobs.html)
+ [ListEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListEntitiesDetectionJobs.html)
+ [ListKeyPhrasesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListKeyPhrasesDetectionJobs.html)
+ [ListPiiEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListPiiEntitiesDetectionJobs.html)
+ [ListSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListSentimentDetectionJobs.html)
要将结果限制为符合特定条件的任务，请使用 `List*` 操作的 `Filter` 参数。您可以按任务名称、任务状态或提交任务的日期和时间筛选结果。有关更多信息，请参阅 Amazon Comprehend API 参考中每个 `List*` 操作的 `Filter` 参数。
## 获取分析结果
分析任务完成后，使用 `Describe*` 操作获取结果的位置。如果任务状态为 `COMPLETED`，则响应将包含一个 `OutputDataConfig` 字段，该字段包含输出文件的 Amazon S3 位置。输出文件 `output.tar.gz` 是包含分析结果的压缩存档。
如果任务状态为 `FAILED`，则响应包括一个 `Message` 字段，用于描述任务未成功完成的原因。
要获取单个任务的状态，请使用相应的 `Describe*` 操作：
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
结果以单个文件形式返回，每个文档都有一个 JSON 结构。每个响应文件还包括状态字段设置为 `FAILED` 的任何任务的错误信息。
以下各节显示了两种输入格式的输出示例。
### 获取主要语言的检测结果
以下是检测主要语言的分析的输出文件示例。输入格式是每行一个文档。有关更多信息，请参阅 [DetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectDominantLanguage.html) 操作。
```
{"File": "0_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9514502286911011}, {"LanguageCode": "de", "Score": 0.02374090999364853}, {"LanguageCode": "nl", "Score": 0.003208699868991971}, "Line": 0}
{"File": "1_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9822712540626526}, {"LanguageCode": "de", "Score": 0.002621392020955682}, {"LanguageCode": "es", "Score": 0.002386554144322872}], "Line": 1}
```
以下是分析的输出示例，其中输入格式为每个文件一个文档：
```
{"File": "small_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9728053212165833}, {"LanguageCode": "de", "Score": 0.007670710328966379}, {"LanguageCode": "es", "Score": 0.0028472368139773607}]}
{"File": "huge_doc", "Languages": [{"LanguageCode": "en", "Score": 0.984955906867981}, {"LanguageCode": "de", "Score": 0.0026436643674969673}, {"LanguageCode": "fr", "Score": 0.0014206881169229746}]}
```
### 获取实体检测的结果
以下是检测文档中实体的分析输出文件示例。输入格式是每行一个文档。有关更多信息，请参阅 [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html) 操作。输出包含两条错误消息，一条针对过长的文档，另一条针对 UTF-8 格式不正确的文档。
```
{"File": "50_docs", "Line": 0, "Entities": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.9763959646224976, "Text": "Cluj-NapocaCluj-Napoca", "Type": "LOCATION"}"]}
{"File": "50_docs", "Line": 1, "Entities": [{"BeginOffset": 11, "EndOffset": 15, "Score": 0.9615424871444702, "Text": "Maat", "Type": "PERSON"}}]}
{"File": "50_docs", "Line": 2, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds maximum size limit 102400 bytes."}
{"File": "50_docs", "Line": 3, "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent lines are ignored."}
```
以下是分析的输出示例，其中输入的格式为每个文件一个文档。输出包含两条错误消息，一条针对过长的文档，另一条针对 UTF-8 格式不正确的文档。
```
{"File": "non_utf8.txt", "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent line are ignored."}
{"File": "small_doc", "Entities": [{"BeginOffset": 0, "EndOffset": 4, "Score": 0.645766019821167, "Text": "Maat", "Type": "PERSON"}]}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds size limit 102400 bytes."}
```
### 获取关键短语的检测结果
以下是检测文档中关键短语的分析输出文件示例。输入格式是每行一个文档。有关更多信息，请参阅 [DetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectKeyPhrases.html) 操作。
```
{"File": "50_docs", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}], "Line": 0}
```
以下是分析的输出示例，其中输入格式为每个文件一个文档。
```
{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}
```
### 获取个人身份信息 (PII) 的检测结果
以下是检测文档中 PII 实体的分析任务输出文件示例。输入格式是每行一个文档。
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ACCOUNT_NUMBER","BeginOffset":406,"EndOffset":411,"Score":0.693283}],"File":"doc.txt","Line":0}
{"Entities":[{"Type":"SSN","BeginOffset":1114,"EndOffset":1124,"Score":0.999999},{"Type":"EMAIL","BeginOffset":3742,"EndOffset":3775,"Score":0.999993},{"Type":"PIN","BeginOffset":4098,"EndOffset":4102,"Score":0.999995}],"File":"doc.txt","Line":1}
```
以下是分析的输出示例，其中输入的格式为每个文件一个文档。
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ROUTING","BeginOffset":279,"EndOffset":289,"Score":0.999999}],"File":"doc.txt"}
```
### 获取情绪检测的结果
以下是检测文档中情绪的分析输出文件示例。它包含一条错误消息，因为一个文档太长。输入格式是每行一个文档。有关更多信息，请参阅 [DetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectSentiment.html) 操作。
```
{"File": "50_docs", "Line": 0, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.002734508365392685, "Negative": 0.008935936726629734, "Neutral": 0.9841893315315247, "Positive": 0.004140198230743408}}
{"File": "50_docs", "Line": 1, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeded maximum size limit 5120 bytes."}
{"File": "50_docs", "Line": 2, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023119584657251835, "Negative": 0.0029857370536774397, "Neutral": 0.9866572022438049, "Positive": 0.008045154623687267}}
```
以下是分析的输出示例，其中输入格式为每个文件一个文档。
```
{"File": "small_doc", "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023450672160834074, "Negative": 0.0009663937962614, "Neutral": 0.9795311689376831, "Positive": 0.017157377675175667}}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeds the limit of 5120 bytes."}
```